JSON quickstart

Stream sentences to Coda with a standard Python WebSocket client and save audio chunks as they arrive.

This Python example sends two sentences in one streaming context and writes PCM audio chunks to a file as they arrive. It needs no audio device. It uses rime.v1.json on wss://api.rime.ai/coda/ws. For the Protobuf variant, use the Protobuf quickstart.

Prepare the client

Install uv and Python 3.11 or later. Create a Rime API key, then set RIME_API_KEY in your server’s environment. Keep the key out of browser code and source control.

Create a project and install the WebSocket client:

uv init --python 3.11 coda-json
cd coda-json
uv add 'websockets>=15,<16'

Stream audio to a file

Save this as stream_json.py. It overwrites output.pcm in the current directory. The sender and receiver run together so audio can arrive while the client sends more text.

import asyncio
import base64
import json
import os

from websockets.asyncio.client import connect

URL = "wss://api.rime.ai/coda/ws"
CONTEXT_ID = "turn-1"


async def receive_event(connection):
    raw = await connection.recv()
    if not isinstance(raw, str):
        raise RuntimeError("Expected a JSON text message")
    event = json.loads(raw)
    if "error" in event:
        raise RuntimeError(f"Rime error: {event['error']}")
    return event


async def send_sentences(connection):
    # Replace this list with complete sentences from your application's input.
    for sentence in ["Hello from Coda. ", "This audio uses the JSON protocol. "]:
        await connection.send(json.dumps({"contextId": CONTEXT_ID, "text": sentence}))
    await connection.send(json.dumps({"contextId": CONTEXT_ID, "end": {}}))


async def receive_audio(connection, output):
    while True:
        event = await receive_event(connection)
        if event.get("contextId") != CONTEXT_ID:
            raise RuntimeError("Unexpected context ID")
        if "started" in event:
            print("Request ID:", event["started"].get("requestId"))
        elif "audio" in event:
            output.write(base64.b64decode(event["audio"], validate=True))
        elif "done" in event:
            return
        elif "cancelled" in event:
            raise RuntimeError("Synthesis was cancelled")


async def main():
    headers = {"Authorization": f"Bearer {os.environ['RIME_API_KEY']}"}
    # This example allows two minutes for the whole operation.
    async with asyncio.timeout(120):
        async with connect(
            URL, additional_headers=headers, subprotocols=["rime.v1.json"]
        ) as connection:
            if connection.subprotocol != "rime.v1.json":
                raise RuntimeError("JSON subprotocol was not selected")
            event = await receive_event(connection)
            if event.get("ready", {}).get("protocol") != 1:
                raise RuntimeError("Expected WebSocket protocol version 1")
            await connection.send(json.dumps({
                "contextId": CONTEXT_ID,
                "start": {
                    "speaker": "lyra",
                    "language": "en",
                    "text": "",
                    "audioParameters": {
                        "audioFormat": "audio/pcm",
                        "samplingRate": 24000,
                    },
                },
            }))
            with open("output.pcm", "wb", buffering=0) as output:
                async with asyncio.TaskGroup() as tasks:
                    tasks.create_task(send_sentences(connection))
                    tasks.create_task(receive_audio(connection, output))
    print("Saved output.pcm")


if __name__ == "__main__":
    asyncio.run(main())

Run the script after setting your API key:

uv run stream_json.py

A successful run prints a request ID and Saved output.pcm. The file contains raw mono, signed 16-bit little-endian PCM at 24 kHz, with no WAV header. A failed run can leave a partial file.

To stream input over time, replace the fixed list in send_sentences with complete sentences from your application. To route audio to a browser, phone system, or player, replace output.write(...) with your audio handler.

The script closes the connection after done. In a persistent application, keep the socket open and start the next turn with a new contextId. Use one receive loop to dispatch events across turns. See lifecycle and interruption handling.

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_json.py

This version plays PCM audio as it arrives and prints Playback complete after the last samples play. The archive includes the playback helper and a README with audio-device setup and troubleshooting.

Use another language or audio format

Set language and speaker together for the desired voice. Set the audio MIME type in audioParameters.audioFormat. Every JSON audio payload is base64 regardless of the selected audio format. Decode it once, then send the bytes to the appropriate player or decoder.

The audio demo accepts only raw PCM. For live playback of MP3, Opus, or WAV, use a streaming decoder for that format and keep it open for the whole context. See audio parameters for sample rates and byte formats.