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 thettstool, served throughmessages.tts.provider(see Text-to-speech). - Streaming TTS (
registerStreamingSpeechProvider) — spoken replies in Voice conversation, served throughtalk.provider(see Voice conversation sessions).
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
speedfield in the JSON body of its/audio/speechrequest, 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
Aas the article “a” rather than the letter name, so acronyms such asAMDare spelledA.M.D.before they reach the provider — see Numbers, filenames and acronyms.
Quick start
- Run the server:
ghcr.io/remsky/kokoro-fastapi-gpu. Confirm the server is up:
curl localhost:8880/v1/models should list the kokoro model.
- Enable the plugin and select the provider:
- Restart the gateway, then confirm with
talk.catalog: itsspeechsection should list akokororow withconfigured: true. For the batch path,tts.providerslists the same row.
Configuration
Plugin settings live underplugins.entries.kokoro.config:
Batch-side overrides live under
messages.tts.providers.kokoro and the per-agent
agents.list[].tts.providers.kokoro:
+, 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:
- The active agent’s
agents.list[].ttsvoice for the talk provider. talk.providers.kokoro.voiceId(the global Talk setting).messages.tts.providers.kokoro.voice.- The plugin’s default voice (
config.voice,af_heart).
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.Related
- Text-to-speech — batch TTS config, per-agent voices, fallback order
- Voice conversation sessions
- ElevenLabs streaming voice
- Register a speech provider