API reference

This is the API documentation of the Rhasspy Hermes package, covering all modules and classes.

rhasspyhermes.asr

Messages for automated speech recognition.

class rhasspyhermes.asr.AsrAudioCaptured(wav_bytes: bytes)[source]

Bases: rhasspyhermes.base.Message

Audio captured from ASR session.

wav_bytes

Captured audio in WAV format

Type

bytes

classmethod get_session_id(topic: str) → Optional[str][source]

Get session id from a topic

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod is_binary_payload()bool[source]

True if payload is not JSON.

classmethod is_session_in_topic()bool[source]

True if session id is in topic.

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

payload() → Union[str, bytes][source]

Get binary/string for this message.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Error from ASR component.

site_id

The id of the site where the error occurred

Type

str = “default”

error

A description of the error that occurred

Type

str

context

Additional information on the context in which the error occurred

Type

Optional[str] = None

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrRecordingFinished(site_id: str = 'default', session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent after silence has been detected, and before transcription occurs.

site_id

The id of the site where the ASR is listening

Type

str = “default”

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrStartListening(site_id: str = 'default', session_id: Optional[str] = None, lang: Optional[str] = None, stop_on_silence: bool = True, send_audio_captured: bool = False, wakeword_id: Optional[str] = None, intent_filter: Optional[List[str]] = None)[source]

Bases: rhasspyhermes.base.Message

Tell the ASR component to start listening.

site_id

The site that must be listened too

Type

str = “default”

session_id

An optional session id if there is a related session

Type

Optional[str] = None

stop_on_silence

If true, ASR should automatically detect end of voice command

Type

bool = True

send_audio_captured

If true, ASR emits asr/audioCaptured message with recorded audio

Type

bool = False

wakeword_id

Optional id of wakeword used to activate ASR

Type

Optional[str] = None

intent_filter

A list of intent names to restrict the ASR on

Type

Optional[List[str]] = None

lang

Language of the incoming audio stream. Typically set in hotword detected or dialogue startSession messages.

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrStopListening(site_id: str = 'default', session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Tell the ASR component to stop listening.

site_id

The id of the site where the ASR should stop listening

Type

str = “default”

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrTextCaptured(text: str, likelihood: float, seconds: float, site_id: str = 'default', session_id: Optional[str] = None, wakeword_id: Optional[str] = None, asr_tokens: Optional[List[List[rhasspyhermes.nlu.AsrToken]]] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Full ASR transcription results.

text

The text captured

Type

str

likelihood

The likelihood of the capture

Type

float

seconds

The duration it took to do the processing

Type

float

site_id

The id of the site where the text was captured

Type

str = “default”

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

wakeword_id

Optional id of wakeword used to activate ASR

Type

Optional[str] = None

asr_tokens

Structured description of the tokens the ASR captured on for this intent

Type

Optional[List[List[AsrToken]]] = None

lang

Language of the session

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrToggleOff(site_id: str = 'default', reason: rhasspyhermes.asr.AsrToggleReason = <AsrToggleReason.UNKNOWN: ''>)[source]

Bases: rhasspyhermes.base.Message

Deactivate the ASR component.

site_id

The id of the site where ASR should be turned off

Type

str = “default”

reason

Reason why ASR was toggled off

Type

AsrToggleReason = UNKNOWN

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrToggleOn(site_id: str = 'default', reason: rhasspyhermes.asr.AsrToggleReason = <AsrToggleReason.UNKNOWN: ''>)[source]

Bases: rhasspyhermes.base.Message

Activate the ASR component.

site_id

The id of the site where ASR should be turned on

Type

str = “default”

reason

Reason why ASR was toggled on

Type

AsrToggleReason = UNKNOWN

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrToggleReason[source]

Bases: str, enum.Enum

Reason for ASR toggle on/off.

UNKNOWN

Overrides all other reasons

DIALOGUE_SESSION

Dialogue session is active

PLAY_AUDIO

Audio is currently playing

TTS_SAY

Text to speech system is currently speaking

class rhasspyhermes.asr.AsrTrain(graph_path: str, id: Optional[str] = None, graph_format: Optional[str] = None, sentences: Optional[Dict[str, str]] = None, slots: Optional[Dict[str, List[str]]] = None)[source]

Bases: rhasspyhermes.base.Message

Request to retrain ASR from intent graph.

graph_path

Path to the graph file

Type

str

id

Unique id for training request

Type

Optional[str] = None

graph_format

Optional format of the graph file

Type

typing.Optional[str] = None

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.asr.AsrTrainSuccess(id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Result from successful training.

id

Unique id from training request

Type

Optional[str] = None

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

rhasspyhermes.audioserver

Messages for audio recording and playback.

class rhasspyhermes.audioserver.AudioDevice(mode: rhasspyhermes.audioserver.AudioDeviceMode, id: str, name: Optional[str] = None, description: Optional[str] = None, working: Optional[bool] = None)[source]

Bases: object

Description of an audio device.

mode

Recording or playback device

Type

AudioDeviceMode

id

Unique id of audio device

Type

str

name

Optional human-readable name of audio device

Type

Optional[str] = None

description

Optional human-readable description of audio device

Type

Optional[str] = None

working

Status of audio device if tested

Type

Optional[bool] = None

class rhasspyhermes.audioserver.AudioDeviceMode[source]

Bases: str, enum.Enum

Mode of an audio device.

INPUT

Recording device

OUTPUT

Playback device

class rhasspyhermes.audioserver.AudioDevices(devices: List[rhasspyhermes.audioserver.AudioDevice], site_id: str = 'default', id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Response to getDevices.

devices

Description of requested device types

Type

List[AudioDevice]

id

Unique id from request

Type

Optional[str] = None

site_id

Id of site where devices are located

Type

str = “default”

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioFrame(wav_bytes: bytes)[source]

Bases: rhasspyhermes.base.Message

Recorded frame of audio.

wav_bytes

Recorded audio frame in WAV format

Type

bytes

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod get_wav_duration(wav_bytes: bytes)float[source]

Return the real-time duration of a WAV file

classmethod is_binary_payload()bool[source]

True if payload is not JSON.

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

classmethod iter_wav_chunked(wav_io: BinaryIO, frames_per_chunk: int, live_delay: bool = False) → Iterable[bytes][source]

Split single WAV into multiple WAV chunks

payload() → Union[str, bytes][source]

Get binary/string for this message.

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioGetDevices(modes: List[rhasspyhermes.audioserver.AudioDeviceMode], site_id: str = 'default', id: Optional[str] = None, test: bool = False)[source]

Bases: rhasspyhermes.base.Message

Get details for available audio devices.

modes

Device types to get information about

Type

List[AudioDeviceMode]

id

Unique id to be returned in response

Type

Optional[str] = None

site_id

Id of the site where devices are located

Type

str = “default”

test

True if devices should be tested

Type

bool = False

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioPlayBytes(wav_bytes: bytes)[source]

Bases: rhasspyhermes.base.Message

Play WAV sound on specific site.

wav_bytes

Audio to play in WAV format

Type

bytes

classmethod get_request_id(topic: str)str[source]

Get request id from a topic

classmethod get_session_id(topic: str)str[source]

Get session id from a topic

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod is_binary_payload()bool[source]

True if payload is not JSON.

classmethod is_session_in_topic()bool[source]

True if session id is in topic.

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

payload() → Union[str, bytes][source]

Get binary/string for this message.

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioPlayError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Error from audio output component.

error

A description of the error that occurred

Type

str

site_id

The id of the site where the error occurred

Type

str = “default”

context

Additional information on the context in which the error occurred

Type

Optional[str] = None

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.audioserver.AudioPlayFinished(id: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent when audio service has finished playing a sound.

id

Request identifier for the request passed from playBytes topic

Type

str : Optional[str] = None

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

classmethod get_site_id(topic: str) → Optional[str][source]

Get site_id from a topic

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioRecordError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Error from audio input component.

error

A description of the error that occurred

Type

str

site_id

The id of the site where the error occurred

Type

str = “default”

context

Additional information on the context in which the error occurred

Type

Optional[str] = None

session_id

The id of the session, if there is an active session

Type

Optional[str] = None

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.audioserver.AudioSessionFrame(wav_bytes: bytes)[source]

Bases: rhasspyhermes.base.Message

Recorded audio frame for a specific session.

wav_bytes

Audio frame in WAV format

Type

bytes

classmethod get_session_id(topic: str) → Optional[str][source]

Get session id from a topic

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod is_binary_payload()bool[source]

True if payload is not JSON.

classmethod is_session_in_topic()bool[source]

True if session id is in topic.

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

payload() → Union[str, bytes][source]

Get binary/string for this message.

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioSetVolume(volume: float, site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Set audio output volume at a site

volume

The volume scale to set (0 = off, 1 = full volume)

Type

float

site_id

The id of the site where the error occurred

Type

str = “default”

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

class rhasspyhermes.audioserver.AudioSummary(debiased_energy: float, is_speech: Optional[bool] = None)[source]

Bases: rhasspyhermes.base.Message

Summary of recent audio frame(s) for diagnostic purposes.

debiased_energy: float

Audio energy computed using get_debiased_energy

is_speech: typing.Optional[bool] = None

True/false if VAD detected speech

classmethod get_debiased_energy(audio_data: bytes)float[source]

Compute RMS of debiased audio.

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

classmethod topic(**kwargs)str[source]

Get topic for message.

class rhasspyhermes.audioserver.AudioToggleOff(site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Deactivate audio output system.

site_id

Id of site where audio should be turned on

Type

str = “default”

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

The MQTT topic for this message type

Return type

str

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> NluIntent.topic()
'hermes/intent/#'
class rhasspyhermes.audioserver.AudioToggleOn(site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Activate audio output system.

site_id

Id of site where audio should be turned off

Type

str = “default”

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

The MQTT topic for this message type

Return type

str

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> NluIntent.topic()
'hermes/intent/#'
class rhasspyhermes.audioserver.SummaryToggleOff(site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Deactivate sending of audio summaries.

site_id

Id of site where audio is being recorded

Type

str = “default”

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

The MQTT topic for this message type

Return type

str

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> NluIntent.topic()
'hermes/intent/#'
class rhasspyhermes.audioserver.SummaryToggleOn(site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Activate sending of audio summaries.

site_id

Id of site where audio is being recorded

Type

str = “default”

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

The MQTT topic for this message type

Return type

str

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> NluIntent.topic()
'hermes/intent/#'

rhasspyhermes.base

Support for the Rhasspy Hermes protocol.

The Rhasspy Hermes protocol is an extension of the Snips Hermes protocol.

class rhasspyhermes.base.Message(**kwargs)[source]

Bases: dataclasses_json.api.DataClassJsonMixin

Base class for Hermes messages.

All classes implementing Hermes messages are subclasses of this class.

classmethod get_session_id(topic: str) → Optional[str][source]

Extract session id from message topic.

Parameters

topic – message topic

Returns

The optional session id for this message topic

Return type

Optional[str]

Example

>>> from rhasspyhermes.audioserver import AudioSessionFrame
>>> topic = "hermes/audioServer/satellite/abcd/audioSessionFrame"
>>> AudioSessionFrame.get_session_id(topic)
'abcd'
classmethod get_site_id(topic: str) → Optional[str][source]

Extract site id from message topic.

Parameters

topic – message topic

Returns

The optional site id for this message topic

Return type

Optional[str]

Example

>>> from rhasspyhermes.audioserver import AudioSessionFrame
>>> topic = "hermes/audioServer/satellite/abcd/audioSessionFrame"
>>> AudioSessionFrame.get_site_id(topic)
'satellite'
classmethod is_binary_payload()bool[source]

Check for binary payload of message.

Returns

True if message payload is not JSON

Return type

bool

Example

>>> from rhasspyhermes.audioserver import AudioFrame
>>> AudioFrame.is_binary_payload()
True
classmethod is_session_in_topic()bool[source]

Check for session id in topic.

Returns

True if session id is part of topic

Return type

bool

Example

>>> from rhasspyhermes.asr import AsrAudioCaptured
>>> AsrAudioCaptured.is_session_in_topic()
True
classmethod is_site_in_topic()bool[source]

Check for site id in topic.

Returns

True if site id is part of topic

Return type

bool

Example

>>> from rhasspyhermes.asr import AsrTrain
>>> AsrTrain.is_site_in_topic()
True
classmethod is_topic(topic: str)bool[source]

Check whether topic is for this message type.

Parameters

topic – message topic

Returns

True if topic is for this message type

Return type

bool

Example

>>> from rhasspyhermes.wake import HotwordDetected
>>> HotwordDetected.is_topic("hermes/hotword/precise/detected")
True
payload() → Union[str, bytes][source]

Get the payload for this message.

Returns

The payload as a JSON string or bytes

Return type

Union[str, bytes]

Example

>>> from rhasspyhermes.handle import HandleToggleOn
>>> on = HandleToggleOn(site_id='satellite')
>>> on.payload()
'{"siteId": "satellite"}'
classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

The MQTT topic for this message type

Return type

str

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> NluIntent.topic()
'hermes/intent/#'

rhasspyhermes.cli

Methods for command-line parsing of a Rhasspy Hermes client.

rhasspyhermes.cli.add_hermes_args(parser: argparse.ArgumentParser)[source]

Add shared Hermes/MQTT command-line arguments.

These are useful arguments for every Hermes client, concerning the connection, authentication, site IDs, debugging and logging.

rhasspyhermes.cli.connect(client: paho.mqtt.client.Client, args: argparse.Namespace)[source]

Connect to an MQTT broker with supplied arguments.

rhasspyhermes.cli.setup_logging(args: argparse.Namespace)[source]

Set up Python logging.

rhasspyhermes.client

MQTT Hermes client base class

class rhasspyhermes.client.HermesClient(client_name: str, mqtt_client, site_ids: Optional[List[str]] = None, sample_rate: int = 16000, sample_width: int = 2, channels: int = 1, loop: Optional[asyncio.events.AbstractEventLoop] = None)[source]

Bases: object

Base class for Hermes MQTT clients

convert_wav(wav_bytes: bytes, sample_rate: Optional[int] = None, sample_width: Optional[int] = None, channels: Optional[int] = None)bytes[source]

Converts WAV data to required format with sox. Return raw audio.

async handle_messages_async(loop: Optional[asyncio.events.AbstractEventLoop] = None)[source]

Handles MQTT messages in event loop.

maybe_convert_wav(wav_bytes: bytes, sample_rate: Optional[int] = None, sample_width: Optional[int] = None, channels: Optional[int] = None)bytes[source]

Converts WAV data to required format if necessary. Returns raw audio.

mqtt_on_connect(client, userdata, flags, rc)[source]

Connected to MQTT broker.

mqtt_on_disconnect(client, userdata, flags, rc)[source]

Automatically reconnect when disconnected.

mqtt_on_message(client, userdata, msg)[source]

Received message from MQTT broker.

on_message(message: rhasspyhermes.base.Message, site_id: Optional[str] = None, session_id: Optional[str] = None, topic: Optional[str] = None) → AsyncIterable[Union[rhasspyhermes.base.Message, Tuple[rhasspyhermes.base.Message, Mapping[str, Any]], None]][source]

Override to handle Hermes messages.

on_message_blocking(message: rhasspyhermes.base.Message, site_id: Optional[str] = None, session_id: Optional[str] = None, topic: Optional[str] = None) → AsyncIterable[Union[rhasspyhermes.base.Message, Tuple[rhasspyhermes.base.Message, Mapping[str, Any]], None]][source]

Override to handle Hermes messages and block.

async on_raw_message(topic: str, payload: bytes)[source]

Override to handle MQTT messages.

classmethod parse_mqtt_message(topic: str, payload: Union[str, bytes], subscribed_types: Iterable[Type[rhasspyhermes.base.Message]], logger=None) → Iterable[Tuple[rhasspyhermes.base.Message, Optional[str], Optional[str]]][source]

Deserialize MQTT message into Hermes object.

publish(message: rhasspyhermes.base.Message, **topic_args)[source]

Publish a Hermes message to MQTT.

async publish_all(async_generator: AsyncIterable[Union[rhasspyhermes.base.Message, Tuple[rhasspyhermes.base.Message, Mapping[str, Any]], None]])[source]

Enumerate all messages in an async generator publish them

reduce_noise(audio_data: bytes, noise_profile: pathlib.Path, amount: float = 0.5)bytes[source]

Reduce noise in raw audio using sox noise profile.

subscribe(*message_types: Type[rhasspyhermes.base.Message], **topic_args)[source]

Subscribe to one or more Hermes messages.

subscribe_topics(*topics)[source]

Subscribe to one or more MQTT topics.

to_wav_bytes(audio_data: bytes, sample_rate: Optional[int] = None, sample_width: Optional[int] = None, channels: Optional[int] = None)bytes[source]

Wrap raw audio data in WAV.

valid_site_id(site_id: Optional[str])[source]

True if site id is valid for this client.

rhasspyhermes.dialogue

Messages for the Hermes dialogue manager.

class rhasspyhermes.dialogue.DialogueAction(can_be_enqueued: bool, type: rhasspyhermes.dialogue.DialogueActionType = <DialogueActionType.ACTION: 'action'>, text: Optional[str] = None, intent_filter: Optional[List[str]] = None, send_intent_not_recognized: bool = False)[source]

Bases: dataclasses_json.api.DataClassJsonMixin

Dialogue session action.

can_be_enqueued: bool = None

If true, the session will start when there is no pending one on this site. Otherwise, the session is just dropped if there is running one.

intent_filter: Optional[List[str]] = None

A list of intents names to restrict the NLU resolution on the first query.

send_intent_not_recognized: bool = False

Indicates whether the dialogue manager should handle non-recognized intents by itself or send them for the client to handle.

text: Optional[str] = None

Text that the TTS should say at the beginning of the session.

type: rhasspyhermes.dialogue.DialogueActionType = 'action'

This value is always DialogueActionType.ACTION.

class rhasspyhermes.dialogue.DialogueActionType[source]

Bases: str, enum.Enum

Type of session init objects.

ACTION = 'action'

Use this type when you need the user to respond.

NOTIFICATION = 'notification'

Use this type when you only want to inform the user of something without expecting a response.

class rhasspyhermes.dialogue.DialogueConfigure(intents: List[rhasspyhermes.dialogue.DialogueConfigureIntent], site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Enable/disable specific intents for future dialogue sessions.

If an intent is enabled, the rhasspyhermes.nlu.NluIntent message is triggered when the intent is detected.

Rhasspy enables all intents by default unless specified otherwise.

MQTT message

Topic

hermes/dialogueManager/configure

Payload (JSON)

Key

Type

Description

intents

List of JSON Objects

The list of intents and whether to enable/disable them.

siteId

String

The id of the site to configure.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/dialogueManager/configure' -m '{"intents": [{"intentId": "GetTime", "enable": true}, {"intentId": "GetTemperature", "enable": false}], "siteId": "livingroom"}'

Example

>>> from rhasspyhermes.dialogue import DialogueConfigureIntent, DialogueConfigure
>>> configure = DialogueConfigure([DialogueConfigureIntent("GetTime", True), DialogueConfigureIntent("GetTemperature", False)], "livingroom")
>>> configure
DialogueConfigure(intents=[DialogueConfigureIntent(intent_id='GetTime', enable=True), DialogueConfigureIntent(intent_id='GetTemperature', enable=False)], site_id='livingroom')
>>> configure.payload()
'{"intents": [{"intentId": "GetTime", "enable": true}, {"intentId": "GetTemperature", "enable": false}], "siteId": "livingroom"}'
intents: typing.List[DialogueConfigureIntent] = None

The list of intents and whether to enable/disable them.

site_id: str = 'default'

The id of the site to configure.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/configure"

Return type

str

class rhasspyhermes.dialogue.DialogueConfigureIntent(intent_id: str, enable: bool)[source]

Bases: object

Enable/disable a specific intent in a DialogueConfigure message.

enable: bool = None

True if the intent should be enabled.

intent_id: str = None

Name of the intent to enable/disable.

class rhasspyhermes.dialogue.DialogueContinueSession(session_id: str, custom_data: Optional[str] = None, text: Optional[str] = None, intent_filter: Optional[List[str]] = None, send_intent_not_recognized: bool = False, slot: Optional[str] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent when a dialogue session should be continued.

You should send this message after receiving a rhasspyhermes.nlu.NluIntent message if you want to continue the session. This can be used for example to ask additional information to the user.

Make sure to use the same sessionId as the original rhasspyhermes.nlu.NluIntent message.

MQTT message

Topic

hermes/dialogueManager/continueSession

Payload (JSON)

Key

Type

Description

sessionId

String

The id of the session to continue.

customData

String (optional)

An update to the session’s custom data. If not provided, the custom data will stay the same.

text

String (optional)

The text the TTS should say to start this additional request of the session.

intentFilter

List of Strings (optional)

A list of intent names to restrict the NLU resolution on the answer of this query.

sendIntentNotRecognized

Boolean

Indicates whether the dialogue manager should handle non recognized intents by itself or send them for the client to handle.

slot

String (optional)

Unused.

lang

String (optional)

Language of the session. Leave empty to use setting from start of session.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/dialogueManager/continueSession' -m '{"sessionId": "foobar", "customData": null, "text": "Are you sure?", "intentFilter": null, "sendIntentNotRecognized": false, "slot": null, "lang": null}'

Example

>>> from rhasspyhermes.dialogue import DialogueContinueSession
>>> session = DialogueContinueSession(session_id="foobar", text="Are you sure?")
>>> session
DialogueContinueSession(session_id='foobar', custom_data=None, text='Are you sure?', intent_filter=None, send_intent_not_recognized=False, slot=None, lang=None)
>>> session.payload()
'{"sessionId": "foobar", "customData": null, "text": "Are you sure?", "intentFilter": null, "sendIntentNotRecognized": false, "slot": null, "lang": null}'
custom_data: Optional[str] = None

An update to the session’s custom data. If not provided, the custom data will stay the same.

intent_filter: Optional[List[str]] = None

A list of intent names to restrict the NLU resolution on the answer of this query.

lang: Optional[str] = None

Language of the session. Leave empty to use setting from start of session.

Note

This is a Rhasspy-only attribute.

send_intent_not_recognized: bool = False

Indicates whether the dialogue manager should handle non recognized intents by itself or send them for the client to handle.

session_id: str = None

The id of the session to continue.

slot: Optional[str] = None

Unused.

text: Optional[str] = None

The text the TTS should say to start this additional request of the session.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/continueSession"

Return type

str

class rhasspyhermes.dialogue.DialogueEndSession(session_id: str, text: Optional[str] = None, custom_data: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent when a dialogue session should be ended.

You should send this message after receiving a rhasspyhermes.nlu.NluIntent message if you want to end the session.

Make sure to use the same sessionId as the original rhasspyhermes.nlu.NluIntent message.

MQTT message

Topic

hermes/dialogueManager/continueSession

Payload (JSON)

Key

Type

Description

sessionId

String

The id of the session to continue.

customData

String (optional)

An update to the session’s custom data. If not provided, the custom data will stay the same.

text

String (optional)

The text the TTS should say to end the session.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/dialogueManager/endSession' -m '{"sessionId": "foobar", "customData": null, "text": "OK, turning off the light"}'

Example

>>> from rhasspyhermes.dialogue import DialogueEndSession
>>> session = DialogueEndSession(session_id="foobar", text="OK, turning off the light")
>>> session
DialogueEndSession(session_id='foobar', text='OK, turning off the light', custom_data=None)
>>> session.payload()
'{"sessionId": "foobar", "text": "OK, turning off the light", "customData": null}'
custom_data: Optional[str] = None

An update to the session’s custom data. If not provided, the custom data will stay the same.

session_id: str = None

The id of the session to end.

text: Optional[str] = None

The text the TTS should say to end the session.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/endSession"

Return type

str

class rhasspyhermes.dialogue.DialogueError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

This message is published by the dialogue manager component if an error has occurred.

MQTT message

Topic

hermes/error/dialogueManager

Payload (JSON)

Key

Type

Description

error

String

A description of the error that occurred.

siteId

String

The id of the site where the error occurred.

context

String (optional)

Additional information on the context in which the error occurred.

sessionId

String (optional)

The id of the session, if there is an active session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/error/dialogueManager'

Example

>>> from rhasspyhermes.dialogue import DialogueError
>>> dialogue_error = DialogueError(error="Unexpected error")
>>> dialogue_error.topic()
'hermes/error/dialogueManager'
>>> dialogue_error.payload()
'{"error": "Unexpected error", "siteId": "default", "context": null, "sessionId": null}'

Note

This is a Rhasspy-only message.

context: Optional[str] = None

Additional information on the context in which the error occurred.

error: str = None

A description of the error that occurred.

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the error occurred.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/error/dialogueManager"

Return type

str

class rhasspyhermes.dialogue.DialogueIntentNotRecognized(session_id: str, site_id: str = 'default', input: Optional[str] = None, custom_data: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Intent not recognized.

Only sent when send_intent_not_recognized is True.

MQTT message

Topic

hermes/dialogueManager/intentNotRecognized

Payload (JSON)

Key

Type

Description

sessionId

String

The id of the session that generated this event.

siteId

String

The id of the site where the user interaction took place.

input

String (optional)

The NLU input that generated this event.

customData

String (optional)

Custom data provided in the DialogueStartSession or DialogueContinueSession messages.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/dialogueManager/intentNotRecognized'
custom_data: Optional[str] = None

Custom data provided in the DialogueStartSession or DialogueContinueSession messages.

input: Optional[str] = None

The NLU input that generated this event.

session_id: str = None

The id of the session that generated this event.

site_id: str = 'default'

The id of the site where the user interaction took place.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/intentNotRecognized"

Return type

str

class rhasspyhermes.dialogue.DialogueNotification(text: str, type: rhasspyhermes.dialogue.DialogueActionType = <DialogueActionType.NOTIFICATION: 'notification'>)[source]

Bases: dataclasses_json.api.DataClassJsonMixin

Dialogue session notification.

text: str = None

Text the TTS should say.

type: rhasspyhermes.dialogue.DialogueActionType = 'notification'

This value is always DialogueActionType.NOTIFICATION.

class rhasspyhermes.dialogue.DialogueSessionEnded(termination: rhasspyhermes.dialogue.DialogueSessionTermination, session_id: str, site_id: str = 'default', custom_data: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent when a dialogue session has ended.

MQTT message

Topic

hermes/dialogueManager/sessionEnded

Payload (JSON)

Key

Type

Description

termination

JSON Object

Structured description of why the session has been ended. See DialogueSessionTerminationReason for the possible values.

sessionId

String

The id of the ended session.

siteId

String

The id of the site where the user interaction took place.

customData

String (optional)

Custom data provided in the DialogueStartSession, DialogueContinueSession or DialogueEndSession messages.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/dialogueManager/sessionEnded'
custom_data: Optional[str] = None

Custom data provided in the DialogueStartSession, DialogueContinueSession or DialogueEndSession messages.

session_id: str = None

The id of the ended session.

site_id: str = 'default'

The id of the site where the user interaction took place.

termination: DialogueSessionTermination = None

Structured description of why the session has been ended.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/sessionEnded"

Return type

str

class rhasspyhermes.dialogue.DialogueSessionQueued(session_id: str, site_id: str = 'default', custom_data: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent by the dialogue manager when it receives a DialogueStartSession message and the site where the interaction should take place is busy. When the site is free again, the session will be started.

Only DialogueStartSession messages with an init attribute of the following type can be enqueued:

MQTT message

Topic

hermes/dialogueManager/sessionQueued

Payload (JSON)

Key

Type

Description

sessionId

String

The id of the session that was enqueued.

siteId

String

The id of the site where the user interaction will take place.

customData

String (optional)

Custom data provided in the DialogueStartSession message.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/dialogueManager/sessionQueued'
custom_data: Optional[str] = None

Custom data provided in the DialogueStartSession message.

session_id: str = None

The id of the session that was enqueued.

site_id: str = 'default'

The id of the site where the user interaction will take place.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/sessionQueued"

Return type

str

class rhasspyhermes.dialogue.DialogueSessionStarted(session_id: str, site_id: str = 'default', custom_data: Optional[str] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Sent when a dialogue session has been started.

MQTT message

Topic

hermes/dialogueManager/sessionStarted

Payload (JSON)

Key

Type

Description

sessionId

String

The id of the session that was started.

siteId

String

The id of the site where the user interaction is taking place.

customData

String (optional)

Custom data provided in the DialogueStartSession message.

lang

String (optional)

Language of the session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/dialogueManager/sessionStarted'
custom_data: Optional[str] = None

Custom data provided in the DialogueStartSession message.

lang: Optional[str] = None

Language of the session.

Note

This is a Rhasspy-only attribute.

session_id: str = None

The id of the session that was started.

site_id: str = 'default'

The id of the site where the user interaction is taking place.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/sessionStarted"

Return type

str

class rhasspyhermes.dialogue.DialogueSessionTermination(reason: rhasspyhermes.dialogue.DialogueSessionTerminationReason)[source]

Bases: object

Dialogue session termination type.

reason: DialogueSessionTerminationReason = None

The reason why the session was ended.

class rhasspyhermes.dialogue.DialogueSessionTerminationReason[source]

Bases: str, enum.Enum

The reason why the session was ended.

ABORTED_BY_USER = 'abortedByUser'

The session was aborted by the user.

ERROR = 'error'

The session failed with an error.

INTENT_NOT_RECOGNIZED = 'intentNotRecognized'

The session ended because no intent was successfully detected.

NOMINAL = 'nominal'

The session ended as expected (a DialogueEndSession message was received).

TIMEOUT = 'timeout'

The session timed out because there was no response from one of the components or no DialogueContinueSession or DialogueEndSession message in a timely manner.

class rhasspyhermes.dialogue.DialogueStartSession(init: Union[rhasspyhermes.dialogue.DialogueAction, rhasspyhermes.dialogue.DialogueNotification], site_id: str = 'default', custom_data: Optional[str] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Start a dialogue session.

You can send this message to programmatically initiate a new session. The Dialogue Manager will start the session by asking the TTS to say the text (if any) and wait for the answer of the user.

MQTT message

Topic

hermes/dialogueManager/startSession

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where to start the session.

init

JSON object

Session initialization description.

customData

String (optional)

Additional information that can be provided by the handler. Each message related to the new session - sent by the Dialogue Manager - will contain this data.

lang

String (optional)

Language of the session.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/dialogueManager/startSession' -m '{"siteId": "livingroom", "init": {"type": "notification", "text": "Ready"}, "lang": "en"}'

Example

>>> from rhasspyhermes.dialogue import DialogueStartSession, DialogueNotification
>>> start_session = DialogueStartSession(init=DialogueNotification(text="Ready"), site_id="livingroom", lang="en")
>>> start_session
DialogueStartSession(init=DialogueNotification(text='Ready', type=<DialogueActionType.NOTIFICATION: 'notification'>), site_id='livingroom', custom_data=None, lang='en')
>>> start_session.payload()
'{"init": {"text": "Ready", "type": "notification"}, "siteId": "livingroom", "customData": null, "lang": "en"}'
custom_data: Optional[str] = None

Additional information that can be provided by the handler. Each message related to the new session - sent by the Dialogue Manager - will contain this data.

init: typing.Union[DialogueAction, DialogueNotification] = None

Session initialization description.

lang: Optional[str] = None

Language of the session.

Note

This is a Rhasspy-only attribute.

site_id: str = 'default'

The id of the site where to start the session.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/dialogueManager/startSession"

Return type

str

rhasspyhermes.g2p

Messages for looking up/guessing word pronunciations.

class rhasspyhermes.g2p.G2pError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Error from G2P component.

MQTT message

Topic

rhasspy/error/g2p

Payload (JSON)

Key

Type

Description

error

String

A description of the error that occurred.

siteId

String

The id of the site where the error occurred.

context

String

Additional information on the context in which the error occurred.

sessionId

String (optional)

Id of active session, if there is one.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -t 'rhasspy/error/g2p' -v

Note

This is a Rhasspy-only message.

context: Optional[str] = None

Additional information on the context in which the error occurred.

error: str = None

A description of the error that occurred.

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the error occurred.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/error/g2p"

Return type

str

class rhasspyhermes.g2p.G2pPhonemes(word_phonemes: Dict[str, List[rhasspyhermes.g2p.G2pPronunciation]], id: Optional[str] = None, site_id: str = 'default', session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Response to G2pPronounce.

MQTT message

Topic

rhasspy/g2p/phonemes

Payload (JSON)

Key

Type

Description

wordPhonemes

Dictionary

Guessed or looked up pronunciations.

id

String (optional)

Unique id for a G2pPronounce request.

siteId

String

The id of the site where pronunciations were requested. Defaults to "default".

sessionId

String (optional)

Id of active session, if there is one.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -t 'rhasspy/g2p/phonemes' -v

Note

This is a Rhasspy-only message.

id: Optional[str] = None

Unique id from a G2pPronounce request.

session_id: Optional[str] = None

Id of active session, if there is one.

site_id: str = 'default'

Id of site where pronunciations were requested.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/g2p/phonemes"

Return type

str

word_phonemes: typing.Dict[str, typing.List[G2pPronunciation]] = None

Guessed or looked up pronunciations.

class rhasspyhermes.g2p.G2pPronounce(words: List[str], id: Optional[str] = None, site_id: str = 'default', session_id: Optional[str] = None, num_guesses: int = 5)[source]

Bases: rhasspyhermes.base.Message

Get phonetic pronunciation for words.

The response is sent in a G2pPhonemes message.

MQTT message

Topic

rhasspy/g2p/pronounce

Payload (JSON)

Key

Type

Description

words

List of Strings

Words to guess pronunciations for.

id

String (optional)

Unique id for request. Appended to reply topic (G2pPhonemes).

siteId

String

The id of the site where pronunciations were requested. Defaults to "default".

sessionId

String (optional)

Id of active session, if there is one.

numGuesses

Integer

Maximum number of guesses to return for words not in dictionary. Defaults to 5.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'rhasspy/g2p/pronounce' -m '{"words": ["word", "sentence"], "id": "test", "siteId": "default", "sessionId": null, "numGuesses": 5}'

Example

>>> from rhasspyhermes.g2p import G2pPronounce
>>> p = G2pPronounce(words=["word", "sentence"], id="test")
>>> p.payload()
'{"words": ["word", "sentence"], "id": "test", "siteId": "default", "sessionId": null, "numGuesses": 5}'
>>> p.topic()
'rhasspy/g2p/pronounce'

Note

This is a Rhasspy-only message.

id: Optional[str] = None

Unique id for request. Appended to reply topic (G2pPhonemes).

num_guesses: int = 5

Maximum number of guesses to return for words not in dictionary.

session_id: Optional[str] = None

Id of active session, if there is one.

site_id: str = 'default'

Id of site to request pronunciations from.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/g2p/pronounce"

Return type

str

words: typing.List[str] = None

Words to guess pronunciations for.

class rhasspyhermes.g2p.G2pPronunciation(phonemes: List[str], guessed: Optional[bool] = None)[source]

Bases: object

Phonetic pronunciation for a single word.

guessed: Optional[bool] = None

True if this pronunciation was guessed using a g2p model. False if it came from a pronunciation dictionary.

phonemes: typing.List[str] = None

Phonetic pronunciation for word.

rhasspyhermes.handle

Rhasspy-only messages for intent handling.

class rhasspyhermes.handle.HandleToggleOff(site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Disable intent handling.

MQTT message

Topic

rhasspy/handle/toggleOff

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where intent handling should be disabled. Defaults to "default".

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'rhasspy/handle/toggleOff' -m '{"siteId": "default"}'

Example

>>> from rhasspyhermes.handle import HandleToggleOff
>>> off = HandleToggleOff()
>>> off
HandleToggleOff(site_id='default')
>>> off.payload()
'{"siteId": "default"}'
>>> off.topic()
'rhasspy/handle/toggleOff'

Note

This is a Rhasspy-only message.

site_id: str = 'default'

The id of the site where intent handling should be disabled

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/handle/toggleOff"

Return type

str

class rhasspyhermes.handle.HandleToggleOn(site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Enable intent handling.

MQTT message

Topic

rhasspy/handle/toggleOn

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where intent handling should be enabled. Defaults to "default".

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'rhasspy/handle/toggleOn' -m '{"siteId": "default"}'

Example

>>> from rhasspyhermes.handle import HandleToggleOn
>>> on = HandleToggleOn()
>>> on
HandleToggleOn(site_id='default')
>>> on.payload()
'{"siteId": "default"}'
>>> on.topic()
'rhasspy/handle/toggleOn'

Note

This is a Rhasspy-only message.

site_id: str = 'default'

The id of the site where intent handling should be enabled

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/handle/toggleOn"

Return type

str

rhasspyhermes.intent

Intent and slot classes for NLU.

class rhasspyhermes.intent.Intent(intent_name: str, confidence_score: float)[source]

Bases: object

Intent object with a name and confidence score.

confidence_score: float = None

The probability of the detection, between 0 and 1 (1 being sure).

intent_name: str = None

The name of the detected intent.

class rhasspyhermes.intent.Slot(entity: str, value: Dict[str, Any], slot_name: str = None, raw_value: str = None, confidence: float = 0.0, range: Optional[rhasspyhermes.intent.SlotRange] = None)[source]

Bases: object

Named entity in an intent slot.

confidence: float = 0.0

Confidence score of the slot, between 0 and 1 (1 being confident).

property end

Get the end index (exclusive) of the slot value.

entity: str = None

The entity of the slot.

range: Optional[rhasspyhermes.intent.SlotRange] = None

The range where the slot is found in the input text.

property raw_end

Get the end index (exclusive) of the raw slot value.

property raw_start

Get the start index (inclusive) of the raw slot value.

raw_value: str = None

The raw value of the slot, as it was in the input.

slot_name: str = None

The name of the slot.

property start

Get the start index (inclusive) of the slot value.

value: typing.Dict[str, typing.Any] = None

The resolved value of the slot. Contains at least a "value" key.

class rhasspyhermes.intent.SlotRange(start: int, end: int, raw_start: Optional[int] = None, raw_end: Optional[int] = None)[source]

Bases: object

The range where a slot is found in the input text.

end: int = None

Index of the end (exclusive) of the slot value in the substituted input.

raw_end: Optional[int] = None

Index of the end (exclusive) of the slot value in the unsubstituted input.

Note

This is a Rhasspy-only attribute.

raw_start: Optional[int] = None

Index of the beginning (inclusive) of the slot value in the unsubstituted input.

Note

This is a Rhasspy-only attribute.

start: int = None

Index of the beginning (inclusive) of the slot value in the substituted input.

rhasspyhermes.nlu

Messages for natural language understanding.

class rhasspyhermes.nlu.AsrToken(value: str, confidence: float, range_start: int, range_end: int, time: Optional[rhasspyhermes.nlu.AsrTokenTime] = None)[source]

Bases: object

A token from an automated speech recognizer.

confidence: float = None

Confidence score of the token, between 0 and 1 (1 being confident).

range_end: int = None

The end of the range in which the token is in the original input.

range_start: int = None

The start of the range in which the token is in the original input.

time: Optional[rhasspyhermes.nlu.AsrTokenTime] = None

Structured time when this token was detected.

value: str = None

Text value of the token.

class rhasspyhermes.nlu.AsrTokenTime(start: float, end: float)[source]

Bases: object

The time when an ASR token was detected.

end: float = None

End time (in seconds) of token relative to beginning of utterance.

start: float = None

Start time (in seconds) of token relative to beginning of utterance.

class rhasspyhermes.nlu.NluError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

This message is published by the NLU component if an error has occurred.

MQTT message

Topic

hermes/error/nlu

Payload (JSON)

Key

Type

Description

error

String

A description of the error that occurred.

siteId

String

Site where the error occurred. Defaults to "default".

context

String (optional)

Additional information on the context in which the error occurred.

sessionId

String (optional)

Session id, if there is an active session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/error/nlu'

Example

>>> from rhasspyhermes.nlu import NluError
>>> nlu_error = NluError(error="Unexpected error")
>>> nlu_error.topic()
'hermes/error/nlu'
>>> nlu_error.payload()
'{"error": "Unexpected error", "siteId": "default", "context": null, "sessionId": null}'
context: Optional[str] = None

Additional information on the context in which the error occurred.

error: str = None

A description of the error that occurred.

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the error occurred. Defaults to "default".

Note

In contrast to the Snips Hermes protocol, the site id is compulsory.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message.

Returns

"hermes/error/nlu"

Return type

str

class rhasspyhermes.nlu.NluIntent(input: str, intent: rhasspyhermes.intent.Intent, site_id: str = 'default', id: Optional[str] = None, slots: Optional[List[rhasspyhermes.intent.Slot]] = None, session_id: Optional[str] = None, custom_data: Optional[str] = None, asr_tokens: Optional[List[List[rhasspyhermes.nlu.AsrToken]]] = None, asr_confidence: Optional[float] = None, raw_input: Optional[str] = None, wakeword_id: Optional[str] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Recognized intent.

This is the main Rhasspy Hermes message an intent handler should subscribe to. It is sent by the dialogue manager when an intent has been detected.

It’s the intent handler’s responsibility to inform the dialogue manager of what it should do with the current session. The handler should either send a rhasspyhermes.dialogue.DialogueContinueSession or a rhasspyhermes.dialogue.DialogueEndSession message with the current session id.

MQTT message

Topic

hermes/intent/<intentName>

Payload (JSON)

Key

Type

Description

input

String

The user input that has generated this intent.

intent

JSON object

Structured description of the intent classification.

siteId

String

Site where the user interaction took place. Defaults to "default".

id

String (optional)

The request identifier from the NLU query (NluQuery), if any.

slots

List of JSON objects (optional)

Structured description of the detected slots for this intent, if any.

sessionId

String (optional)

Session id of the intent detection. The client code must use it to continue (rhasspyhermes.dialogue.DialogueContinueSession) or end (rhasspyhermes.dialogue.DialogueEndSession) the session.

customData

String (optional)

Custom data provided by message that started (rhasspyhermes.dialogue.DialogueStartSession), continued (rhasspyhermes.dialogue.DialogueContinueSession) or ended (rhasspyhermes.dialogue.DialogueEndSession) the session.

asrTokens

List of list of JSON objects (optional)

Structured description of the tokens the ASR captured for this intent. The first level of lists represents each invocation of the ASR, the second level represents the captured tokens in that invocation.

asrConfidence

Number (optional)

Speech recognizer confidence score between 0 and 1 (1 being sure).

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/intent/<intentName>'

Replace <intentName> by the name of the intent you’re interested in. You can use the MQTT wildcard # is you want to receive all intents.

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> from rhasspyhermes.intent import Intent
>>> nlu_intent = NluIntent("what time is it", Intent(intent_name="GetTime", confidence_score=0.95))
>>> nlu_intent.payload()
'{"input": "what time is it", "intent": {"intentName": "GetTime", "confidenceScore": 0.95}, "siteId": "default", "id": null, "slots": null, "sessionId": null, "customData": null, "asrTokens": null, "asrConfidence": null, "rawInput": null, "wakewordId": null, "lang": null}'
asr_confidence: Optional[float] = None

Speech recognizer confidence score between 0 and 1 (1 being sure).

asr_tokens: Optional[List[List[rhasspyhermes.nlu.AsrToken]]] = None

Structured description of the tokens the ASR captured for this intent. The first level of lists represents each invocation of the ASR, the second level represents the captured tokens in that invocation.

custom_data: Optional[str] = None

Custom data provided by message that started (rhasspyhermes.dialogue.DialogueStartSession), continued (rhasspyhermes.dialogue.DialogueContinueSession) or ended (rhasspyhermes.dialogue.DialogueEndSession) the session.

classmethod get_intent_name(topic: str)str[source]

Get intent_name from a topic.

id: Optional[str] = None

Request id from the NLU query (NluQuery), if any.

Note

This is a Rhasspy-only attribute.

input: str = None

The user input that has generated this intent.

intent: Intent = None

Structured description of the intent classification.

classmethod is_topic(topic: str)bool[source]

True if topic matches template.

lang: Optional[str] = None

Language of the session.

Note

This is a Rhasspy-only attribute.

classmethod make_asr_tokens(tokens: List[Any]) → List[rhasspyhermes.nlu.AsrToken][source]

Create ASR token objects from words.

raw_input: Optional[str] = None

Original query input before substitutions, such as number replacement.

Note

This is a Rhasspy-only attribute.

session_id: Optional[str] = None

Session id of the intent detection. The client code must use it to continue (rhasspyhermes.dialogue.DialogueContinueSession) or end (rhasspyhermes.dialogue.DialogueEndSession) the session.

Note

In contrast to the Snips Hermes protocol, the session id is optional.

site_id: str = 'default'

Site where the user interaction took place.

slots: Optional[List[rhasspyhermes.intent.Slot]] = None

Structured description of the detected slots for this intent, if any.

to_rhasspy_dict() → Dict[str, Any][source]

Convert to Rhasspy format.

classmethod topic(**kwargs)str[source]

Get MQTT topic for a message of this type with intent name intent_name.

Returns

"hermes/intent/{intent_name}"

Return type

str

Example

>>> from rhasspyhermes.nlu import NluIntent
>>> NluIntent.topic()
'hermes/intent/#'
>>> NluIntent.topic(intent_name="GetTime")
'hermes/intent/GetTime'
wakeword_id: Optional[str] = None

Id of the wake word that triggered this session.

Note

This is a Rhasspy-only attribute.

class rhasspyhermes.nlu.NluIntentNotRecognized(input: str, site_id: str = 'default', id: Optional[str] = None, custom_data: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Intent not recognized.

MQTT message

Topic

hermes/nlu/intentNotRecognized

Payload (JSON)

Key

Type

Description

input

String

The user input, if any, that generated this event.

siteId

String

Site where the user interaction took place. Defaults to "default".

id

String (optional)

The request identifier from the NLU query (NluQuery), if any.

customData

String (optional)

Custom data provided by message that started (rhasspyhermes.dialogue.DialogueStartSession), continued (rhasspyhermes.dialogue.DialogueContinueSession) or ended (rhasspyhermes.dialogue.DialogueEndSession) the session.

sessionId

String (optional)

Session id of the intent detection. The client code must use it to continue (rhasspyhermes.dialogue.DialogueContinueSession) or end (rhasspyhermes.dialogue.DialogueEndSession) the session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/nlu/intentNotRecognized'
custom_data: Optional[str] = None

Custom data provided by message that started (rhasspyhermes.dialogue.DialogueStartSession), continued (rhasspyhermes.dialogue.DialogueContinueSession) or ended (rhasspyhermes.dialogue.DialogueEndSession) the session.

id: Optional[str] = None

Request id from NLU query, if any.

input: str = None

The input, if any, that generated this event.

session_id: Optional[str] = None

Session identifier of the session that generated this intent not recognized event.

site_id: str = 'default'

Site where the user interaction took place.

Note

In contrast to the Snips Hermes protocol, the site id is compulsory.

to_rhasspy_dict() → Dict[str, Any][source]

Return an empty Rhasspy intent dictionary.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/nlu/intentNotRecognized"

Return type

str

class rhasspyhermes.nlu.NluIntentParsed(input: str, intent: rhasspyhermes.intent.Intent, site_id: str = 'default', id: Optional[str] = None, slots: Optional[List[rhasspyhermes.intent.Slot]] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

An intent is successfully parsed.

The NLU component returns this message as a result of the intent resolution requested by a NluQuery message.

MQTT message

Topic

hermes/nlu/intentParsed

Payload (JSON)

Key

Type

Description

input

String

The user input that has generated this intent.

intent

JSON object

Structured description of the intent classification.

siteId

String

Site where the user interaction took place.

id

String (optional)

The request identifier from the NLU query (NluQuery), if any.

slots

List of JSON objects (optional)

Structured description of the detected slots for this intent, if any.

sessionId

String (optional)

Session id of the intent detection. The client code must use it to continue (rhasspyhermes.dialogue.DialogueContinueSession) or end (rhasspyhermes.dialogue.DialogueEndSession) the session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/nlu/intentParsed'

Note

This is a low-level message. It preceeds the full intent message, NluIntent. To detect a specific intent parsed by the NLU component, it is recommended to subscribe to the latter message type.

id: Optional[str] = None

The request identifier from the NLU query (NluQuery), if any.

input: str = None

The user input that has generated this intent.

intent: Intent = None

Structured description of the intent classification.

session_id: Optional[str] = None

Session id of the intent detection. The client code must use it to continue (rhasspyhermes.dialogue.DialogueContinueSession) or end (rhasspyhermes.dialogue.DialogueEndSession) the session.

site_id: str = 'default'

Site where the user interaction took place.

Note

In contrast to the Snips Hermes protocol, the site id is compulsory.

slots: Optional[List[rhasspyhermes.intent.Slot]] = None

Structured description of the detected slots for this intent, if any.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/nlu/intentParsed"

Return type

str

class rhasspyhermes.nlu.NluQuery(input: str, site_id: str = 'default', id: Optional[str] = None, intent_filter: Optional[List[str]] = None, session_id: Optional[str] = None, wakeword_id: Optional[str] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Request intent recognition from NLU component.

MQTT message

Topic

hermes/nlu/query

Payload (JSON)

Key

Type

Description

input

String

The text to send to the NLU component.

siteId

String

The id of the site where the NLU component is located. Defaults to "default".

id

String (optional)

A request identifier. If provided, it will be passed back in the response (NluIntentParsed or NluIntentNotRecognized).

intentFilter

List of strings (optional)

A list of intent names to restrict the NLU resolution on.

sessionId

String (optional)

The id of the session, if there is an active session.

wakewordId

String (optional)

The id of the wakeword used to activate the ASR.

lang

String (optional)

The language of the session.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/nlu/query' -m '{"input": "what time is it", "siteId": "default"}'

Example

>>> from rhasspyhermes.nlu import NluQuery
>>> query = NluQuery(input='what time is it')
>>> query.payload()
'{"input": "what time is it", "siteId": "default", "id": null, "intentFilter": null, "sessionId": null, "wakewordId": null, "lang": null}'
>>> query.topic()
'hermes/nlu/query'
id: Optional[str] = None

A request identifier. If provided, it will be passed back in the response (NluIntentParsed or NluIntentNotRecognized).

input: str = None

The text to send to the NLU component.

intent_filter: Optional[List[str]] = None

A list of intent names to restrict the NLU resolution on.

lang: Optional[str] = None

Optional language of the session.

Note

This is a Rhasspy-only attribute.

session_id: Optional[str] = None

The id of the session, if there is an active session.

Note

In contrast to the Snips Hermes protocol, the session id is optional.

site_id: str = 'default'

The id of the site where the NLU component is located.

Note

In contrast to the Snips Hermes protocol, the site id is compulsory.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/nlu/query"

Return type

str

wakeword_id: Optional[str] = None

Optional id of the wakeword used to activate the ASR.

Note

This is a Rhasspy-only attribute.

class rhasspyhermes.nlu.NluTrain(graph_path: str, id: Optional[str] = None, graph_format: Optional[str] = None, sentences: Optional[Dict[str, str]] = None, slots: Optional[Dict[str, List[str]]] = None)[source]

Bases: rhasspyhermes.base.Message

Request to retrain NLU from intent graph.

MQTT message

Topic

rhasspy/nlu/<siteId>/train

Payload (JSON)

Key

Type

Description

graphPath

String

Path to the graph file.

id

String (optional)

Unique id for the training request. Appended to reply topic (NluTrainSuccess).

graphFormat

String (optional)

Format of the graph file.

sentences

Dictionary (optional)

TODO

slots

Dictionary (optional)

TODO

Publish this message type with mosquitto_pub:

TODO

Note

This is a Rhasspy-only message.

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic.

graph_format: Optional[str] = None

Optional format of the graph file.

graph_path: str = None

Path to the graph file.

id: Optional[str] = None

Unique id for the training request.

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template.

sentences: Optional[Dict[str, str]] = None

TODO

slots: Optional[Dict[str, List[str]]] = None

TODO

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/nlu/{site_id}/train"

Return type

str

class rhasspyhermes.nlu.NluTrainSuccess(id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Result from successful training.

MQTT message

Topic

rhasspy/nlu/<siteId>/trainSuccess

Payload (JSON)

Key

Type

Description

id

String (optional)

Unique id from the training request (NluTrain).

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'rhasspy/nlu/<siteId>/trainSuccess'

Note

This is a Rhasspy-only message.

classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from a topic.

id: Optional[str] = None

Unique id from training request.

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

classmethod is_topic(topic: str)bool[source]

True if topic matches template

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/nlu/{site_id}/trainSuccess"

Return type

str

rhasspyhermes.train

Rhasspy-only messages for intent training.

class rhasspyhermes.train.IntentGraph(graph_bytes: bytes)[source]

Bases: rhasspyhermes.base.Message

Intent graph from training.

MQTT message

Topic

rhasspy/train/intentGraph

Payload (binary)

gzipped pickle bytes containing a NetworkX intent graph

Subscribe to this message type with mosquitto_sub and show the binary payload as hexadecimal numbers:

mosquitto_sub -h <HOSTNAME> -t 'rhasspy/train/intentGraph' -F %x

Note

This is a Rhasspy-only message.

graph_bytes: bytes = None

Gzipped pickle bytes containing a NetworkX intent graph

classmethod is_binary_payload()bool[source]

Check for binary payload of message.

Returns

True

Return type

bool

classmethod is_topic(topic: str)bool[source]

Check whether topic is for this message type.

Parameters

topic – message topic

Returns

True if topic is for this message type

Return type

bool

Example

>>> from rhasspyhermes.train import IntentGraph
>>> IntentGraph.is_topic("rhasspy/train/intentGraph/abcd")
True
payload()bytes[source]

Get the binary payload for this message.

Returns

The binary payload as gzipped pickle bytes containing a NetworkX intent graph.

Return type

bytes

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Parameters

request_id (str) – Unique id for request. Supplied in request topic (IntentGraphRequest)

Returns

"rhasspy/train/intentGraph/{request_id}"

Return type

str

Example

>>> from rhasspyhermes.train import IntentGraph
>>> IntentGraph.topic(request_id="abcd")
'rhasspy/train/intentGraph/abcd'
class rhasspyhermes.train.IntentGraphRequest(id: str, site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Request publication of intent graph from training.

MQTT message

Topic

rhasspy/train/getIntentGraph

Payload (JSON)

Key

Type

Description

id

String

Unique id for request. Appended to reply topic (IntentGraph).

siteId

String

The id of the site where training occurred. Defaults to "default".

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'rhasspy/train/getIntentGraph' -m '{"id": "abcd", "siteId": "default"}'

Example

>>> from rhasspyhermes.train import IntentGraphRequest
>>> request = IntentGraphRequest(id='abcd')
>>> request.payload()
'{"id": "abcd", "siteId": "default"}'
>>> request.topic()
'rhasspy/train/getIntentGraph'

Note

This is a Rhasspy-only message.

id: str = None

Unique id for request. Appended to reply topic (IntentGraph).

site_id: str = 'default'

The id of the site where training occurred.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/train/getIntentGraph"

Return type

str

rhasspyhermes.tts

Messages for text to speech.

class rhasspyhermes.tts.GetVoices(id: Optional[str] = None, site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Get the available voices for the text to speech system.

Note

This is a Rhasspy-only message.

MQTT message

Topic

hermes/tts/getVoices

Payload (JSON)

Key

Type

Description

id

String (optional)

Unique identifier passed to the response (Voices).

siteId

String

The id of the site to request voices from. Defaults to "default".

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/tts/getVoices' -m '{"id": "abcd", "siteId": "default"}'

Example

>>> from rhasspyhermes.tts import GetVoices
>>> g = GetVoices("abcd")
>>> g.topic()
'rhasspy/tts/getVoices'
>>> g.payload()
'{"id": "abcd", "siteId": "default"}'
id: Optional[str] = None

Unique identifier passed to response (Voices).

site_id: str = 'default'

Id of site to request voices from.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/tts/getVoices"

Return type

str

class rhasspyhermes.tts.TtsError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

This message is published by the text to speech system if an error has occurred.

Note

This is a Rhasspy-only message.

MQTT message

Topic

hermes/error/tts

Payload (JSON)

Key

Type

Description

error

String

A description of the error that occurred.

siteId

String

Site where the error occurred. Defaults to "default".

context

String (optional)

Additional information on the context in which the error occurred.

sessionId

String (optional)

The id of the session, if there is an active session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/error/tts'

Example

>>> from rhasspyhermes.tts import TtsError
>>> tts_error = TtsError(error="Unexpected error")
>>> tts_error.topic()
'hermes/error/tts'
>>> tts_error.payload()
'{"error": "Unexpected error", "siteId": "default", "context": null, "sessionId": null}'
context: Optional[str] = None

Additional information on the context in which the error occurred.

error: str = None

A description of the error that occurred.

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the error occurred.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/error/tts"

Return type

str

class rhasspyhermes.tts.TtsSay(text: str, site_id: str = 'default', lang: Optional[str] = None, id: Optional[str] = None, session_id: Optional[str] = None, volume: Optional[float] = None)[source]

Bases: rhasspyhermes.base.Message

Send text to be spoken by the text to speech component.

Note

This is a low-level message. You should use the dialogue manager’s rhasspyhermes.dialogue.DialogueStartSession or rhasspyhermes.dialogue.DialogueContinueSession messages.

MQTT message

Topic

hermes/tts/say

Payload (JSON)

Key

Type

Description

text

String

The text to be spoken.

siteId

String

The id of the site where the text should be spoken. Defaults to "default".

lang

String (optional)

The language code to use when saying the text.

id

String (optional)

A request identifier. If provided, it will be passed back in the response message TtsSayFinished.

sessionId

String (optional)

The id of the session, if there is an active session.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/tts/say' -m '{"text": "Ciao!", "lang": "it_IT"}'

Example

>>> from rhasspyhermes.tts import TtsSay
>>> say = TtsSay(text="Ciao!", lang="it_IT")
>>> say.topic()
'hermes/tts/say'
>>> say.payload()
'{"text": "Ciao!", "siteId": "default", "lang": "it_IT", "id": null, "sessionId": null}'
id: Optional[str] = None

A request identifier. If provided, it will be passed back in the response message TtsSayFinished.

lang: Optional[str] = None

The language code to use when saying the text.

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the text should be spoken.

text: str = None

The text to be spoken.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/tts/say"

Return type

str

volume: Optional[float] = None

Volume scale to apply to generated audio (0-1)

class rhasspyhermes.tts.TtsSayFinished(site_id: str = 'default', id: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Response published when the text to speech component has finished speaking.

MQTT message

Topic

hermes/tts/sayFinished

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where the text was spoken. Defaults to "default".

id

String (optional)

Identifier from the request (TtsSay).

sessionId

String (optional)

The id of the session, if there is an active session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/tts/sayFinished'
id: Optional[str] = None

Identifier from the request (TtsSay).

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the text was spoken. Defaults to "default".

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/tts/sayFinished"

Return type

str

class rhasspyhermes.tts.Voice(voice_id: str, description: Optional[str] = None)[source]

Bases: object

Information about a single TTS voice.

description: Optional[str] = None

Human-readable description of voice.

voice_id: str = None

Unique identifier for voice.

class rhasspyhermes.tts.Voices(voices: List[rhasspyhermes.tts.Voice], id: Optional[str] = None, site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Response with the available voices for the text to speech system. This message is published in response to a GetVoices request.

Note

This is a Rhasspy-only message.

MQTT message

Topic

hermes/tts/Voices

Payload (JSON)

Key

Type

Description

voices

List of JSON objects

List of available voices.

id

String (optional)

Unique identifier from the request (GetVoices).

siteId

String

The id of the site where voices were requested. Defaults to "default".

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/tts/voices'
id: Optional[str] = None

Unique identifier from request (GetVoices).

site_id: str = 'default'

Id of site where voices were requested.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/tts/voices"

Return type

str

voices: typing.List[Voice] = None

List of available voices.

rhasspyhermes.utils

Utility methods for Rhasspy Hermes messages.

rhasspyhermes.utils.only_fields(cls, message_dict: Dict[str, Any]) → Dict[str, Any][source]

Return a dict with only valid fields.

rhasspyhermes.wake

Messages for wake word detection.

class rhasspyhermes.wake.GetHotwords(site_id: str = 'default', id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Request to list available hotwords. The wake word component responds with a Hotwords message.

MQTT message

Topic

rhasspy/hotword/getHotwords

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where the wake word component exists.

id

String (optional)

Unique id passed to the response in the Hotwords message.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'rhasspy/hotword/getHotwords' -m '{"siteId": "default", "id": "foobar"}'

Note

This is a Rhasspy-only message.

id: Optional[str] = None

Unique id passed to the response in the Hotwords message.

site_id: str = 'default'

The id of the site where the wake word component exists.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/hotword/getHotwords"

Return type

str

class rhasspyhermes.wake.Hotword(model_id: str, model_words: str, model_version: str = '', model_type: str = 'personal')[source]

Bases: object

Description of a single hotword.

model_id: str = None

Unique ID of hotword model.

model_type: str = 'personal'

Model type (personal, unversal).

model_version: str = ''

Model version.

model_words: str = None

Actual words used to activate hotword.

class rhasspyhermes.wake.HotwordDetected(model_id: str, model_version: str = '', model_type: str = 'personal', current_sensitivity: float = 1.0, site_id: str = 'default', session_id: Optional[str] = None, send_audio_captured: Optional[bool] = None, lang: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Message sent by the wake word component when it has detected a specific wake word.

MQTT message

Topic

hermes/hotword/<WAKEWORD_ID>/detected

Payload (JSON)

Key

Type

Description

modelId

String

The id of the model that triggered the wake word.

modelVersion

String

The version of the model.

modelType

String

The type of the model. Possible values are "universal" and "personal".

currentSensitivity

Float

The sensitivity configured in the model at the time of the detection.

siteId

String

The id of the site where the wake word component should be disabled.

sessionId

String (optional)

The id of the dialogue session created after detection.

send_audio_captured

Boolean (optional)

True if audio captured from the ASR should be emitted on rhasspy/asr/{site_id}/{session_id}/audioCaptured.

lang

String (optional)

Language of the detected wake word. Copied by the dialogue manager into subsequent ASR and NLU messages.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/hotword/default/detected'
current_sensitivity: float = 1.0

The sensitivity configured in the model at the time of the detection.

classmethod get_wakeword_id(topic: str)str[source]

Get wakeword id from MQTT topic.

Parameters

topic – MQTT topic.

Returns

Wake word ID extracted from the MQTT topic.

Return type

str

Example

>>> from rhasspyhermes.wake import HotwordDetected
>>> HotwordDetected.get_wakeword_id("hermes/hotword/example-02.wav/detected")
'example-02.wav'
classmethod is_topic(topic: str)bool[source]

True if topic matches template.

lang: Optional[str] = None

Language of the detected wake word. Copied by the dialogue manager into subsequent ASR and NLU messages.

Note

This is a Rhasspy-only attribute.

model_id: str = None

The id of the model that triggered the wake word.

model_type: str = 'personal'

The type of the model. Possible values are "universal" and "personal".

model_version: str = ''

The version of the model.

send_audio_captured: Optional[bool] = None

True if audio captured from the ASR should be emitted on rhasspy/asr/{site_id}/{session_id}/audioCaptured.

Note

This is a Rhasspy-only attribute.

session_id: Optional[str] = None

The desired id of the dialogue session created after detection. Leave empty to have one auto-generated.

Note

This is a Rhasspy-only attribute.

site_id: str = 'default'

The id of the site where the wake word was detected.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Parameters

wakeword_id (str) – The id of the wake word.

Returns

MQTT topic for this message type with the given wake word id.

Return type

str

Example

>>> from rhasspyhermes.wake import HotwordDetected
>>> HotwordDetected.topic(wakeword_id="example-02.wav")
'hermes/hotword/example-02.wav/detected'
class rhasspyhermes.wake.HotwordError(error: str, site_id: str = 'default', context: Optional[str] = None, session_id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

Error from wake word component.

MQTT message

Topic

hermes/error/hotword

Payload (JSON)

Key

Type

Description

error

String

A description of the error that occurred.

siteId

String

The id of the site where the error occurred.

context

String (optional)

Additional information on the context in which the error occurred.

sessionId

String (optional)

The id of the session, if there is an active session.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'hermes/error/hotword'

Note

This is a Rhasspy-only message.

context: Optional[str] = None

Additional information on the context in which the error occurred.

error: str = None

A description of the error that occurred.

session_id: Optional[str] = None

The id of the session, if there is an active session.

site_id: str = 'default'

The id of the site where the error occurred.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/error/hotword"

Return type

str

class rhasspyhermes.wake.HotwordExampleRecorded(wav_bytes: bytes)[source]

Bases: rhasspyhermes.base.Message

Response when a hotword example has been recorded. Sent by the wake word component in response to a RecordHotwordExample message.

MQTT message

Topic

rhasspy/hotword/<SITE_ID>/exampleRecorded/<REQUEST_ID>

Payload (binary)

Audio from the recorded sample in WAV format.

Subscribe to this message type with mosquitto_sub and show the binary payload as hexadecimal numbers:

mosquitto_sub -h <HOSTNAME> -t 'rhasspy/hotword/<SITE_ID>/exampleRecorded/<REQUEST_ID>' -F %x

Note

This is a Rhasspy-only message.

classmethod get_request_id(topic: str)str[source]

Get request id from MQTT topic.

Parameters

topic – MQTT topic.

Returns

Request ID extracted from the MQTT topic.

Return type

str

Example

>>> from rhasspyhermes.wake import HotwordExampleRecorded
>>> HotwordExampleRecorded.get_request_id("rhasspy/hotword/default/exampleRecorded/foobar")
'foobar'
classmethod get_site_id(topic: str) → Optional[str][source]

Get site id from MQTT topic.

Parameters

topic – MQTT topic.

Returns

Site ID extracted from the MQTT topic.

Return type

str

Example

>>> from rhasspyhermes.wake import HotwordExampleRecorded
>>> HotwordExampleRecorded.get_site_id("rhasspy/hotword/default/exampleRecorded/foobar")
'default'
classmethod is_binary_payload()bool[source]

True if payload is not JSON.

Returns

True

Return type

bool

classmethod is_site_in_topic()bool[source]

True if site id is in topic.

Returns

True

Return type

bool

classmethod is_topic(topic: str)bool[source]

True if topic matches template

payload() → Union[str, bytes][source]

Get binary/string for this message.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Parameters
  • site_id (str) – The id of the site where the wake word component exists.

  • request_id (str) – Unique id of the request message.

Returns

MQTT topic for this message type with the given site id and request id.

Return type

str

Example

>>> from rhasspyhermes.wake import HotwordExampleRecorded
>>> HotwordExampleRecorded.topic(site_id="default", request_id="foobar")
'rhasspy/hotword/default/exampleRecorded/foobar'
wav_bytes: bytes = None

Audio from recorded sample in WAV format.

class rhasspyhermes.wake.HotwordToggleOff(site_id: str = 'default', reason: rhasspyhermes.wake.HotwordToggleReason = <HotwordToggleReason.UNKNOWN: ''>)[source]

Bases: rhasspyhermes.base.Message

Deactivate the wake word component, so pronouncing a wake word won’t trigger a HotwordDetected message.

MQTT message

Topic

hermes/hotword/toggleOff

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where the wake word component should be disabled.

reason

String

The reason for disabling the wake word component.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/hotword/toggleOff' -m '{"siteId": "default", "reason": "dialogueSession"}'
reason: rhasspyhermes.wake.HotwordToggleReason = ''

The reason for disabling the wake word component.

Note

This is a Rhasspy-only attribute.

site_id: str = 'default'

The id of the site where the wake word component should be disabled.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/hotword/toggleOff"

Return type

str

class rhasspyhermes.wake.HotwordToggleOn(site_id: str = 'default', reason: rhasspyhermes.wake.HotwordToggleReason = <HotwordToggleReason.UNKNOWN: ''>)[source]

Bases: rhasspyhermes.base.Message

Activate the wake word component, so pronouncing a wake word will trigger a HotwordDetected message.

MQTT message

Topic

hermes/hotword/toggleOn

Payload (JSON)

Key

Type

Description

siteId

String

The id of the site where the wake word component should be enabled.

reason

String

The reason for enabling the wake word component.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'hermes/hotword/toggleOn' -m '{"siteId": "default", "reason": "dialogueSession"}'
reason: rhasspyhermes.wake.HotwordToggleReason = ''

The reason for enabling the wake word component.

Note

This is a Rhasspy-only attribute.

site_id: str = 'default'

The id of the site where the wake word component should be enabled.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"hermes/hotword/toggleOn"

Return type

str

class rhasspyhermes.wake.HotwordToggleReason[source]

Bases: str, enum.Enum

Reason for hotword toggle on/off.

DIALOGUE_SESSION = 'dialogueSession'

Dialogue session is active.

PLAY_AUDIO = 'playAudio'

Audio is currently playing.

TTS_SAY = 'ttsSay'

Text to speech system is currently speaking.

UNKNOWN = ''

Overrides all other reasons.

class rhasspyhermes.wake.Hotwords(models: List[rhasspyhermes.wake.Hotword], site_id: str = 'default', id: Optional[str] = None)[source]

Bases: rhasspyhermes.base.Message

The list of available hotwords. The wake word component sends this message in response to a request in a GetHotwords message.

MQTT message

Topic

rhasspy/hotword/hotwords

Payload (JSON)

Key

Type

Description

models

List of JSON objects

The list of available hotwords.

siteId

String

The id of the site where hotwords were requested.

id

String (optional)

Unique id passed from the request in the GetHotwords message.

Subscribe to this message type with mosquitto_sub:

mosquitto_sub -h <HOSTNAME> -v -t 'rhasspy/hotword/hotwords'

Note

This is a Rhasspy-only message.

id: Optional[str] = None

Unique id passed from the request in the GetHotwords message.

models: typing.List[Hotword] = None

The list of available hotwords.

site_id: str = 'default'

The id of the site where hotwords were requested.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/hotword/hotwords"

Return type

str

class rhasspyhermes.wake.RecordHotwordExample(id: str, site_id: str = 'default')[source]

Bases: rhasspyhermes.base.Message

Request to record examples of a hotword. The wake word component responds with a HotwordExampleRecorded message.

MQTT message

Topic

rhasspy/hotword/recordExample

Payload (JSON)

Key

Type

Description

id

String

Unique id used in the response message (HotwordExampleRecorded).

siteId

String

The id of the site where the wake word component exists.

Publish this message type with mosquitto_pub:

mosquitto_pub -h <HOSTNAME> -t 'rhasspy/hotword/recordExample' -m '{"siteId": "default", "id": "foobar"}'

Note

This is a Rhasspy-only message.

id: str = None

Unique id used in the response message (HotwordExampleRecorded).

site_id: str = 'default'

The id of the site where the wake word component exists.

classmethod topic(**kwargs)str[source]

Get MQTT topic for this message type.

Returns

"rhasspy/hotword/recordExample"

Return type

str