> ## Documentation Index
> Fetch the complete documentation index at: https://rimelabs-docs-coda-websocket-reference.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.astral.sh/uv/getting-started/installation/). Create a key on the [API Tokens page](https://app.rime.ai/tokens) 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.

<Note>
  WebSocket v1 support is in [Pipecat PR #5629](https://github.com/pipecat-ai/pipecat/pull/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.
</Note>

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

```bash theme={null}
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:

```python theme={null}
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](/docs/pipecat). Install the fork with that guide's extras, then use the TTS configuration above.

## Run the audio demo

[Download the audio demos](/files/coda-audio-demos.zip), extract the archive, and open its `coda-audio-demos` directory. With `RIME_API_KEY` set and a local audio output device available, run:

```bash theme={null}
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](/docs/voices-coda). |
| `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-reference/coda/websockets#text-splitting-and-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](/api-reference/coda/websockets-json). 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](/api-reference/coda/websockets) for the wire protocol, or the [Pipecat agent guide](/docs/pipecat) to connect this service to a browser conversation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.