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:

DialogueNotification
DialogueAction with the attribute canBeEnqueued set to True.

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, custom_data: Optional[str] = None, asr_confidence: Optional[float] = None, custom_entities: Optional[Dict[str, Any]] = 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.
customData	String (optional)	Custom data provided by message that started (`rhasspyhermes.dialogue.DialogueStartSession`), continued (`rhasspyhermes.dialogue.DialogueContinueSession`) or ended (`rhasspyhermes.dialogue.DialogueEndSession`) 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, "customData": null}'
>>> query.topic()
'hermes/nlu/query'

asr_confidence: Optional[float] = None¶: Speech recognizer confidence score between 0 and 1 (1 being sure).

Note

This is a Rhasspy-only attribute.

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.

Note

This is a Rhasspy-only attribute.

custom_entities: Optional[Dict[str, Any]] = None¶: User-defined entities to be set in the recognized intent. Copied by the dialogue manager into subsequent ASR and NLU messages.

Note

This is a Rhasspy-only attribute.

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, custom_entities: Optional[Dict[str, Any]] = 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.

custom_entities: Optional[Dict[str, Any]] = None¶: User-defined entities to be set in the recognized intent. Copied by the dialogue manager into subsequent ASR and NLU messages.

Note

This is a Rhasspy-only attribute.

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