Skip to main content

Kokoro (local TTS)

Kokoro is the bundled local text-to-speech provider, powered by Kokoro-FastAPI. It runs on your own hardware, speaks the OpenAI-compatible /audio/speech endpoint, and needs no API key. Because the URL is operator config, a custom or local TTS server never has to borrow the built-in openai provider, and real OpenAI TTS keeps working alongside it. The plugin registers both speech seams under the single id kokoro:
  • Batch TTS (registerSpeechProvider) — read aloud, voice notes, auto-TTS and the tts tool, served through messages.tts.provider (see Text-to-speech).
  • Streaming TTS (registerStreamingSpeechProvider) — spoken replies in Voice conversation, served through talk.provider (see Voice conversation sessions).
Kokoro is speech output only. Voice conversation still needs a streaming speech-to-text provider, for example ElevenLabs (see ElevenLabs streaming voice). Website: https://github.com/remsky/Kokoro-FastAPI

Text cleanup before synthesis

WednesdayAI cleans every synthesis request before it reaches Kokoro: markdown, code, emoji and URL paths are removed, and symbols such as ->, >= and TCP/IP are turned into spoken words — see How replies are spoken. Kokoro-FastAPI’s own text normalization (URLs, units, phone numbers) still applies on top of that. If your agent is non-English, turn the English word substitutions off per agent with agents.list[].tts.naturalize.enabled: false. Two Kokoro-specific notes:
  • Speed is honoured. When the client sets a playback speed (0.75 to 2, see Read modes), the plugin forwards a speed field in the JSON body of its /audio/speech request, and Kokoro synthesizes faster or slower with natural pitch. The field is omitted when no speed is set, so the key stays out of the request body for older servers and strict validators.
  • Acronyms are spelled with dotted letters. Kokoro reads a spaced A as the article “a” rather than the letter name, so acronyms such as AMD are spelled A.M.D. before they reach the provider — see Numbers, filenames and acronyms.

Quick start

  1. Run the server:
A GPU image is available as ghcr.io/remsky/kokoro-fastapi-gpu. Confirm the server is up: curl localhost:8880/v1/models should list the kokoro model.
  1. Enable the plugin and select the provider:
  1. Restart the gateway, then confirm with talk.catalog: its speech section should list a kokoro row with configured: true. For the batch path, tts.providers lists the same row.
The plugin is bundled but disabled by default. Enabling it is the only “configured” check the batch provider makes — there is no API key and no reachability probe.

Configuration

Plugin settings live under plugins.entries.kokoro.config: Batch-side overrides live under messages.tts.providers.kokoro and the per-agent agents.list[].tts.providers.kokoro:
Voices can be mixed by joining names with +, for example af_bella+af_sky; the string is passed through verbatim. For Voice conversation only, talk.providers.kokoro.baseUrl overrides the plugin’s config.baseUrl for the streaming seam. Batch synthesis (read aloud, voice notes) always uses the plugin config.baseUrl — a single Kokoro server serves every agent.

Per-agent voices

agents.list[].tts gives each agent its own voice, and it applies everywhere that agent speaks: read aloud, voice notes, auto-TTS, the /tts commands and the tts tool. In the example above the ops agent speaks with am_adam while every other agent uses af_heart. When Voice conversation speaks, the voice resolves in this order:
  1. The active agent’s agents.list[].tts voice for the talk provider.
  2. talk.providers.kokoro.voiceId (the global Talk setting).
  3. messages.tts.providers.kokoro.voice.
  4. The plugin’s default voice (config.voice, af_heart).
Selecting an agent in the web client selects its voice; there is no separate voice picker.

Fallback behaviour

A plugin provider can also serve as a fallback: when the primary provider fails, the gateway tries the built-ins (openai, elevenlabs, edge) and then the remaining plugin providers. Set messages.tts.provider (or the per-agent block) to make Kokoro the primary; it is never auto-selected.

Troubleshooting

Synthesis fails with Kokoro TTS request failed (HTTP ...)

The gateway could not synthesize with the configured endpoint. Check that the server is running (curl localhost:8880/v1/models lists kokoro), that plugins.entries.kokoro.config.baseUrl points at the right port, and that the request model (config.model) is one the server offers. Error messages never echo the URL, because it can carry credentials.

Synthesis fails with Kokoro TTS request failed (network error) or Kokoro TTS request aborted

network error means the request could not reach the server at all — the server is down, the port is wrong, or a firewall blocks it. aborted means the request was cancelled before it finished: the per-request messages.tts.timeoutMs (default 30 seconds) expired, or the read-aloud request was dropped. Kokoro on CPU can be slower than real time for long text; raise timeoutMs or shorten the text.

Synthesis fails with Kokoro TTS response too large

The server returned more than 16 MiB for one synthesis request. This usually means the request hit a non-Kokoro endpoint (for example a proxy or file server at the configured baseUrl). Check plugins.entries.kokoro.config.baseUrl points at the Kokoro-FastAPI server itself.

The kokoro row in talk.catalog or tts.providers reports configured: false

For tts.providers, the batch provider is always configured while the plugin is enabled — check plugins.entries.kokoro.enabled. In talk.catalog’s speech section, a keyless provider like Kokoro is configured as soon as the plugin is enabled and a voice resolves; if the row is unconfigured, enable the plugin and restart the gateway.

Voice conversation reports no configured TTS provider

Kokoro registers only speech (TTS). Voice conversation needs a streaming speech-to-text provider as well — see Voice conversation sessions and ElevenLabs streaming voice.