Quickstart

import { spawn } from "node:child_process";
import WebSocket from "ws";

const API_KEY = process.env.ZEROWEIGHT_API_KEY;
const SAMPLE_RATE = 24000;
const HEADER_BYTES = 12;

// 1 ── Ask for somewhere to connect. Your key travels in this header and
//      nowhere else; what comes back carries a token that expires in seconds.
const session = await fetch(
  "https://api.zeroweight.ai/api/v1/realtime/stream/session",
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-ZW-Api-Key": API_KEY },
    body: JSON.stringify({
      voice_id: "ngocanh",
      format: "pcm_s16le",
      sample_rate: SAMPLE_RATE,
    }),
  },
).then((response) => {
  if (!response.ok) throw new Error(`session refused: ${response.status}`);
  return response.json();
});

// A player that reads mono 16-bit PCM from stdin and plays it as it arrives.
// Raw PCM has nothing to probe, so skip the analysis ffplay would otherwise
// buffer for before it starts playing.
const player = spawn(
  "ffplay",
  [
    "-nodisp", "-autoexit", "-loglevel", "error",
    "-probesize", "32", "-analyzeduration", "0",
    "-f", "s16le", "-sample_rate", String(SAMPLE_RATE),
    "-i", "-",
  ],
  { stdio: ["pipe", "ignore", "inherit"] },
);
player.on("error", () => {
  console.error("ffplay not found: install ffmpeg and make sure it is on PATH");
  process.exit(1);
});
player.on("exit", () => console.log("playback finished"));

// 2 ── Open it.
const socket = new WebSocket(session.url);
let finished = false;

socket.on("open", () => {
  // 3 ── One context is one utterance. Several synthesize messages on the same
  //      context_id queue seamlessly, which is how you feed an LLM's output
  //      sentence by sentence.
  socket.send(JSON.stringify({
    type: "synthesize",
    context_id: "turn-1",
    text: "Xin chào. Tôi có thể giúp gì cho bạn?",
    segment_mode: "auto",
  }));
  // Optional but recommended: it lets the gateway release the slot without
  // waiting for a timeout.
  socket.send(JSON.stringify({ type: "end", context_id: "turn-1" }));
});

socket.on("message", (data, isBinary) => {
  if (isBinary) {
    // 4 ── 12-byte header, then mono 16-bit little-endian PCM. Straight to
    //      the speakers; nothing waits for the rest of the utterance.
    if (data.length <= HEADER_BYTES) return;
    player.stdin.write(data.subarray(HEADER_BYTES));
    return;
  }

  const message = JSON.parse(data.toString());
  if (message.type === "context_done") {
    finished = true;
    socket.close(1000);
  }
  if (message.type === "error") console.error(message);
});

// 5 ── Close ends the billing. This one closes itself on context_done above;
//      ending stdin lets ffplay finish what it holds and exit.
socket.on("close", (code, reason) => {
  // After context_done the gateway may drop the line rather than answer the
  // close (1006); the audio is already complete, so only an early close matters.
  if (!finished) console.error(`closed ${code}: ${reason}`);
  player.stdin.end();
});

const SAMPLE_RATE = 24000;
const HEADER_BYTES = 12;
/** Held before starting playback. Below ~100 ms a hiccup in delivery is
 *  audible as a gap; much above it and you have spent the latency you paid
 *  the streaming API to save. */
const JITTER_MS = 120;

export class StreamPlayer {
  private context = new AudioContext({ sampleRate: SAMPLE_RATE });
  /** When the next buffer should start, on the context's own clock. */
  private playhead = 0;

  /** One binary frame off the socket. */
  push(frame: ArrayBuffer): void {
    if (frame.byteLength <= HEADER_BYTES) return;

    // Read out explicitly little-endian: a typed-array view takes the
    // platform's byte order, and the wire format is pcm_s16le regardless.
    const view = new DataView(frame);
    const count = (frame.byteLength - HEADER_BYTES) >> 1;
    const buffer = this.context.createBuffer(1, count, SAMPLE_RATE);
    const samples = buffer.getChannelData(0);
    for (let i = 0; i < count; i++) {
      samples[i] = view.getInt16(HEADER_BYTES + i * 2, true) / 0x8000;
    }

    const source = this.context.createBufferSource();
    source.buffer = buffer;
    source.connect(this.context.destination);

    // Behind the clock means we underran: restart the buffer rather than
    // scheduling into the past, which plays everything at once.
    const now = this.context.currentTime;
    if (this.playhead < now) this.playhead = now + JITTER_MS / 1000;
    source.start(this.playhead);
    this.playhead += buffer.duration;
  }
}

const player = new StreamPlayer();
const socket = new WebSocket(session.url);
socket.binaryType = "arraybuffer";
socket.onmessage = (event) => {
  if (typeof event.data !== "string") player.push(event.data);
};