Add respeecher tts plugin#3233
Open
mitrushchienkova wants to merge 21 commits into
Open
Conversation
mitrushchienkova
force-pushed
the
add-respeecher-TTS-plugin
branch
from
6450e4e to
9af5141
Compare
mitrushchienkova
force-pushed
the
add-respeecher-TTS-plugin
branch
4 times, most recently
from
d844b57 to
2b09286
Compare
mitrushchienkova
commented
Sep 8, 2025
|
|
||
| Support for [Respeecher](https://respeecher.com/)'s TTS in LiveKit Agents. | ||
|
|
||
| More information is available in the docs for the [Respeecher](https://docs.livekit.io/agents/integrations/tts/respeecher/) integration. |
Author
There was a problem hiding this comment.
How can we add documentation for the new plugin?
longcw
reviewed
Oct 8, 2025
Contributor
There was a problem hiding this comment.
when testing I got an error as following, is this correct to put the api key in the url?
aiohttp.client_exceptions.WSServerHandshakeError: 401, message='Invalid response status', url='wss://api.respeecher.com/v1/public/tts/en-rt/tts/websocket?api_key=[xxx]&source=LiveKit-Plugin-Respeecher-Version&version=0.1.0'
also, could you fix the type checks with mypy mypy --install-types --non-interactive -p livekit.plugins.respeecher
| async def _connect_ws(self, timeout: float) -> aiohttp.ClientWebSocketResponse: | ||
| session = self._ensure_session() | ||
| ws_url = self._opts.base_url.replace("https://", "wss://").replace("http://", "ws://") | ||
| full_ws_url = f"{ws_url}{self._opts.model}/tts/websocket?api_key={self._opts.api_key}&source={API_VERSION_HEADER}&version={API_VERSION}" |
Contributor
There was a problem hiding this comment.
is this the correct that exposes api key in url?
Author
There was a problem hiding this comment.
Hello!
Yes, this is intended since the Websocket protocol doesn't accept custom headers. Sending api keys via query parameters is common workaround. Other plugins, e.g. Cartesia does the same.
However, sending API keys as query parameters should be done only via TLS, so I've added a check for that.
mitrushchienkova
force-pushed
the
add-respeecher-TTS-plugin
branch
from
80047b2 to
1f8db02
Compare
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Different Respeecher models expose different voice catalogs, so a single hardcoded default (samantha) doesn't generalize once ua-rt is available. Make voice_id a required argument and update callers. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The session is lazily obtained from utils.http_context.http_session(), a process-wide shared session. Closing it would break every other plugin and HTTP request in the same job context. Match the pattern used by Cartesia, Resemble, ElevenLabs, Deepgram, and friends. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Preserve APIError/APIStatusError raised inside _recv_task instead of
rewrapping them as a generic APIConnectionError that loses the
original message ("Respeecher returned error: ...").
- Pass conn_options.timeout to ws.receive() so a stalled stream is
detected instead of hanging until external cancellation, matching
the Cartesia/Deepgram pattern.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Retire the old connection pool on model change instead of force-closing it. The model is baked into the WebSocket URL, so the pool must be swapped; force-closing terminated WebSockets held by in-flight streams. Now we hold a reference until aclose(), letting in-flight streams return their connections naturally. - Export SynthesizeStream from the package so callers can use it for type annotations, matching ElevenLabs and other streaming plugins. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
- Snapshot _TTSOptions per stream via dataclasses.replace so concurrent update_options() can't mutate voice_id/voice_settings/etc. mid-stream. - Track end-of-input with an input_ended flag instead of relying on sent_tokenizer_stream.closed. The tokenizer closes as soon as _input_task drains its channel, which fires before the final continue=false request is sent; a per-sentence "done" arriving in that window could terminate the recv loop prematurely. - Use output_emitter.end_segment() in _recv_task instead of end_input(). Closing the AudioEmitter write channel is the base class's job; the plugin only owns segment boundaries (matches Resemble). - Handle aiohttp.WSMsgType.ERROR explicitly so transport-level failures surface immediately instead of waiting for the next receive timeout. Also extracted the duplicated voice-payload construction into a small helper to keep send paths in sync. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds a new TTS plugin for LiveKit Agents, integrating Respeecher’s synthesis and streaming API. It currently supports the English voice model and the Ukrainian voice models.
Why Respeecher?
Respeecher’s technology is notable not just for voice quality but also for its ethical design and safeguards. This integration offers: