Usage

You can interact with Rhasspy in more ways than your voice:

Web Interface

A browser-based interface for Rhasspy is available on port 12101 by default (http://localhost:12101 if running locally). From this interface, you can test voice commands, add new voice commands, re-train, and edit your profile.

Top Bar

The top bar of the web interface lets you perform some global actions on Rhasspy, regardless of which page you have selected.

Web interface top bar

Test Page

Test voice and text commands.

Web interface speech page

Sentences Page

Add new voice commands to Rhasspy using the template syntax.

Web interface sentences page

Slots Page

Edit your slots lists.

Web interface slots page

Words Page

Teach Rhasspy how to pronounce new words.

Web interface words page

Settings Page

Simplified interface for editing your profile. Rhasspy will automatically restart after saving changes.

Web interface settings page

Advanced Page

Direct interface for editing your profile. Be careful! Entering invalid settings here can cause Rhasspy to not start.

Web interface advanced page

Home Assistant

Rhasspy communicates with Home Assistant directly over its REST API. Specifically, Rhasspy intents are POST-ed to the events endpoint.

If you have a Rhasspy intent named ChangeLightColor with name and color slots like in the RGB light example, then Home Assistant will receive an event of type rhasspy_ChangeLightColor whose event data is:

{
  "name": "bedroom",
  "color": "red"
}

when you say “set the bedroom to red”. You should write a custom automation with an event trigger to do something when this event arrives. Catching the example event would look like:

automation:
  trigger:
    platform: event
    event_type: rhasspy_ChangeLightColor
    event_data:
      color: red
  action:
    ...

You’ve now added offline, private voice commands to your Home Assistant. Happy automating!

Getting the Spoken Text

The Home Assistant event will contain two extra slots besides the ones you specify:

Node-RED

Rhasspy can interact directly with Node-RED directly through websockets. Simply add a websocket input and set the path to ws://<rhasspy>:12101/api/events/intent where <rhasspy> is the hostname or IP address of your Rhasspy server. Make sure to also set send/receive to “entire message”.

Node-RED websocket example

More example flows are available on Github.

WebSocket Events

Rhasspy supports multiple websocket event endpoints:

WebSocket Intents

Whenever a voice command is recognized, Rhasspy emits JSON events over a websocket connection available at ws://YOUR_SERVER:12101/api/events/intent (replace ws:// with wss:// if you’re using secure hosting). You can listen to these events in a Node-RED flow, and easily add offline, private voice commands to your home automation set up!

For the ChangLightState intent from the RGB Light Example, Rhasspy will emit a JSON event like this over the websocket:

{
  "text": "set the bedroom light to red",
  "intent": {
    "name": "ChangeLightColor",
    "confidence": 1
  },
  "entities": [
    {
      "entity": "name",
      "value": "bedroom"
    },
    {
      "entity": "color",
      "value": "red"
    }
  ],
  "slots": {
    "name": "bedroom",
    "color": "red"
  }
}

WebSocket Wake

When the wake word is detected, or Rhasspy is woken up via the /api/listen-for-command HTTP endpoint, a JSON event is emitted at ws://YOUR_SERVER:12101/api/events/wake (wss:// if using HTTPS) like:

{
    "wakewordId": "default",
    "siteId": "default"
}

The wakewordId is set using the model or file name of your wakeword model (e.g., porcupine for porcupine.ppn). The siteId comes from your mqtt.siteId profile setting.

WebSocket Transcriptions

Each time a voice command is transcribed, Rhasspy emits a JSON event at ws://YOUR_SERVER:12101/api/events/text (wss:// if using HTTPS) like:

{
    "text": "text from voice command",
    "wakewordId": "default",
    "siteId": "default"
}

The transcription is contained in the text property. wakewordId is the id of the wakeword that initiated the voice command (or default). The siteId comes from your mqtt.siteId profile setting.

Websocket MQTT Messages

You can send and receive MQTT messages over a special websocket endpoint at ws://YOUR_SERVER:12101/api/mqtt (wss:// if using HTTPS).

Subscribing to Topics

Send a JSON message with the following form:

{
  "type": "subscribe",
  "topic": "the/mqtt/topic"
}

Receiving Messages

When a message whose topic you have subscribed to is received, you will get a JSON message like:

{
  "topic": "/the/mqtt/topic",
  "payload": ...
}

You should only subscribe to messages whose payloads can be serialized in JSON.

Publishing Messages

To send a message to all of Rhasspy’s services, send a JSON message like:

{
  "type": "publish",
  "topic": "/the/mqtt/topic",
  "payload": ...
}

Single Topic

If you only need to receive messages from a single MQTT topic, you can connect to ws://YOUR_SERVER:12101/api/mqtt/<TOPIC> (wss:// if using HTTPS).

When a message is received on this topic, you will receive a JSON message like:

{
  "topic": "/the/mqtt/topic",
  "payload": ...
}

MQTT and Snips

Rhasspy is able to interoperate with Snips.AI services using the Hermes protocol over MQTT. See the description of Rhasspy’s services for details.

HTTP API

Rhasspy features a comprehensive HTTP API available at /api/, documented with OpenAPI 3 (Swagger). See the HTTP API reference for more details.

Secure Hosting with HTTPS

If you need to access Rhasspy’s web interface/API through HTTPS (formally SSL), you can provide a certificate and key file via command-line parameters or the Hass.io configuration.

If you’re running Rhasspy via Docker or in a virtual environment, add --certfile <CERT_FILE> and --keyfile <KEY_FILE> to the command-line arguments where <CERT_FILE> is your SSL certificate (PEM) and <KEY_FILE> is your SSL private key file.

You can generate a self-signed certificate with the following command:

openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365

After answering the series of questions, you should have cert.pem and key.pem in your current directory. Then run Rhasspy with:

<RHASSPY COMMAND> --certfile cert.pem --keyfile key.pem

The web interface will now be available at https://localhost:12101 and the web socket events at wss://localhost:12101/api/events/intent

In Hass.io, you will need to set the following options via the web interface or in your JSON configuration:

Command Line

A command-line client for the Rhasspy HTTP API is available in the rhasspy-client library.

You can install it with:

pip install rhasspy-client

and then run it:

rhasspy-client --help