ovos-tts-server 1.14.0a2

simple FastAPI server to host TTS plugins as a service

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]

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	en-us	Default language reported by the plugin

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
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]"
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
• Architecture overview: classes, entry points, request flow

---

Agent integration

UTCP: Universal Tool Calling Protocol

The server exposes a UTCP manual at GET /utcp. Any UTCP-aware agent, for example ovos-tool-adapters' UTCPToolBox, can point at this URL and auto-discover every synthesis endpoint without extra configuration.

GET /utcp needs no extra dependencies. It is always available.

Example response (abbreviated):

{
  "utcp_version": "1.0.1",
  "manual_version": "1.0.0",
  "tools": [
    {
      "name": "tts_synthesize_v2",
      "description": "Synthesize speech from text (OVOS v2 endpoint)...",
      "inputs": {
        "type": "object",
        "properties": {
          "utterance": {"type": "string"},
          "voice":     {"type": "string"},
          "lang":      {"type": "string"}
        },
        "required": ["utterance"]
      },
      "tool_call_template": {
        "call_template_type": "http",
        "url": "http://localhost:9666/v2/synthesize",
        "http_method": "GET"
      }
    }
  ]
}

ovos-tool-adapters config example:

{
  "utcp_config": {
    "providers": [
      {
        "provider_type": "http",
        "name": "ovos-tts",
        "url": "http://localhost:9666/utcp"
      }
    ]
  }
}

---

MCP: Model Context Protocol

The server can optionally expose a FastMCP server mounted at /mcp, providing a synthesize tool callable by any MCP-compatible agent (Claude Desktop, Claude Code, and others).

Install the extra:

pip install "ovos-tts-server[mcp]"

Start with MCP enabled:

ovos-tts-server --engine ovos-tts-plugin-piper --mcp

Or from Python:

from ovos_tts_server import start_tts_server
app, engine = start_tts_server("ovos-tts-plugin-piper", enable_mcp=True)

The MCP server uses streamable HTTP transport (SSE-compatible) and mounts alongside the existing FastAPI app. No separate process is needed.

Claude Desktop claude_desktop_config.json example:

{
  "mcpServers": {
    "ovos-tts": {
      "transport": "http",
      "url": "http://localhost:9666/mcp"
    }
  }
}

synthesize tool:

Parameter	Type	Required	Description
text	string	yes	Text to synthesize
voice	string	no	Voice/speaker identifier
lang	string	no	BCP-47 language code (for example en-us)

Returns a JSON object:

{
  "mime_type": "audio/wav",
  "data": "<base64-encoded WAV>",
  "path": "/tmp/ovos_synth_abc123.wav",
  "phonemes": null
}

---

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.