repository·main·Indexed 41 days ago
https://github.com/rhasspy/wyoming-openwakewordA Wyoming protocol server for the openWakeWord detection system (version 2.1.0), enabling local wake word detection. It supports custom .tflite models, configurable detection thresholds, and trigger levels. The server can be deployed via Python virtual environments or Docker and provides a CLI for managing connection URIs, refractory periods, and Zeroconf discovery.
To install the server on your local machine, clone the repository and use the provided setup script to configure a Python virtual environment.
git clone https://github.com/rhasspy/wyoming-openwakeword.git
cd wyoming-openwakeword
script/setupYou can run the server as a Docker container. By default, it maps port 10400.
docker run -it -p 10400:10400 rhasspy/wyoming-openwakewordStart the server using the script/run command. You must specify a URI for the server to listen on. By default, using 0.0.0.0 allows connections from any network interface.
script/run --uri 'tcp://0.0.0.0:10400'The server automatically scans directories provided via --custom-model-dir for .tflite files.
To ensure models are correctly identified, the server uses a naming convention where the model ID is extracted from the filename. If a filename contains a version suffix in the format _v[number], the version is stripped to determine the base model_id.
Example filename behavior:
my_wake_word_v1.0.tflite -> model_id becomes my_wake_wordhey_computer.tflite -> model_id becomes hey_computerModels are stored in the internal State object and will be used for detection if they match the requested IDs.
The OpenWakeWordEventHandler allows dynamic switching of active wake word models via Detect events.
When a Detect event is received:
names field from the event.state.custom_models first; if not found, it attempts to load them as built-in Model types.DEFAULT_MODEL (Model.OKAY_NABU).Detector objects for new models and removes any existing detectors that were not requested in the current Detect event.This allows a client to tell the server exactly which wake words it is currently listening for, optimizing resource usage by only running necessary models.
To use custom .tflite wake word models in a Docker container, mount a local directory containing the models to a path inside the container and use the --custom-model-dir flag to point to that path.
docker run -it -p 10400:10400 -v /path/to/custom/models:/custom rhasspy/wyoming-openwakeword \
--custom-model-dir /customWhen running the server via script/run, you can use the following flags to modify behavior:
--custom-model-dir <DIR>: Specifies a directory where the server should look for custom wake word models (in .tflite format).--debug: Enables verbose logging to the console for troubleshooting.Use script/run --help to view all available options.
The OpenWakeWordEventHandler class is an implementation of AsyncEventHandler designed to process Wyoming protocol events for wake word detection. It manages audio conversion, feature extraction, and multiple detector instances.
To use it, you must provide the following parameters during initialization:
threshold: The probability threshold above which a detection is triggered.trigger_level: The number of consecutive high-probability frames required before a detection is emitted.refractory_seconds: The cooldown period (in seconds) after a detection during which further detections for that specific model are ignored.state: A State object containing information about custom models.Key behaviors:
Describe event: Responds by sending Info containing available wake models (both built-in and custom).Detect event: Configures which models the handler should actively monitor. It will load requested models and remove any previously active detectors not included in the new request.AudioStart event: Resets the audio timestamp, feature extractor, and all active detectors.AudioChunk event: Processes incoming audio chunks, extracts features, and runs them through the active detectors. If a detection meets the threshold and trigger level requirements, a Detection event is written to the client.AudioStop event: If no detections occurred during the audio stream, it sends a NotDetected event to the client.from wyoming_openwakeword.handler import OpenWakeWordEventHandler
from wyoming_openwakeword.state import State
# Example initialization (contextual usage)
handler = OpenWakeWordEventHandler(
threshold=0.5,
trigger_level=2,
refractory_seconds=1.0,
state=my_state_instance
)The following command-line arguments are available for the wyoming-openwakeword entrypoint:
--uri URI
unix:// or tcp:// (default: stdio://)
--custom-model-dir PATH
Path to directory with custom wake word models
--threshold FLOAT
Wake word model threshold (0.0-1.0, default: 0.5)
--trigger-level INT
Number of activations before detection (default: 1)
--refractory-seconds FLOAT
Seconds before a wake word can be detected again (default: 2)
--zeroconf [NAME]
Enable discovery over zeroconf with optional name (default: openWakeWord)
--debug
Log DEBUG messages
--log-format FORMAT
Format for log messages
--version
Print version and exit
--model MODELS (Deprecated)
--models-dir DIR (Deprecated)
--preload-model MODEL (Deprecated)
--output-dir DIR (Deprecated)
--debug-probability (Deprecated)The wyoming-openwakeword package provides a command-line interface to start a Wyoming server that performs wake word detection using openWakeWord models. You can specify the connection URI, detection sensitivity, and custom model locations via CLI flags.
--uri: The connection URI for the server. Supports stdio:// (standard input/output) or tcp:// (network connection). Default is stdio://.--threshold: The wake word model detection threshold (0.0 to 1.0). Default is 0.5.--trigger-level: The number of activations required before a detection is triggered. Default is 1.--refractory-seconds: The number of seconds to wait before the same wake word can be detected again. Default is 2.0.--custom-model-dir: Path to a directory containing custom .tflite wake word models. This flag can be used multiple times to include multiple directories.--zeroconf: Enables discovery over Zeroconf. If provided, it uses the name openWakeWord by default. Note: Using Zeroconf requires a tcp:// URI.--debug: Enables DEBUG level logging.--log-format: Customizes the format for log messages.# Example: Running a TCP server with a specific threshold and custom models
python3 -m wyoming_openwakeword --uri tcp://0.0.0.0:10400 --threshold 0.6 --custom-model-dir /path/to/models
# Example: Running with Zeroconf discovery
python3 -m wyoming_openwakeword --uri tcp://0.0.0.0:10400 --zeroconfThe __version__ attribute provides the current version of the wyoming_openwakeword package as a string.
import wyoming_openwakeword
print(wyoming_openwakeword.__version__)The State class is used to maintain the runtime state of the detector, specifically tracking paths to custom models. It contains a custom_models dictionary where keys are model names (strings) and values are the filesystem paths (Path) to those models.
from wyoming_openwakeword.state import State
from pathlib import Path
state = State()
state.custom_models["my_custom_model"] = Path("/path/to/model.tflite")