This release is a pre-release and may not be stable for production use.
OpenVoiceOS STT HTTP Server
Turn any OVOS STT plugin into an HTTP microservice for speech-to-text and spoken-language detection.
Pair it with the companion client plugin to offload transcription from an OVOS device, or point existing tooling at the vendor-compatible endpoints below.
Contents
- Install
- Configuration
- Usage
- HTTP API
- AI agent integration: MCP & UTCP
- Vendor-compatible endpoints
- Docker
- Documentation
- Examples
- Credits
Install
pip install --pre ovos-stt-http-server
The server only hosts plugins. Install at least one STT plugin alongside it:
pip install --pre ovos-stt-plugin-fasterwhisper
Optional extras:
| Extra | Installs | Enables |
|---|---|---|
mcp |
pip install --pre "ovos-stt-http-server[mcp]" |
embedded MCP server at /mcp (requires --mcp flag) |
audio |
pip install --pre "ovos-stt-http-server[audio]" |
non-WAV audio decoding (pydub) for the vendor-compat routers |
Configuration
The STT plugin is configured exactly as it would be inside an assistant, under
mycroft.conf:
{
"stt": {
"module": "ovos-stt-plugin-deepgram",
"ovos-stt-plugin-deepgram": {"key": "xxxxx"}
}
}
Usage
$ ovos-stt-server --help
usage: ovos-stt-server [-h] --engine ENGINE [--lang-engine LANG_ENGINE]
[--host HOST] [--port PORT] [--multi] [--mcp]
options:
-h, --help show this help message and exit
--engine ENGINE STT plugin to be used (required)
--lang-engine LANG_ENGINE audio language-detection plugin to be used (optional)
--host HOST host to bind (default: 0.0.0.0)
--port PORT TCP port (default: 8080)
--multi load one plugin instance per language (more memory)
--mcp mount MCP server at /mcp (requires ovos-stt-http-server[mcp])
For example, to serve faster-whisper for transcription with matching audio language detection:
ovos-stt-server \
--engine ovos-stt-plugin-fasterwhisper \
--lang-engine ovos-audio-transformer-plugin-fasterwhisper
HTTP API
The native API is unauthenticated. Audio is sent as the raw request body.
| Method & path | Body | Purpose |
|---|---|---|
GET /status |
none | Service status and loaded plugin names |
POST /stt |
raw PCM bytes | Transcribe audio → plain-text transcript |
POST /lang_detect |
raw PCM bytes | Detect the spoken language → {"lang", "conf"} |
POST /stt query parameters:
| Parameter | Default | Description |
|---|---|---|
lang |
system lang or auto |
Language code, or auto to run language detection first |
sample_rate |
16000 |
Audio sample rate in Hz |
sample_width |
2 |
Sample width in bytes (2 = int16) |
The body must be raw PCM (16-bit signed, mono). Example with a WAV file decoded to PCM on the fly:
# 16 kHz mono int16 PCM in body
curl -s --data-binary @speech.pcm \
-H 'Content-Type: application/octet-stream' \
'http://localhost:8080/stt?lang=en&sample_rate=16000&sample_width=2'
See examples/native_example.py for a runnable
script that reads a WAV file and posts its PCM frames. Full reference:
docs/index.md.
Transformer pipelines
The server can run OVOS transformer plugins around transcription, on every
endpoint: audio transformers process audio before STT (an
AudioLanguageDetector in the chain resolves lang=auto) and utterance
transformers rewrite the transcript before it is returned. Opt-in via the
standard mycroft.conf sections:
{
"utterance_transformers": {
"ovos-utterance-corrections-plugin": {}
}
}
Enabling an utterance transformer server-side means clients receive a different transcript than the raw STT output. Use it for fleet-wide vocabulary corrections. See docs/transformers.md for when to run transformers server-side vs on-device and how to avoid double-processing.
AI agent integration
Start the server with --mcp to give AI agents a transcribe tool over the
Model Context Protocol. This needs the mcp extra:
pip install --pre "ovos-stt-http-server[mcp]"
ovos-stt-server --engine ovos-stt-plugin-fasterwhisper --mcp
claude mcp add --transport http ovos-stt http://localhost:8080/mcp
Every server also publishes a UTCP manual at GET /utcp, so UTCP clients can
call /stt/json, /lang_detect and /status directly.
docs/ai-agents.md gives recipes for Claude Code, Claude Desktop, opencode, Mistral Vibe, OVOS agents and UTCP clients, the tool reference, and deployment notes.
Vendor-compatible endpoints
The server mounts compat routers under per-vendor prefixes so existing tools and SDKs that already target a cloud STT API can be pointed at your local OVOS instance with only a base-URL / endpoint override. Every router accepts (and silently ignores) the vendor's auth token. Authentication is the job of your reverse proxy.
| Vendor | Prefix | Client (see examples/) |
|---|---|---|
| OpenAI Whisper | /v1/audio/transcriptions |
official openai |
| Groq | /groq/openai/v1/audio/transcriptions |
official groq |
| Deepgram | /deepgram/v1/listen |
official deepgram-sdk |
| Google Cloud STT | /google/v1/speech:recognize |
HTTP |
| AssemblyAI | /assemblyai/v2/... |
official assemblyai |
| Gladia | /gladia/v2/transcription |
HTTP (upload → poll) |
| Speechmatics | /speechmatics/... |
official speechmatics-batch |
| Microsoft Azure Speech | /azure-stt/cognitiveservices/v1 |
HTTP |
| AWS Transcribe | /aws/... |
official boto3 |
| IBM Watson STT | /watson/speech-to-text/v1/recognize |
official ibm-watson |
| ElevenLabs Scribe | /elevenlabs/v1/speech-to-text |
official elevenlabs |
| Wit.ai | /wit/speech |
official wit |
| Chromium Web Speech | /speech-api/v2/recognize |
ovos-stt-plugin-chromium |
| whisper.cpp server | /inference |
HTTP |
| vosk-server (WebRTC) | /vosk-webrtc/offer |
needs the aiortc extra |
A runnable script for each lives in examples/. Full endpoint
reference, per-vendor notes, and network-redirect recipes:
docs/api-compatibility.md.
Docker
Any plugin can be served with a small Dockerfile:
FROM python:3.11-slim
RUN pip install --no-cache-dir --pre \
ovos-stt-http-server \
ovos-stt-plugin-fasterwhisper
EXPOSE 8080
ENTRYPOINT ["ovos-stt-server", "--engine", "ovos-stt-plugin-fasterwhisper"]
Build and run:
docker build -t my-stt-server .
docker run -p 8080:8080 my-stt-server
Each plugin can ship its own Dockerfile in its repository using
ovos-stt-http-server as the base.
Documentation
| Document | Covers |
|---|---|
| docs/index.md | Overview, native HTTP API, architecture, audio format |
| docs/api-compatibility.md | Vendor routers: prefixes, endpoints, clients |
| docs/audio-formats.md | Accepted audio encodings and conversion |
| docs/transformers.md | Audio/utterance transformer plugins around transcription |
| docs/ai-agents.md | MCP and UTCP for AI agents |
| docs/wyoming-integration.md | Home Assistant Voice / Wyoming bridge |
| docs/voice-pihole.md | DNS-redirect + reverse-proxy recipes per vendor |
Examples
examples/ holds one runnable script per vendor router (driving
each vendor's real client SDK where one exists) plus a native-API script. See
examples/README.md.
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.
2 maintainers
Metadata
2 maintainers
Release files for ovos-stt-http-server 0.28.2a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| ovos_stt_http_server-0.28.2a1.tar.gz | 575.5 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ovos_stt_http_server-0.28.2a1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.2 MB
Release files / ovos_stt_http_server-0.28.2a1.tar.gz
| Download URL | ovos_stt_http_server-0.28.2a1.tar.gz |
|---|---|
| Size | 575.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cb51a0d15e736ea8b090ddc0ecb32a258e4cd6ac05371a31ce2f61daafd52f6a
|
|
BLAKE2b-256 checksum How to use checksums |
fc6326d2c5728cba0478b2ab9f0549d92b3589de47fbcdd8fa8c6fc749da91f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ovos_stt_http_server-0.28.2a1-py3-none-any.whl
| Download URL | ovos_stt_http_server-0.28.2a1-py3-none-any.whl |
|---|---|
| Size | 588.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7ecc1a24880c63c12c80f10237ed220efd4df3475a088ac58d43ad1c6367ab1c
|
|
BLAKE2b-256 checksum How to use checksums |
1e01cf1770fb7833aba39687eb6badf438719d46d78c8c2970e6f5e104792514
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for ovos-stt-http-server 0.28.2a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
