snips-sam/docs/articles/snipsfile.md

The Snips Assistant Manager

---
layout: article
title:  "The Snipsfile"
permalink: /articles/snipsfile/
toc: Overview|Conventions|Pointing to an assistant|Hardware setup|Text-to-Speech|External MQTT brokers|Skills
---

A Snipsfile is a plain text file for declaratively describing your assistant. You can use a Snipsfile to declare the location of an assistant, the skills to install, your microphone and speaker models, the location of an external MQTT broker, and more.

## Overview

A Snipsfile can be very simple:

```yaml
assistant_file: my_assistant.zip
```

A slightly more complex Snipsfile can look like this:

```yaml
assistant_id: proj_01ap9812WUer9
tts:
    service: snips
microphone:
    identifier: respeaker
    params:
        vendor_id: "2886"
        product_id: "0007"
mqtt_broker:
    hostname: 192.168.1.22
    port: 1883
skills:
    - package_name: snipshue
      params:
          hostname: 192.168.100.20
          username: AzXYX391uurWWAzmMkff192Pwo
          light_ids: [1, 2, 3, 4]
    - package_name: snipssmartercoffee
    - name: calculator
      intents:
          - intent: GetSum
            action: |
              {% raw %}{%{% endraw %}
              sum = int(intent.firstTerm) + int(intent.secondTerm)
              tts_service.speak(str(sum))
              {% raw %}%}{% endraw %}
```

## Conventions

A Snipsfile is a plain text file adhering to the YAML format. It should be named `Snipsfile`, and nothing else. It must be placed at the root of your project.

## Pointing to an assistant

A Snipsfile can be used to declare the location of your assistant, as created in the [Snips Console](https://console.snips.ai). There are three ways to point to an assistant:

* Locally: if your assistant.zip has been downloaded onto your device, you can point to it using the `assistant_file` key. The path can be either absolute, or relative to the location of your Snipsfile:

```yaml
assistant_file: path/to/assistant.zip
```

* Publicly: if your assistant.zip is accessible on a public URL, you can point to it using the `assistant_url` key:

```yaml
assistant_url: https://example.com/my_assistant.zip
```

* On the console: to avoid having to download your assistant every time an update is made, you can point to is directly in the console, using the `assistant_id` key. The value should be the ID of your assistant (starting with `proj_`). You can grab it in the URL in your browser.

```yaml
assistant_id: proj_XYZ
```

## Hardware setup

A Snipsfile can also be used to easily set up your hardware configuration, such as the microphone and speaker you are using. Sam will automatically install drivers and generate configuraiton files for known models.

### Microphone

If you are using a microphone that requires a custom configuration, such as a ReSpeaker 7-Mic Array, you can streamline the configuration process in the Snipsfile. For instance, the following section will set up a ReSpeaker:

```yaml
microphone:
    identifier: respeaker
    params:
        vendor_id: "2886"
        product_id: "0007"
```

Note that this section will be generated on your behalf if you use the `sam setup microphone` command.

For most microphones, no configuration is needed as they will work off-the-shelf. Currently, the following special microphones are supported:

- ReSpeaker 7-Mic Array
- Matrix Voice
- Jabra
- Adafruit SpeakerBonnet

For more information on microphones, check out the [Microphone Setup Guide]({{ site.baseurl }}/articles/microphone-setup/).

### Speaker

If you are using another speaker than the onboard speaker, this can be specified in the Snipsfile. Here is an example for a Jabra Speak microphone array, which also has an integrated speaker:

```yaml
speaker:
    identifier: jabra
```

## Text-to-Speech

By default, Snips uses its own on-device TTS engine. You may change this to the cloud-based [Google Cloud Speech](https://cloud.google.com/speech/) using the `tts` key:

```yaml
tts:
    service: google
```

Note that this configuration will only work if your device has an Internet connection. More providers will be added soon.

## External MQTT brokers

By default, the Snips SDK launches an MQTT broker locally. You can tell Snips to use an external MQTT broker using the `mqtt_broker` key:

```yaml
mqtt_broker:
    hostname: IP_OR_HOSTNAME
    port: MQTT_PORT
```

Here, `hostname` can either be an IP address or a hostname.

## Skills

A Snipsfile can be used to tell how your assistant should react upon receiving an intent from the Snips platform. This can be done by adding skills to your assistant, which are pieces of code that are triggered under certain specific conditions.

### External skill references

Skills are declared in a `skills` section. A simple example is the following:

```yaml
skills:
  - url: github.com/snipsco/snips-skill-hue
  - url: github.com/snipsco/snips-skill-sonos
  - url: github.com/snipsco/snips-skill-nest
```

The `url` key points to a skill residing on a public repository.

### Configuring skills

Some skills require parameters, such as an API key or the IP of a device. This is specified in a sub section `params`:

```yaml
skills:
  - url: github.com/snipsco/snips-smarter-coffee
    params:
      hostname: 192.168.163.105
```

### Adding custom behaviours

The above skills are configured to react to specific intents for various bundles on the console. For instance, the `snips-skill-hue` skill above will react to intents such as `ActivateObject`. If you want to override or extend this behaviour, you can do so by adding a sub section `intents`:

```yaml
skills:
  - url: github.com/snipsco/snips-skill-hue
    intents:
      - intent: LightsOn
        action: "turn_on"
      - intent: SetLightColor
        action: |
          {% raw %}{%{% endraw %}
          if intent.objectColor != None:
            skill.set_color_name(intent.objectColor)
          else:
            tts_service.speak("You did not provide a color")
          {% raw %}%}{% endraw %}
```

Here, you are telling Snips to call the skill's `turn_on()` function when receving a `LightsOn` intent. The second item, slightly more complex, adds logic to the handler. In such as block, delimited by the `{% raw %}{%{% endraw %}` and `{% raw %}%}{% endraw %}` symbols, you may call any code (current example being Python). There are three object you have access to:

- `intent` is an instance of the intent that was received, and which gives you access to further information such as its slot values
- `skill` is an instance of the skill, upon which you can call any public functions
- `tts_service` is a helper giving you access to TTS, via the `speak()` method

### Plain code blocks

You do not need to point to an external skill. In fact, your may entirely remove a reference to a skill, and just provide a code block to be executed when an intent is detected. In this case, only the `intent` and `tts_services` instances will be accessible. For instance, a simple skill to say the sum of two numbers can look as follows:

```yaml
skills:
  - name: calculator
    intents:
      - intent: GetSum
        action: |
          {% raw %}{%{% endraw %}
          sum = int(intent.firstTerm) + int(intent.secondTerm)
          tts_service.speak(str(sum))
          {% raw %}%}{% endraw %}
```

If you want to create your own, complex skills with default behaviours, check out the [Creating A Skill]({{ site.baseurl }}/articles/creating-a-skill) article.