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!

[danivs10]

@tinalenguyen would you mind taking a look at this one when you have a moment? I believe it's ready.

CI is fully green as of today. The checks were red until a few hours ago, which I want to flag so it doesn't look like a problem with this PR: it was an unrelated duplicate secondary_languages parameter in the elevenlabs plugin that had landed on main and broke ruff plus both type-check jobs repo-wide. That was already fixed upstream — I merged main in and everything passes now.

Scope: 15 files, all new, entirely inside livekit-plugins/livekit-plugins-lokutor/. No changes to any existing plugin. One line added to the root pyproject.toml for workspace registration, plus the uv.lock entry. No CHANGELOG.md edits, per CONTRIBUTING.

Includes unit + integration tests and two examples, following the structure of the existing TTS plugins. Happy to make any changes you'd like.

[danivs10]

Went through the Devin flags. Three of the four were already addressed in earlier revisions of this branch, so recording the current state for whoever reviews:

• Custom sample rates corrupt audio — resolved; the public sample_rate option was removed and the emitter is fixed at 44.1 kHz.
• Provider failures lose typed details — resolved; except APIError: raise now sits before the broad handler in both ChunkedStream._run and SynthesizeStream._run, so APIStatusError/APIError keep their status, request ID and body.
• Provider content enters log bodies — resolved; both logger.debug calls are static strings with no interpolation.
• API key travels in WebSocket URLs — resolved; the key is sent as an X-API-Key header, not a query parameter.

The remaining one, provider errors escape through exceptions, was raise APIConnectionError() from e. Just pushed 7118c31 changing both sites to raise APIConnectionError(type(e).__name__) from None, since an aiohttp transport error can carry the request URL, headers or a response body and from e keeps all of it on __cause__ for anything that walks the chain. Keeping the exception type preserves diagnosability, which is the "log only safe metadata such as its type" allowance in REVIEW.md, and matches the existing pattern in the cartesia plugin.

Worth noting from e is the more common pattern across the existing plugins (elevenlabs, deepgram, rime), so this is the stricter reading of REVIEW.md rather than a fix to something those got wrong — happy to align either way if you'd prefer consistency with the majority.