Example: streaming a long document

pip install kova-tts
export KOVA_API_KEY=kova_sk_...

npm install @kova-ai/tts
export KOVA_API_KEY=kova_sk_...

import asyncio, os
from kova_tts import KovaTTSClient, AudioResponseFormat

DOCUMENT = """
Welcome to Kova.
This is the second sentence.
And here is one more, just to round things out.
""".strip().splitlines()


async def main():
    client = KovaTTSClient(api_key=os.environ["KOVA_API_KEY"])
    sample_rate = 32000
    pcm_chunks: list[bytes] = []

    async with client.websocket() as ws:
        await ws.start_context(
            context_id="doc",
            voice_id="cal",
            model_id="default",
            response_format=AudioResponseFormat(encoding="pcm", sample_rate=sample_rate),
        )

        for line in DOCUMENT:
            await ws.send_text(line + " ", context_id="doc")

        await ws.flush(context_id="doc", flush_id="end")

        # Match on OUR flush_id. close_context also emits a flush_completed
        # whose flush_id is the synthetic string "doc:close" — breaking on any
        # flush_completed would exit this loop at the wrong time.
        async for frame in ws:
            if frame.type == "audio":
                pcm_chunks.append(frame.audio)
            elif frame.type == "flush_completed" and frame.flush_id == "end":
                break

        await ws.close_context(context_id="doc")

    # The SDK does not currently expose a WAV-writing helper.
    # Use stdlib `wave` to write a 16-bit mono WAV.
    import wave
    with wave.open("doc.wav", "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)         # 16-bit PCM
        wf.setframerate(sample_rate)
        wf.writeframes(b"".join(pcm_chunks))
    print(f"wrote doc.wav ({sum(len(c) for c in pcm_chunks)} pcm bytes)")


asyncio.run(main())

import { KovaTTSClient, pcm16ToWavBytes } from "@kova-ai/tts";
import { writeFile } from "node:fs/promises";

const DOCUMENT = [
  "Welcome to Kova.",
  "This is the second sentence.",
  "And here is one more, just to round things out.",
];

const client = new KovaTTSClient({ apiKey: process.env.KOVA_API_KEY! });
const sampleRate = 32000;
const pcmChunks: Uint8Array[] = [];

const ws = await client.connectWebSocket();

await ws.startContext({
  contextId: "doc",
  voiceId: "cal",
  modelId: "default",
  responseFormat: { encoding: "pcm", sample_rate: sampleRate },
});

for (const line of DOCUMENT) {
  await ws.sendText("doc", line + " ");
}

await ws.flush("doc", "end");

// Match on OUR flush_id. close_context also emits a flush_completed whose
// flush_id is the synthetic string "doc:close" — breaking on any
// flush_completed would exit this loop at the wrong time.
for await (const frame of ws) {
  if (frame.type === "audio") {
    pcmChunks.push(frame.audio);
  } else if (frame.type === "flush_completed" && frame.flush_id === "end") {
    break;
  }
}

await ws.closeContext("doc");
ws.close();

const total = pcmChunks.reduce((n, c) => n + c.byteLength, 0);
const merged = new Uint8Array(total);
let offset = 0;
for (const c of pcmChunks) { merged.set(c, offset); offset += c.byteLength; }

// The SDK does not currently expose a WAV-writing helper on the client.
// Use the exported `pcm16ToWavBytes` primitive + node:fs to write the file.
const wavBytes = pcm16ToWavBytes(merged, { sampleRate });
await writeFile("doc.wav", wavBytes);
console.log(`wrote doc.wav (${total} pcm bytes)`);