Wyoming OVOS STT Bridge

Expose any OpenVoiceOS STT plugin as a Wyoming protocol ASR server for use with Home Assistant, Rhasspy, and other Wyoming-compatible voice pipelines.

                         ┌──────────────────────────────────────┐
  Wyoming client         │         wyoming-ovos-stt              │
  (Home Assistant,       │                                      │
   Rhasspy, etc.)        │  ┌────────────────────────────────┐  │
                         │  │   STTAPIEventHandler           │  │
  Transcribe ───────────►│  │                                │  │
  AudioChunk* ──────────►│  │  AudioChunkConverter           │  │
                         │  │  (→ 16kHz/16-bit/mono)         │  │
  AudioStop  ───────────►│  │  asyncio.to_thread() ──────────►│  OVOSSTTFactory
                         │  │  STT.execute(AudioData)        │  └──> STT plugin
  Transcript ◄───────────│  │                                │
  Describe ─────────────►│  │  Info(asr=[AsrProgram(...)])    │
  Info ◄─────────────────│  │                                │
                         │  └────────────────────────────────┘  │
                         └──────────────────────────────────────┘

Features

• Single Transcript response: OVOS STT plugins are non-streaming, so the bridge returns the full text in one Transcript (matching the wyoming-faster-whisper reference).
• Automatic audio conversion: AudioChunkConverter converts all incoming audio to 16 kHz / 16-bit / mono PCM.
• Thread-safe: asyncio.to_thread() offloads the blocking stt.execute() call so the event loop stays responsive.
• Language propagation: The bridge reads language from the Transcribe event and sets it on the Transcript.
• Error reporting: The bridge sends failures back as Wyoming Error events.
• Signal handling: The bridge shuts down gracefully on SIGINT/SIGTERM.

Installation

From PyPI

pip install wyoming-ovos-stt

You also need to install the OVOS STT plugin you intend to bridge, e.g.:

pip install ovos-stt-plugin-server
pip install ovos-stt-plugin-whisper
pip install ovos-stt-plugin-vosk

From source

git clone https://github.com/OpenVoiceOS/wyoming-ovos-stt.git
cd wyoming-ovos-stt
pip install -e .

Configuration

Plugin configuration is read from mycroft.conf under stt.<plugin-name>:

{
  "lang": "en-US",
  "stt": {
    "ovos-stt-plugin-server": {
      "url": "https://stt.openvoiceos.com/stt"
    },
    "ovos-stt-plugin-whisper": {
      "model": "base",
      "language": "en"
    },
    "ovos-stt-plugin-vosk": {
      "model": "vosk-model-small-en-us-0.15"
    }
  }
}

The language is taken from stt.<plugin-name>.lang if set, otherwise from lang at the root level.

Usage

# TCP server using public OVOS STT servers
wyoming-ovos-stt --uri tcp://0.0.0.0:7891 \
                 --plugin-name ovos-stt-plugin-server \
                 --debug

# Local Whisper STT
wyoming-ovos-stt --uri tcp://0.0.0.0:7891 \
                 --plugin-name ovos-stt-plugin-whisper

# Unix socket
wyoming-ovos-stt --uri unix:///run/wyoming-stt.sock \
                 --plugin-name ovos-stt-plugin-vosk

CLI Reference

Note: --uri is required (unlike the TTS and wake-word bridges which default to stdio://) because the STT bridge is designed for persistent TCP connections.

Wyoming Protocol

Transcription flow

Client → Describe
Server → Info(asr=[AsrProgram(name="ovos-stt-plugin-server", ...)])

Client → Transcribe(language="en-US")
Client → AudioStart(rate=16000, width=2, channels=1)
       → AudioChunk (PCM bytes)
       → AudioChunk ...
       → AudioStop
Server → Transcript(text="hello world", language="en-US")

The connection closes after each transcription (single-use handler pattern, matching the upstream wyoming-faster-whisper reference). Audio must be 16 kHz / 16-bit / mono PCM. The bridge converts it automatically.

Supported Plugin Types

Any OVOS STT plugin implementing STT from ovos_plugin_manager.templates.stt:

• ovos-stt-plugin-server: proxy to remote STT servers
• ovos-stt-plugin-whisper: OpenAI Whisper (local)
• ovos-stt-plugin-vosk: Vosk offline speech recognition
• ovos-stt-plugin-chromium: Chrome/Chromium's Web Speech API
• ovos-stt-plugin-pocketsphinx: CMU PocketSphinx
• ovos-stt-plugin-whispercpp: Whisper.cpp binding
• ovos-stt-plugin-fasterwhisper: CTranslate2-accelerated Whisper
• ovos-stt-plugin-google: Google Cloud Speech-to-Text
• ovos-stt-plugin-azure: Microsoft Azure Speech
• ovos-stt-plugin-amazon: Amazon Transcribe

Documentation

Detailed docs live in docs/:

• Configuration
• Home Assistant
• Wyoming protocol

Related projects

• wyoming-ovos-tts: the matching Wyoming bridge for OVOS TTS plugins.
• wyoming-ovos-wakeword: the matching Wyoming bridge for OVOS wake-word plugins.
• ovos-wyoming-docker: Docker images that bundle these bridges.
• ovos-plugin-manager: loads and manages the OVOS STT plugins this bridge exposes.

Credits

Developed by TigreGótico for OpenVoiceOS.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.