Pipecat quickstart

Add Coda WebSocket v1 to a Pipecat pipeline, configure the service, and test local audio playback.

Set websocket_url="wss://api.rime.ai/coda/ws" in RimeTTSService to use Coda WebSocket v1. The service handles authorization, message encoding, sentence buffering, audio decoding, and connection reuse.

Install the integration

Use Python 3.11 or later, Git, and uv. Create a key on the API Tokens page and set RIME_API_KEY in your server’s environment. The service sends this key to the selected endpoint. Keep it out of browser code and source control.

WebSocket v1 support is in Pipecat PR #5629. The commands below install the fork at a fixed commit that includes this support. A normal release install does not include the changes in that open PR.

These commands create a project and install the Rime integration from the fork:

uv init --python 3.11 coda-pipecat
cd coda-pipecat
uv add 'pipecat-ai[rime] @ git+https://github.com/naszzz/pipecat.git@6fabc472d330b7f0e9b7b7bd65cf24345f8b57fb'

For an existing project, run the uv add command in its directory. Keep any extras your agent already uses, such as openai, silero, webrtc, and runner. The rime extra installs rime-api, which supplies message definitions for both encodings. Commit uv.lock so deployments use the same dependencies.

Use the service in a pipeline

Replace the TTS service in your existing pipeline with this configuration. Keep it between the LLM and the transport output:

import os

from pipecat.services.rime.tts import RimeTTSService

tts = RimeTTSService(
    api_key=os.environ["RIME_API_KEY"],
    websocket_url="wss://api.rime.ai/coda/ws",
    websocket_protocol="binary",
    sample_rate=24000,
    settings=RimeTTSService.Settings(
        voice="lyra",
        language="en",
    ),
)

The service defaults to binary. Set websocket_protocol="json" to use JSON. Both modes produce mono, signed 16-bit PCM in TTSAudioRawFrame objects. Pipecat passes these frames to your transport for playback.

Because /coda/ws selects Coda, you can omit settings.model, as above, or set it to "coda". A different model raises ValueError. Omitting websocket_url selects the older WS3 interface, even if settings.model="coda".

For browser transport, speech recognition, and an LLM, follow the Pipecat agent guide. Install the fork with that guide’s extras, then use the TTS configuration above.

Run the audio demo

Download the audio demos, extract the archive, and open its coda-audio-demos directory. With RIME_API_KEY set and a local audio output device available, run:

uv run stream_pipecat.py

The script installs the same fork commit and runs a Pipecat pipeline that plays two sentences as audio arrives. It prints Playback complete after the last samples play. You don’t need a browser transport, speech recognition provider, or LLM.

For JSON, run RIME_WEBSOCKET_PROTOCOL=json uv run stream_pipecat.py. See the included README for audio-device setup and troubleshooting.

Use Pipecat frames to send text through the service. The demo sends LLMFullResponseStartFrame, TextFrame objects, and LLMFullResponseEndFrame to represent one streamed reply. In an agent, the LLM service supplies these frames. You can also queue a TTSSpeakFrame for a fixed utterance.

Service parameters

These settings apply to both encodings. Pass the fields prefixed with settings. through RimeTTSService.Settings(...):

Service option	Default	Behavior or wire field
websocket_url	Omitted, selects WS3	Set the full /coda/ws endpoint to select v1.
websocket_protocol	"binary" with v1	"binary" selects rime.v1.binary. "json" selects rime.v1.json. Requires websocket_url.
settings.voice	Omitted	start.speaker. Choose a Coda voice.
settings.language	Omitted	start.language. Set a supported language such as "en", which Pipecat maps to "eng". Omit it to use the server default.
settings.model	Inferred from the v1 endpoint	Must match the model selected by the endpoint.
sample_rate	Pipeline output sample rate	start.audioParameters.samplingRate. The example sets 24000 explicitly.
settings.timeScaleFactor	Omitted, engine default 1.0	start.audioParameters.timeScaleFactor. Below 1 is faster. Above 1 is slower.
settings.text_lookahead_tokens	Omitted, engine default 0	start.codaParameters.textLookaheadTokens. Coda v1 only. See text lookahead.
api_key	Required	Bearer credential in the upgrade header. Pass the environment variable explicitly.
text_aggregation_mode	Sentence aggregation for v1	Buffers text locally into sentences. Token aggregation is rejected.
allow_custom_endpoint	False	Set True only for a trusted custom host. The service sends your API key there. Remote endpoints require wss.

Audio format and protocol limits

The adapter requests audio/pcm only. Set sample_rate=8000 for 8 kHz PCM, then let your telephony transport encode mu-law if it requires that format. The service has no v1 audio_format option.

For splitStrategy or config.defaults, use a direct client. The adapter does not expose these fields. Coda v1 does not return aligned word timestamps.

Move from WS3 to v1

Use websocket_url for the endpoint and settings.timeScaleFactor for speed. Remove the following settings from your configuration. The v1 adapter rejects them.

Purpose	Settings to remove
Legacy endpoint	url
Segmentation and latency	segment, reduceLatency
Speed	speedAlpha, inlineSpeedAlpha
Text normalization	noTextNormalization
Generation	repetition_penalty, temperature, top_p
Custom fields	Custom settings.extra fields
Mist-only options, rejected for Coda	pauseBetweenBrackets, phonemizeBetweenBrackets, saveOovs

Stream lifecycle

One Pipecat turn uses one Coda context. The service opens the context when the first sentence is ready, after the connection has received ready.

Pipecat action	Service behavior
Pipeline starts	Connect and wait for ready.
LLM text arrives	Buffer fragments into sentences. Send an empty start, then sentence text messages in the same context.
LLM response ends	Drain the text buffer and call flush_audio(), which sends end. Continue receiving audio until done.
Server sends done	Emit TTSStoppedFrame and release the context. Keep the socket open.
User interrupts	Send cancel for the interrupted context and discard its later audio.
Settings update	Apply new settings to later contexts. Active contexts keep their initial settings.
Pipeline ends or is cancelled	Close the connection and clean up background tasks.

Pipecat’s flush_audio() finishes input for a context. It is not the same as LiveKit’s local text flush(). Let the pipeline call it at the end of a turn, because the context cannot accept more text after end.

The service checks the negotiated subprotocol, ready.protocol, context IDs, and event order. It reports synthesis failures through ErrorFrame.

Timeouts

Each send has a time limit. This includes time spent waiting for an earlier send:

Write operation	Time limit
Send one sentence, including start if it opens a context	10 seconds
Send end	10 seconds
Send cancel	1 second

Write limits are separate from response timeouts. After sending cancel, the service waits up to another second for the context to finish. You cannot change these limits through the RimeTTSService constructor.

If a send times out, the service cannot tell whether the server received the message. It closes the connection, rejects queued sends on that connection, and fails its active contexts. A later request can use a new connection. Connection failures and response timeouts also prevent reuse of that connection.

Use the Coda WebSocket API reference for the wire protocol, or the Pipecat agent guide to connect this service to a browser conversation.