Skip to content
Back to

Text-to-speech

AI Chat can read assistant replies aloud. You choose which engines are available for the workspace from Administration (/admin) under Text-to-speech. Each person picks among those engines on Preferences (omnibar cog, AI section). The composer speaker control only turns voice on or off for the session.

Providers

Section titled “Providers”
Provider How it runs When it appears
Native (browser) Browser Web Speech (speechSynthesis) When the browser supports it (not Firefox/Gecko) and Admin enables it
Local Kokoro Platform Kokoro-FastAPI on the host bridge; Convex returns compressed mp3 When platform TTS is enabled and Admin enables local
Cloud speech OpenAI-compatible /v1/audio/speech via an Admin-selected gateway (openai, openrouter, or llmapi) and your BYOK key When Admin enables openapi and the gateway key is set

There is no automatic failover between providers. If the selected engine fails, Flow shows an error and you switch provider or fix Admin configuration.

Admin configuration

Section titled “Admin configuration”

On Administration → Text-to-speech (/ai/tts) you:

  1. Enable one or more providers and set the workspace default.
  2. Pick a Kokoro voice for local speech (ids stay stable; the UI shows readable labels).
  3. Set cloud speech gateway, model, and voice strings.
  4. Use Test (requires platform:write) against allowlisted endpoints only. A successful Test returns audio and plays a short sample in the browser.

Profile reads and writes require platform:read / platform:write. Chat users with ai:page still speak through a separate chat config path.

User preference

Section titled “User preference”

TTS on/off stays session-local (composer speaker). The selected provider and, for Local Kokoro, your voice live under Preferences → AI (Chat text-to-speech provider), with a Preview control on the same row as the provider pills. If a saved provider is disabled or unavailable, Flow uses the Admin default for speak/UI and does not rewrite the preference until you pick again. On Firefox, Native (browser) is hidden because Web Speech end events are unreliable; use Local Kokoro or cloud speech instead.

Mic and speaker controls sit next to Send in the composer. While the model runs, Flow publishes progressive assistant text on the thread runtime so speech can start before the final message append. Flow speaks completed sentences (and blank-line breaks) as they arrive, then flushes any open tail when the run finishes. Intentional stop/cancel does not show a failure toast; real speak errors still fail closed with an error toast. Preferences Preview and Admin Test unlock audio on click (Web Audio) so playback still works in Firefox after the speak request returns; abort-shaped HTMLAudio errors after successful play are not treated as failures.

Platform Kokoro

Section titled “Platform Kokoro”

Kokoro runs as a shared fontana-gateway singleton (default on). To skip it on a RAM-constrained host, set in fontana.yaml:

platform:
  tts:
    disabled: true

Then run fontana apply. Speech traffic uses the platform host bridge (/v1/audio/speech); health is exposed as /kokoro/health. Post-apply and fontana status record the kokoro Deployment when it exists (same presence gate as Infinity). See Fontana CLI for the full platform.* disable table.

Section titled “Related”
  • BYOK - Cloud speech uses the same gateway API keys as embeddings/LLM routes
  • Gateways - Approved gateways for OpenAI-compatible speech
  • Fontana CLI - platform.tts.disabled for light installs