feat: add Lokutor TTS plugin

[danivs10]

Summary

Adds livekit-plugins-lokutor, a TTS integration for Lokutor — a CPU-only voice-AI platform (no GPU) with 10 voices (F1–F5, M1–M5) and 32 languages.

The plugin connects to Lokutor's WebSocket TTS API and supports both streaming (stream()) and one-shot (synthesize()) synthesis, following the standard LiveKit plugin conventions:

• utils.ConnectionPool for pooled/prewarmed WebSocket connections (prewarm() supported)
• tts.AudioEmitter for streaming PCM frames
• Typed error mapping (APIStatusError / APITimeoutError / APIConnectionError)
• py.typed (PEP 561)

Usage

from livekit.plugins import lokutor

session = AgentSession(
    stt=deepgram.STT(),
    llm=openai.LLM(),
    tts=lokutor.TTS(voice="F1", language="en"),  # LOKUTOR_API_KEY from env
    vad=silero.VAD.load(),
)

Testing

• 25 unit tests (tests/test_plugin_lokutor_tts.py) covering config, request building, and stream construction.
• Gated live-integration tests (tests/test_integration.py) that run against the real API when LOKUTOR_API_KEY is set, exercising the full connect → request → binary audio → EOS path.
• ruff check and ruff format --check pass.

Notes

Supersedes #5925 (that PR was opened from main, had drifted into conflicts, and shipped an older revision). This one is a clean feature branch on top of current main and uses Lokutor's current canonical request vocabulary (voice / language / speed / steps), with all 32 languages. CLA is already signed.

[CLAassistant]

All committers have signed the CLA.

[danivs10]

Thanks for the review — addressed the flagged issues in the latest commit:

• Custom sample rates corrupt audio — Lokutor's TTS output is a fixed 44.1 kHz, so the configurable sample_rate was removed and the rate is pinned to 44100 (the LiveKit pipeline resamples downstream if needed).
• Provider failures lose typed details — _run now re-raises APIError/APIStatusError instead of collapsing them into a generic APIConnectionError.
• API key in WebSocket URL — the key is now sent via an X-API-Key header instead of the URL query string.
• Provider content in logs / exceptions — unexpected text frames and provider error messages are no longer interpolated into log lines or exception messages.

ruff check, ruff format, and the unit tests pass locally.

[devin-ai-integration]

Devin Review found 1 new potential issue.

3 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

[devin-ai-integration]

🔴 Header authentication blocks all synthesis

Every TTS request sends X-API-Key, but Lokutor's WebSocket handshake accepts only the api_key query parameter. The upgrade fails before either synthesis path can emit audio.

Learn more

Lokutor authenticates /ws/tts during the WebSocket handshake. Its authentication and streaming API documentation specifies ?api_key=... for WebSockets; X-API-Key is documented for REST endpoints. The new request reaches the correct endpoint without the only supported WebSocket credential, so the server rejects it before any JSON synthesis request is sent.

Example: With api_key="sk_test", the plugin connects to wss://api.lokutor.com/ws/tts with an X-API-Key header. Lokutor expects wss://api.lokutor.com/ws/tts?api_key=sk_test, so both stream() and synthesize() fail during connection setup instead of returning audio.

Recommended fix: Confirm and adopt a Lokutor-supported WebSocket authentication mechanism that keeps credentials out of observable URLs. If header authentication is unavailable, coordinate provider support or add explicit sanitization around every URL-bearing exception and telemetry path before retaining query authentication.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[danivs10]

Re: the "Header authentication blocks all synthesis" flag — this is a false positive. Lokutor's WebSocket handshake does accept the X-API-Key header; the public docs previously only mentioned the ?api_key= query parameter (now updated). The server reads X-API-Key first and falls back to the query param.

Verified against production wss://api.lokutor.com/ws/tts:

• Invalid key via X-API-Key header → 401 {"code":"auth.invalid_key"} (the header was read and the key evaluated)
• No auth → 401 {"code":"auth.missing_key"}

If the header were ignored, the header case would return auth.missing_key; it returns auth.invalid_key, confirming the header is honored. Synthesis is unaffected.

The remaining red ruff / type-check checks are unrelated to this plugin — they fail on a pre-existing Duplicate keyword argument "secondary_languages" syntax error in livekit-plugins-elevenlabs on the base branch. This plugin's own ruff, type-check, and unit tests pass.

[danivs10]

This is ready for a maintainer review whenever someone has a moment 🙏

Quick status recap:

• CLA: signed ✅
• Plugin ruff, type-check, and unit-tests pass ✅
• The failing top-level ruff / type-check runs are not from this plugin — they fail on a pre-existing Duplicate keyword argument "secondary_languages" syntax error in livekit-plugins-elevenlabs on main, which breaks those jobs for every open PR right now. Happy to rebase the moment that's fixed on main.

Lokutor is a CPU-only TTS provider (10 voices, 32 languages); the plugin follows the standard conventions (ConnectionPool, AudioEmitter, prewarm, typed errors, py.typed) with unit + gated live-integration tests. Thanks for taking a look!