feat(rime): add WebSocket streaming TTS support

[mcullan]

Summary

Adds opt-in WebSocket streaming to the Rime TTS plugin via a new use_websocket=True constructor argument. The existing HTTP synthesize path is unchanged and remains the default. When enabled, the plugin sets streaming=True and aligned_transcript=True during construction, opens a long-lived pooled WebSocket to Rime's /ws3 endpoint, and emits word-level timestamps via push_timed_transcript.

New constructor arguments

• use_websocket: bool = False — opt into the streaming path. Off by default so existing consumers see no behavior change.
• ws_base_url: str = "wss://users-ws.rime.ai" — overridable for self-hosted deployments, parallel to the existing base_url.
• segment: NotGivenOr[str] = NOT_GIVEN — passed to Rime as a connect-time query param. Defaults to "bySentence" (server-side sentence buffering, mirrors StreamAdapter semantics). Pass "immediate" if the consumer is already feeding sentence-tokenized text and wants to skip server-side buffering.
• tokenizer: NotGivenOr[tokenize.SentenceTokenizer] = NOT_GIVEN — overridable client-side sentence tokenizer. Defaults to tokenize.blingfire.SentenceTokenizer(). Mirrors the hook Cartesia exposes.

Implementation

The streaming class is similar to the implementation in the Cartesia plugin: single-context JSON-envelope WebSocket, base64 PCM audio frames, weakref.WeakSet[SynthesizeStream] for cleanup, utils.ConnectionPool[aiohttp.ClientWebSocketResponse] with max_session_duration=300 and mark_refreshed_on_get=True. Word timestamps are pushed as TimedString.

Connection lifecycle:

• _connect_ws opens the pooled WebSocket using the URL built from current options. Connect-time errors propagate to the outer _run exception block, which classifies aiohttp.ClientResponseError (covering WSServerHandshakeError) as APIStatusError with the HTTP status code preserved.
• _close_ws follows the graceful-shutdown pattern in the Deepgram plugin: send the eos operation, wait one second for the server's ack, suppress-and-log any send or recv errors during teardown so they don't mask the original cause that evicted the connection from the pool.
• update_options invalidates the pool when the WebSocket URL changes, computed via a before/after _ws_url() diff. This automatically handles model swaps, speaker swaps, and any per-model option that participates in the URL.

A small _model_params(opts) helper consolidates the per-model option walking shared between the WebSocket query string and the HTTP JSON body.

Routes through /ws3, which accepts every model the plugin supports (mistv2, mistv3, arcana). The older /ws2 endpoint is not wired in.

Validating

• update_options mid-session: model swap drops the existing pooled connection and reconnects with the new URL. Verified by observing two distinct _connect_ws calls and matching audio output.
• Error propagation: invalid API key surfaces as APIStatusError(status_code=401) with the server message preserved, rather than a generic APIConnectionError.
• Empty-input fast-fail: tts.stream() followed by end_input() with no push_text() raises APIError immediately at the protocol layer rather than hanging on the receive timeout.
• Pool reuse: streams created within the max_session_duration window share the same WebSocket — no new handshake.
• HTTP path unchanged: with use_websocket=False (default), synthesize() behavior is identical to before; _run payload assembly continues to use the same _model_params helper plus HTTP-only fields (samplingRate, reduceLatency for mistv2).

[tinalenguyen]

thanks for the pr, left a comment! also we do not have a rime plugin testing key at the moment, so we can omit the test file edit for now

[tinalenguyen]

i think it might be confusing to pass both the http and wss url, wdyt of keeping base_url and adding logic to detect the prefix to see if it's meant to be streaming? if the base url is not given then we can check via use_websocket (i think use_websocket could supersede the url)

[mcullan]

I like that idea + have implemented it. This is resolved, I believe.

[tinalenguyen]

i tested it out and the websocket path worked well, but when trying rime.TTS() i get:

aiohttp.client_exceptions.WSServerHandshakeError: 400, message='Invalid response status', url='https://users.rime.ai/v1/rime-tts/ws3?speaker=astra&modelId=arcana&audioFormat=pcm&samplingRate=22050&segment=bySentence&lang=eng'

let me know if you're seeing this as well!