Services

Rhasspy is composed of independent services that communicate over MQTT using a superset of the Hermes protocol for these components:

The rhasspy-supervisor tool converts your profile into a runnable configuration for either supervisord or docker-compose.

Each service sends and receives a specific set of MQTT messages. Message payloads are typically JSON objects, except for the following messages whose payloads are binary WAV audio:

Most messages contain a string siteId property, whose default value is "default". Each service takes one or more --siteId <NAME> arguments that determine which site IDs the service will listen for. If not specified, the service will listen for all sites.

Internal vs. External MQTT

Rhasspy operates in one of two MQTT modes: internal or external. If you want to interact with Rhasspy over MQTT or use a server with satellites, it's important to understand the difference.

Internal MQTT

When Rhasspy is configured for internal MQTT (the default), a mosquitto broker is automatically started on port 12183 (override with --local-mqtt-port). All of Rhasspy's services will connect to this private broker and send messages through it.

Internal MQTT broker

If you're running Rhasspy inside Docker, make sure to add -p 12183:12183 to expose this port. Any downstream MQTT tools, like mosquitto_pub or NodeRED will need to have the MQTT port changed to 12183.

External MQTT

If you have your own MQTT broker that you'd like Rhasspy to share, configure it for external MQTT mode. In this mode, Rhasspy will simply connect all of its services to your broker.

External MQTT broker

Streaming audio from your microphone can sometimes cause congestion in an MQTT broker shared by many different services. For these scenarios, it's recommended to enable UDP audio streaming for both the Rhasspy audio input service and wake word service. This will disable MQTT audio streaming until the wake word has been detected, and again after a voice command has been spoken.

Web Server

Provides a graphical web interface for managing Rhasspy, and handles downloading language-specific profile artifacts.

Available Services

Dialogue Manager

Manages sessions initiated by a wake word detection or a startSession.

Hermes dialogue message flow

Available Services

Input Messages

Output Messages

Audio Input

Records audio from a microphone and streams it as WAV chunks over MQTT. See Audio Input for details.

Available Services

Input Messages

Output Messages

Wake Word Detection

Listens to WAV chunks and tries to detect a wake/hotword. See Wake Word for details.

Available Services

Input Messages

Output Messages

Speech to Text

Listens to WAV chunks and transcribes voice commands. See Speech to Text for details.

Available Services

Input Messages

Output Messages

Intent Recognition

Recognizes user intents from text input. See Intent Recognition for details.

Available Services

Input Messages

Output Messages

Intent Handling

Dispatches recognized intents to home automation software. See Intent Handling for details.

Available Services

Input Messages

Output Messages

Text to Speech

Generates spoken audio for a sentence. See Text to Speech for details.

Available Services

Input Messages

Output Messages

Audio Output

Plays WAV audio through an audio output device (speakers). See Audio Output for details.

Available Services

Input Messages

Output Messages

Rhasspy Supervisor

The rhasspy-supervisor tool transforms a Rhasspy profile.json file into:

  • A supervisord.conf file that can be run with supervisord
    • Runs services on the local machine
    • Requires you to have service executables in your PATH (e.g., rhasspy-server-hermes)
  • A docker-compose.yml file that can be run with docker-compose

When you start Rhasspy, it automatically runs rhasspy-supervisor to generate these files in your profile directory. From there, it depends on how you've installed Rhasspy.

Supervisord Restart

When running Rhasspy using supervisord, the process ID (PID) of the supervisord process will be written to a file named supervisord.pid in your profile directory. If a restart is requested from the web interface, a SIGHUP is sent to this PID, causing supervisord to re-read its configuration file and stop/start all child processes.

Docker Compose Restart

If you run Rhasspy using docker-compose, the restart process is a bit more complicated than with supervisord. This is due to the need to re-write docker-compose.yml on a profile change and bring the entire Docker container stack down and back up again.

A wrapper script like get-rhasspy.sh needs to monitor the profile directory for a file named .restart_docker. When a restart is requested via the web interface, this file is written and a timeout is set. The wrapper script should restart docker-compose (using down and then up), and then delete the .restart_docker file. Once its deleted, the web interface will reload the user's page.