This release is a pre-release and may not be stable for production use.
OpenVoiceOS TTS Server
ovos-tts-server turns any OVOS TTS plugin into a microservice. It is a small, stateless FastAPI app that exposes text-to-speech over HTTP.
- Plugin-agnostic. Serve Piper, Coqui, Azure, or any OVOS TTS plugin behind one HTTP API.
- Cloud-API compatibility. The server also speaks the ElevenLabs, OpenAI, Coqui, Google, Amazon Polly, Azure, MaryTTS, Cartesia, Deepgram Aura, and PlayHT APIs, so existing clients and SDKs work unmodified. See API compatibility.
- Stateless. Each request loads nothing extra. This suits containers and horizontal scaling.
- Format conversion. The server returns WAV by default, or mp3/ogg/flac/... with the optional
[audio]extra.
Install
pip install ovos-tts-server
# Optional: enable non-WAV output (mp3, ogg, flac, ...) via pydub
pip install "ovos-tts-server[audio]"
You also need at least one TTS plugin, for example Piper:
pip install ovos-tts-plugin-piper
Quickstart
# Start the server with the Piper plugin
ovos-tts-server --engine ovos-tts-plugin-piper
# Synthesize over HTTP
curl "http://localhost:9666/v2/synthesize?utterance=hello%20world" -o hello.wav
Command line
ovos-tts-server [-h] [--engine ENGINE] [--port PORT] [--host HOST] [--cache] [--lang LANG] [--mcp]
| Option | Default | Description |
|---|---|---|
--engine ENGINE |
none | TTS plugin to load (for example ovos-tts-plugin-piper) |
--port PORT |
9666 |
Port to bind |
--host HOST |
0.0.0.0 |
Host/interface to bind |
--cache |
off | Persist every synth to disk (cache across requests) |
--lang LANG |
none | Overrides the plugin's configured language; falls back to the plugin's own configuration, or mul, when omitted |
--mcp |
off | Serve MCP at /mcp (needs the mcp extra) |
Configuration
The plugin is configured exactly as it would be inside the assistant, through mycroft.conf:
{
"tts": {
"module": "ovos-tts-plugin-piper",
"ovos-tts-plugin-piper": {
"model": "alan-low"
}
}
}
See docs/configuration.md for how voice and language flow from a request to the plugin.
Transformer pipelines
The server can run OVOS transformer plugins around synthesis, on every endpoint (native, vendor-compat, websocket, MCP/UTCP). Dialog transformers rewrite the text before synthesis, and tts transformers post-process the audio. Enable them with the standard mycroft.conf sections:
{
"dialog_transformers": {
"ovos-dialog-transformer-openai-plugin": {"rewrite_prompt": "reply in a cheerful tone"}
},
"tts_transformers": {
"ovos-tts-transformer-sox-plugin": {"pitch": 300}
}
}
Enabling a dialog transformer server-side means the server deliberately synthesizes different text than the client sent. Use it to set a tone or persona globally, across every device using this server. See docs/transformers.md for when to use server-side or device-side transformers, and how to avoid processing the text twice.
HTTP API
The native OVOS endpoints:
| Method | Path | Description |
|---|---|---|
| GET | /status |
Plugin name, supported languages, default voice/model |
| GET | /v2/synthesize?utterance=<text>[&lang=...][&voice=...] |
Primary synthesis endpoint. Returns a WAV file |
| GET | /synthesize/<utterance> |
Legacy path-based synthesis endpoint |
The server forwards any extra query parameter on the synthesis endpoints to the plugin as a synthesis option. CORS is enabled for all origins.
curl http://localhost:9666/status
# {"status": "ok", "plugin": "ovos-tts-plugin-piper", "langs": ["en-us"], ...}
Third-party API compatibility
The server can also expose the same plugin behind drop-in compatibility endpoints for popular cloud TTS APIs. Each vendor lives under its own URL prefix, so every compat layer stays active at once with no path collisions. The server accepts auth tokens and API keys but ignores them silently; put real auth in a reverse proxy if you need it.
| Vendor | Prefix | Key endpoint |
|---|---|---|
| ElevenLabs | /elevenlabs |
POST /v1/text-to-speech/{voice_id} |
| OpenAI | /openai |
POST /v1/audio/speech |
| Coqui | /coqui |
GET /api/tts |
| Google Cloud TTS | /google-tts |
POST /v1/text:synthesize |
| Amazon Polly | /amazon-polly |
POST /v1/speech, GET /v1/voices |
| Azure TTS | /azure-tts |
POST /cognitiveservices/v1 |
| MaryTTS | /marytts |
GET/POST /process (plus root aliases) |
| Cartesia | /cartesia |
POST /tts/bytes |
| Deepgram Aura | /deepgram |
POST /v1/speak?model=... |
| PlayHT | /playht |
POST /api/v2/tts/stream (plus pyht SDK auth) |
Kokoro / kokoro-fastapi clients are OpenAI-compatible and need no dedicated prefix. Point them at /openai/v1/audio/speech.
Most official SDKs accept a custom base URL. Point them at http://<host>:9666/<prefix> and they work unmodified. See docs/api-compatibility.md for per-vendor endpoints, parameters, SDK snippets, and curl examples.
Python API
from ovos_tts_server import start_tts_server
app, engine = start_tts_server("ovos-tts-plugin-piper", cache=False)
# `app` is a FastAPI instance: mount it, test it, or run it with uvicorn
create_app(tts_engine) is also available if you want to build and inject the TTSEngineWrapper yourself.
Docker
Build a small image that serves any plugin:
FROM python:3.11-slim
RUN pip install --no-cache-dir "ovos-tts-server[audio]" {PLUGIN_HERE}
ENTRYPOINT ["ovos-tts-server", "--engine", "{PLUGIN_HERE}", "--cache"]
docker build . -t my_ovos_tts_plugin
docker run -p 8080:9666 my_ovos_tts_plugin
curl "http://localhost:8080/v2/synthesize?utterance=hello" -o hello.wav
Each plugin can ship its own Dockerfile in its repository, using ovos-tts-server.
Companion plugin
Consume this server from a voice assistant with the companion TTS plugin.
Development
pip install -e ".[audio,test,mcp]"
pytest test/ -v
Documentation
- API compatibility reference: every vendor prefix, endpoint, and SDK snippet
- Voice & language configuration: how requests map to the plugin
- Transformer pipelines: dialog/tts transformer plugins around synthesis
- Audio format conversion:
convert_audio()and the[audio]extra - AI agents (MCP and UTCP): connect Claude Code, Claude Desktop, OVOS agents and UTCP clients
- Architecture overview: classes, entry points, request flow
AI agent integration
The server works as a tool for AI agents. GET /utcp always serves a UTCP manual. Start the server with --mcp and install the mcp extra to serve an MCP endpoint at /mcp:
pip install --pre "ovos-tts-server[mcp]"
ovos-tts-server --engine ovos-tts-plugin-piper --mcp
claude mcp add --transport http ovos-tts http://localhost:9666/mcp
AI agents (MCP and UTCP) has recipes for Claude Code, Claude Desktop, OVOS agents and UTCP clients, and the tool reference.
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-tts-server 1.15.4a3
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_tts_server-1.15.4a3.tar.gz | 36.9 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ovos_tts_server-1.15.4a3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 80.4 kB
Release files / ovos_tts_server-1.15.4a3.tar.gz
| Download URL | ovos_tts_server-1.15.4a3.tar.gz |
|---|---|
| Size | 36.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4f3a9295e5d6ba7b987c4f16869f78f0e0a4f3dba58ad4f33d1c803b73e183a5
|
|
BLAKE2b-256 checksum How to use checksums |
b08cdc694825f8d3d3a14d49f3bff65adfff11aea5afb74cb6b077d15e8e3fbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ovos_tts_server-1.15.4a3-py3-none-any.whl
| Download URL | ovos_tts_server-1.15.4a3-py3-none-any.whl |
|---|---|
| Size | 43.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a505db757efbb9c0f4cbb74552ef496923cba1d2978ebc65d1e6b515318eb27
|
|
BLAKE2b-256 checksum How to use checksums |
ab35616049e3a5af779e7f9a446aa047d9e4a73c56f908fceb74b4a8b901c65c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for ovos-tts-server 1.15.4a3
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.
