WebSocket Response Handling

Python
TypeScript

def tts_websocket_response_handling(client: Cartesia) -> None:
    """WebSocket response type handling."""
    with client.tts.websocket_connect() as ws:
        ctx = ws.context(
            model_id="sonic-latest",
            voice={"mode": "id", "id": "6ccbfb76-1fc6-48f7-b71d-91ac6298247b"},
            output_format={"container": "raw", "encoding": "pcm_s16le", "sample_rate": 44100},
            language="en",
        )
        ctx.push(
            "Hello, world!",
            continue_=False,  # equivalent to ctx.push() then ctx.no_more_inputs()
        )

        import datetime

        filename = f"tts_websocket_response_handling_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.pcm"

        # Write chunks to file as they arrive.
        # You could also send chunks over the network, play them in real-time, etc.
        with open(filename, "wb") as f:
            for response in ctx.receive():
                if response.type == "chunk" and response.audio:
                    f.write(response.audio)
                elif response.type == "timestamps":
                    print("got timestamps")
                elif response.type == "error":
                    print(f"error: {response.message or response.title}")

                if response.done:
                    break

        print(f"Saved audio to {filename}")
        print(f"Play with: ffplay -f s16le -ar 44100 {filename}")

From cartesia-python/examples/examples.py:458

async function ttsWebsocketResponseHandling(client: Cartesia): Promise<void> {
  const ws = await client.tts.websocket();
  ws.on('error', (err) => console.error('WS error:', err.message));

  const filename = `tts_websocket_response_handling_${timestamp()}.pcm`;
  const file = fs.createWriteStream(filename);

  try {
    const ctx = ws.context({
      model_id: 'sonic-latest',
      voice: { mode: 'id', id: '6ccbfb76-1fc6-48f7-b71d-91ac6298247b' },
      output_format: { container: 'raw', encoding: 'pcm_f32le', sample_rate: 44100 },
      language: 'en',
      add_timestamps: true,
    });

    await ctx.push({
      transcript: 'Hello, world!',
    });
    await ctx.no_more_inputs();

    for await (const event of ctx.receive()) {
      if (event.type === 'chunk') {
        if (event.audio) file.write(event.audio);
      } else if (event.type === 'timestamps') {
        const wt = event.word_timestamps;
        if (wt) {
          console.log(`Words: ${wt.words}, Starts: ${wt.start}, Ends: ${wt.end}`);
        }
      } else if (event.type === 'error') {
        throw new Error(`${event.title}: ${event.message}`);
      }
    }

    console.log(`Saved audio to ${filename}`);
    console.log(`Play with: ffplay -f f32le -ar 44100 ${filename}`);
  } finally {
    file.end();
    ws.close();
  }
}

From cartesia-js/examples/node_examples.ts:417

Run this example

Python
TypeScript

git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python
cd cartesia-python
uv sync
CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py tts_websocket_response_handling

git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js
cd cartesia-js
pnpm i
CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts ttsWebsocketResponseHandling

​Run this example

Run this example