The Snipsfile - snipsco/snipsmanager GitHub Wiki

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:

assistant_file: my_assistant.zip

A slightly more complex Snipsfile can look like this:

assistant_id: proj_XYZ
tts:
    service: snips
microphone:
    identifier: respeaker
    params:
        vendor_id: "2886"
        product_id: "0007"
mqtt_broker:
    hostname: <CUSTOM_MQTT_HOSTNAME>
    port: <CUSTOM_MQTT_PORT>
skills:
    - package_name: snipshue
      params:
          hostname: <PHILIPS_HUE_HOSTNAME>
          username: <PHILIPS_HUE_USERNAME>
          light_ids: [1, 2, 3, 4]
    - package_name: snipssmartercoffee
    - name: calculator
      intents:
          - intent: GetSum
            action: |
              {%
              sum = int(snips.intent.firstTerm) + int(snips.intent.secondTerm)
              snips.dialogue.speak(str(sum))
              %}

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. 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:
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:
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.
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. The Snips Manager 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:

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

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:

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 using the tts key:

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:

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:

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:

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:

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

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 {% and %} 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
  • dialogue is a helper giving you access to the dialogue manager, 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 dialogue instances will be accessible. For instance, a simple skill to say the sum of two numbers can look as follows:

skills:
  - name: calculator
    intents:
      - intent: GetSum
        action: |
          {%
          sum = int(snips.intent.firstTerm) + int(snips.intent.secondTerm)
          snips.dialogue.speak(str(sum))
          %}

If you want to create your own, you can start by looking at the multiple skills on the Snips organization or the ones developed by the community on Awesome Snips. You can also take a look at the snips-skill-skeleton to have a good point of reference when building your skill. We also have a simple skill creation tutorial but we will soon release detail tutorials for you to learn how to build more complex skills.