@breeze.blue/sdk 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,10 +1,67 @@
 # Changelog
 
+## 0.5.0
+
+- Fixed `textToSpeech.realtime.connect(...)` so a failed WebSocket handshake
+  rejects instead of hanging: added a handshake timeout (connect `timeout`,
+  falling back to the client `timeout`), rejected clean closes that arrive
+  before the socket opens, and closed the socket on every failure path.
+- Breaking (compile time): the client constructor accepts a missing API key,
+  so `BreezeBlueClient.apiKey` is now typed `string | undefined` instead of
+  `string`. The constructor no longer throws on a missing key; the first REST
+  call throws `BreezeBlueConfigurationError` instead, so browser clients can
+  use `textToSpeech.realtime.connect({ clientSecret })` without a key. Code
+  that read `client.apiKey` as a `string` must narrow it first, and code that
+  relied on the constructor throwing must handle the error at the first
+  request.
+- Bounded the realtime receive buffer at 16 MiB. If messages are not consumed,
+  the SDK closes the connection and the message iterator rejects with a
+  `BreezeBlueRealtimeError`.
+- Added `BreezeBlueRealtimeError` for realtime connection failures the SDK
+  detects (invalid server frames, receive-buffer overflow). It carries the
+  same fields as the Python SDK's `RealtimeError` — `code`, `meta`,
+  `closeCode`, `reconnect`, and `recoverable` (`true` only when just the
+  active turn was cancelled and the connection stays usable; SDK-detected
+  connection failures are never recoverable).
+- Fixed invalid JSON text frames on a realtime connection: instead of the
+  `JSON.parse` exception escaping from the WebSocket `onmessage` callback
+  (leaving the connection neither failed nor finished), the SDK now fails the
+  connection and the message iterator rejects with a
+  `BreezeBlueRealtimeError`, matching the Python SDK.
+- Added `connection.ping()` for realtime keepalive; the server answers with a
+  `pong` event.
+- Guarded `connection.close()` so it no longer throws when the underlying
+  WebSocket is not open.
+- Breaking (compile time): `RealtimeTextToSpeechEvent` changed from an open
+  record (`{ type: string; [key: string]: unknown }`) to a discriminated
+  union of per-event interfaces with camelCase fields (`turnId`,
+  `historyItemId`, `ttfaMs`, ...). Code that indexed arbitrary keys on an
+  event must narrow on `event.type` first (or cast). The union is
+  non-exhaustive by design: unknown future event types are still delivered
+  at runtime, so do not rely on an exhaustive `switch` — ignore event types
+  you do not recognize.
+- Exported the `RealtimeTextToSpeechConnection` class from the root
+  entrypoint.
+- `realtime.connect` now warns when session parameters (`modelId`,
+  `voiceSettings`, ...) are passed together with `clientSecret` or
+  `websocketUrl`, which ignore them.
+- Clarified the missing-WebSocket error and README: realtime needs a global
+  WebSocket (browsers, edge runtimes, Node 22+) or a `webSocket` constructor
+  passed to the client.
+- Reworked the README realtime examples into a consume-and-close loop and
+  added keepalive, pre-created session, and browser `clientSecret` handoff
+  examples.
+
 ## 0.4.1
 
 - Renamed the instruction-only text-to-speech helper to
   `client.textToSpeech.enhance(...)` and aligned it with
   `/v1/text-to-speech/enhance`.
+- Documented the streaming text-to-speech default as `pcm`, added `wav`
+  streaming examples, and taught the Node `stream(...)` helper to pass raw PCM
+  playback options to mpv.
+- Added realtime conversation text-to-speech helpers under
+  `client.textToSpeech.realtime` for fixed-PCM WebSocket sessions.
 
 ## 0.4.0
 

package/README.md

@@ -30,6 +30,10 @@ export BREEZE_API_KEY=brz_...
 The SDK sends the key with the `xi-api-key` header. It also sends
 `x-breeze-sdk` for server-side observability.
 
+An API key is required for every REST method. The one exception is
+`textToSpeech.realtime.connect(...)` with a `clientSecret`, which lets a
+browser client run without a key (see the realtime section below).
+
 ## Quickstart
 
 ```ts
@@ -100,6 +104,102 @@ if (status.status === "ready") {
 If the job is still active, `downloadAudio(...)` rejects with
 `BreezeBlueGenerationNotReadyError`; read `error.retryAfter` before retrying.
 
+Use realtime text-to-speech when one WebSocket connection should handle multiple
+conversation turns. Realtime audio is fixed to raw `pcm_s16le`, 24000 Hz, mono,
+16-bit frames.
+
+Realtime needs a `WebSocket` implementation. Browsers, edge runtimes, and
+Node 22+ provide a global one; on Node 20, pass a constructor (for example the
+`ws` package's `WebSocket`) via `new BreezeBlueClient({ webSocket })`.
+
+```ts
+const connection = await client.textToSpeech.realtime.connect("voc_...", {
+  modelId: "bluebell-v1",
+});
+
+connection.startTurn("turn_1");
+connection.appendText("Hello from Breeze.");
+connection.flush();
+connection.endTurn();
+
+const pcmChunks: Uint8Array[] = [];
+for await (const message of connection) {
+  if (message.type === "audio") {
+    pcmChunks.push(message.audio);
+    continue;
+  }
+  if (message.type === "error") {
+    throw new Error(`Realtime TTS failed: ${message.code}: ${message.message}`);
+  }
+  if (message.type === "turn.done") {
+    break; // all audio for this turn has been delivered
+  }
+}
+connection.close();
+```
+
+Always consume the connection (or its `audio()` / `events()` iterators) while a
+turn is active, and call `close()` when you are done. When the SDK detects a
+connection failure — an invalid server frame, or more than 16 MiB of messages
+piling up unconsumed — it closes the connection and the iterator rejects with
+a `BreezeBlueRealtimeError`.
+
+Events are a typed discriminated union (`session.ready`, `turn.started`,
+`audio.started`, `turn.done`, `turn.cancelled`, `usage.committed`,
+`session.closed`, `error`, `pong`), with camelCase fields such as `turnId`,
+`historyItemId`, and `ttfaMs`. Treat the union as non-exhaustive: the server
+may add event types, and the SDK delivers unknown JSON events unchanged —
+ignore event types you do not recognize instead of switching exhaustively.
+
+For connections that sit idle between turns, send a keepalive ping inside the
+session's `inactivityTimeoutSeconds` window; the server answers with a `pong`
+event:
+
+```ts
+const keepalive = setInterval(() => connection.ping(), 30_000);
+// ... run turns ...
+clearInterval(keepalive);
+connection.close();
+```
+
+To cut time to first audio, create the session ahead of time (for example while
+your app is still preparing the turn) and connect with its `clientSecret` when
+the first text is ready — only the WebSocket handshake remains:
+
+```ts
+const session = await client.textToSpeech.realtime.createSession("voc_...", {
+  modelId: "bluebell-v1",
+});
+
+// Later, when the first text is ready:
+const connection = await client.textToSpeech.realtime.connect("voc_...", {
+  clientSecret: session.clientSecret,
+});
+```
+
+The same `clientSecret` handoff lets a browser connect without ever seeing your
+API key: create the session on your server, hand `session.clientSecret` to the
+page, and build a key-less client there:
+
+```ts
+// Browser — no API key required for clientSecret connections.
+const browserClient = new BreezeBlueClient();
+const connection = await browserClient.textToSpeech.realtime.connect("voc_...", {
+  clientSecret, // received from your server
+});
+```
+
+Session parameters (`modelId`, `languageCode`, `instructions`, `voiceSettings`,
+`inactivityTimeoutSeconds`, `enableLogging`) are fixed when the session is
+created. `connect` ignores them when `clientSecret` or `websocketUrl` is
+provided and logs a warning.
+
+If a realtime WebSocket is interrupted by a network change, service deployment,
+or upstream realtime worker restart, handle `error.meta.reconnect === true` or a
+`session.closed` event with `reconnect === true` by creating a new connection and
+starting a new turn from your own conversation state. Active turns are not
+resumed in place.
+
 The API uses the default text-to-speech model when `modelId` is omitted. If
 you need to select a model explicitly, call `client.models.list()` and pass one
 of the returned `modelId` values.
@@ -130,6 +230,10 @@ await save(audio, "x.mp3");
 await stream(audioStream); // mpv
 ```
 
+Streaming text-to-speech defaults to `pcm` to reduce time to first audio. Pass
+`{ outputFormat: "wav" }` or `{ outputFormat: "mp3" }` when you need that wire
+format explicitly.
+
 ## Voices
 
 Browse existing voices and inspect a single voice:

package/dist/audio.d.ts

@@ -10,6 +10,12 @@ export interface StreamPlaybackCommand {
     command: string;
     args: string[];
 }
+export interface StreamPlaybackCommandOptions {
+    contentType?: string | null;
+    sampleRate?: number | null;
+    channels?: number | null;
+    sampleFormat?: string | null;
+}
 export interface AudioResponseOptions {
     filename?: string | null;
 }
@@ -45,5 +51,5 @@ export declare function selectAudioPlaybackCommand(params: {
     availability: CommandAvailability;
     platform: string;
 }): PlaybackCommand;
-export declare function selectStreamPlaybackCommand(): StreamPlaybackCommand;
+export declare function selectStreamPlaybackCommand(options?: StreamPlaybackCommandOptions): StreamPlaybackCommand;
 export declare function extensionForContentType(contentType: string): string;

package/dist/audio.js

@@ -55,8 +55,17 @@ export function selectAudioPlaybackCommand(params) {
     }
     throw new Error("No supported audio player found. Install ffplay, or use afplay on macOS.");
 }
-export function selectStreamPlaybackCommand() {
-    return { command: "mpv", args: ["--no-terminal", "--really-quiet", "-"] };
+export function selectStreamPlaybackCommand(options = {}) {
+    const args = ["--no-terminal", "--really-quiet"];
+    if (isPcmContentType(options.contentType)) {
+        args.push("--demuxer=rawaudio", `--demuxer-rawaudio-rate=${options.sampleRate ?? 24000}`, `--demuxer-rawaudio-channels=${options.channels ?? 1}`, `--demuxer-rawaudio-format=${options.sampleFormat ?? "s16le"}`);
+    }
+    args.push("-");
+    return { command: "mpv", args };
+}
+function isPcmContentType(contentType) {
+    const mediaType = (contentType ?? "").split(";", 1)[0].trim().toLowerCase();
+    return mediaType === "audio/pcm" || mediaType === "audio/x-pcm" || mediaType.endsWith("/pcm");
 }
 function nodeHelperError(action) {
     return new Error(`Use @breeze.blue/sdk/node to ${action} in Node.js runtimes.`);

package/dist/client.d.ts

@@ -1,9 +1,10 @@
 import { AudioResponse } from "./audio.js";
-import type { AudioRequestOptions, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsEnhanceRequest, TtsEnhanceResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceEditRequest, VoiceList, VoiceSearchParams, VoiceSettings } from "./types.js";
+import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, RealtimeTextToSpeechConnectOptions, RealtimeTextToSpeechEvent, RealtimeTextToSpeechMessage, RealtimeTextToSpeechSession, RealtimeTextToSpeechSessionRequest, SavedVoice, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsEnhanceRequest, TtsEnhanceResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceEditRequest, VoiceList, VoiceSearchParams, VoiceSettings } from "./types.js";
 export declare class BreezeBlueClient {
-    readonly apiKey: string;
+    readonly apiKey: string | undefined;
     readonly baseUrl: string;
     readonly fetch: typeof fetch;
+    readonly webSocket: BreezeBlueClientOptions["webSocket"];
     readonly headers: HeadersInit | undefined;
     readonly timeout: number | undefined;
     readonly textToSpeech: TextToSpeechResource;
@@ -20,12 +21,48 @@ export declare class BreezeBlueClient {
 }
 declare class TextToSpeechResource {
     private readonly client;
+    readonly realtime: RealtimeTextToSpeechResource;
     constructor(client: BreezeBlueClient);
     convert(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<AudioResponse>;
     createJob(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<AsyncTextToSpeechJob>;
     stream(voiceId: string, request: TextToSpeechRequest, options?: StreamTextToSpeechOptions): Promise<AudioResponse>;
     enhance(request: TtsEnhanceRequest, options?: RequestOptions): Promise<TtsEnhanceResponse>;
 }
+declare class RealtimeTextToSpeechResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    createSession(voiceId: string, request?: RealtimeTextToSpeechSessionRequest, options?: RequestOptions): Promise<RealtimeTextToSpeechSession>;
+    connect(voiceId: string, options?: RealtimeTextToSpeechConnectOptions): Promise<RealtimeTextToSpeechConnection>;
+}
+export declare class RealtimeTextToSpeechConnection implements AsyncIterable<RealtimeTextToSpeechMessage> {
+    private readonly socket;
+    private readonly queue;
+    private readonly waiters;
+    private closed;
+    private queuedBytes;
+    private failure;
+    private constructor();
+    static open(socket: BreezeBlueWebSocket, options?: {
+        timeout?: number;
+    }): Promise<RealtimeTextToSpeechConnection>;
+    startTurn(turnId?: string): void;
+    appendText(text: string): void;
+    flush(): void;
+    endTurn(): void;
+    cancelTurn(): void;
+    /** Send a keepalive ping. The server answers with a `pong` event. */
+    ping(): void;
+    close(): void;
+    events(): AsyncIterable<RealtimeTextToSpeechEvent>;
+    audio(): AsyncIterable<Uint8Array>;
+    [Symbol.asyncIterator](): AsyncIterator<RealtimeTextToSpeechMessage>;
+    private sendJson;
+    private handleMessage;
+    private handleClose;
+    private push;
+    private fail;
+    private finish;
+}
 declare class GenerationJobsResource {
     private readonly client;
     constructor(client: BreezeBlueClient);
@@ -65,7 +102,7 @@ declare class VoicesResource {
     /** Stream the audio of a clone or design preview before saving. */
     streamPreview(generatedVoiceId: string, options?: AudioRequestOptions): Promise<AudioResponse>;
     /** Persist a clone or design preview as a real voice asset. */
-    savePreview(request: SaveVoiceRequest, options?: RequestOptions): Promise<Voice>;
+    savePreview(request: SaveVoiceRequest, options?: RequestOptions): Promise<SavedVoice>;
 }
 declare class HistoryResource {
     private readonly client;

package/dist/client.js

@@ -1,13 +1,17 @@
 import { AudioResponse } from "./audio.js";
-import { BreezeBlueConfigurationError, errorFromResponse } from "./errors.js";
+import { BreezeBlueConfigurationError, BreezeBlueRealtimeError, errorFromResponse } from "./errors.js";
 import { camelizeKeys, snakeizeKeys } from "./_transform.js";
 import { SDK_NAME, SDK_VERSION } from "./version.js";
 const DEFAULT_BASE_URL = "https://api.breeze.blue";
 const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS = 30_000;
+const REALTIME_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+const WEBSOCKET_OPEN = 1;
 export class BreezeBlueClient {
     apiKey;
     baseUrl;
     fetch;
+    webSocket;
     headers;
     timeout;
     textToSpeech;
@@ -19,13 +23,12 @@ export class BreezeBlueClient {
     constructor(options = {}) {
         const envApiKey = typeof process !== "undefined" ? process.env.BREEZE_API_KEY : undefined;
         const envBaseUrl = typeof process !== "undefined" ? process.env.BREEZE_BASE_URL : undefined;
-        const apiKey = options.apiKey ?? envApiKey;
-        if (!apiKey) {
-            throw new BreezeBlueConfigurationError("Missing Breeze API key. Pass apiKey or set BREEZE_API_KEY.");
-        }
-        this.apiKey = apiKey;
+        // An API key is only required for REST calls; realtime.connect with a
+        // clientSecret works without one, so missing keys are reported lazily.
+        this.apiKey = options.apiKey ?? envApiKey;
         this.baseUrl = normalizeBaseUrl(options.baseUrl ?? envBaseUrl ?? DEFAULT_BASE_URL);
         this.fetch = options.fetch ?? globalThis.fetch;
+        this.webSocket = options.webSocket ?? readGlobalWebSocket();
         this.headers = options.headers;
         this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
         this.textToSpeech = new TextToSpeechResource(this);
@@ -48,6 +51,10 @@ export class BreezeBlueClient {
         return new AudioResponse(response);
     }
     async request(method, path, params, body, options) {
+        if (!this.apiKey) {
+            throw new BreezeBlueConfigurationError("Missing Breeze API key. Pass apiKey or set BREEZE_API_KEY. " +
+                "(Only textToSpeech.realtime.connect with a clientSecret works without one.)");
+        }
         const signal = buildAbortSignal(options?.signal, options?.timeout ?? this.timeout);
         const wireParams = params ? snakeizeKeys(params) : undefined;
         const wireBody = transformRequestBody(body);
@@ -69,7 +76,9 @@ export class BreezeBlueClient {
     }
     buildHeaders(body, requestHeaders) {
         const headers = new Headers(this.headers);
-        headers.set("xi-api-key", this.apiKey);
+        if (this.apiKey) {
+            headers.set("xi-api-key", this.apiKey);
+        }
         headers.set("x-breeze-sdk", `${SDK_NAME}/${SDK_VERSION}`);
         mergeHeaders(headers, requestHeaders);
         if (body !== undefined && !(body instanceof FormData) && !headers.has("content-type")) {
@@ -80,8 +89,10 @@ export class BreezeBlueClient {
 }
 class TextToSpeechResource {
     client;
+    realtime;
     constructor(client) {
         this.client = client;
+        this.realtime = new RealtimeTextToSpeechResource(client);
     }
     convert(voiceId, request, options = {}) {
         return this.client.requestAudio("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, { outputFormat: options.outputFormat }, request, options);
@@ -100,6 +111,233 @@ class TextToSpeechResource {
         return this.client.requestJson("POST", "/v1/text-to-speech/enhance", undefined, request, options);
     }
 }
+class RealtimeTextToSpeechResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    createSession(voiceId, request = {}, options) {
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/realtime-sessions`, undefined, request, options);
+    }
+    async connect(voiceId, options = {}) {
+        if ((options.clientSecret !== undefined || options.websocketUrl !== undefined) && hasRealtimeSessionParams(options)) {
+            console.warn("@breeze.blue/sdk: realtime.connect ignores modelId, languageCode, instructions, voiceSettings, " +
+                "inactivityTimeoutSeconds, and enableLogging when clientSecret or websocketUrl is provided. " +
+                "Configure these when creating the realtime session instead.");
+        }
+        const websocketUrl = options.websocketUrl ??
+            (options.clientSecret
+                ? buildUrl(this.client.baseUrl.replace(/^http/i, "ws"), `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream-input`, { client_secret: options.clientSecret })
+                : (await this.createSession(voiceId, {
+                    modelId: options.modelId,
+                    languageCode: options.languageCode,
+                    instructions: options.instructions,
+                    voiceSettings: options.voiceSettings,
+                    inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
+                    enableLogging: options.enableLogging,
+                })).websocketUrl);
+        const WebSocketImpl = requireWebSocket(options.webSocket ?? this.client.webSocket);
+        const socket = new WebSocketImpl(websocketUrl);
+        return RealtimeTextToSpeechConnection.open(socket, {
+            timeout: options.timeout ?? this.client.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS,
+        });
+    }
+}
+function hasRealtimeSessionParams(options) {
+    return (options.modelId !== undefined ||
+        options.languageCode !== undefined ||
+        options.instructions !== undefined ||
+        options.voiceSettings !== undefined ||
+        options.inactivityTimeoutSeconds !== undefined ||
+        options.enableLogging !== undefined);
+}
+export class RealtimeTextToSpeechConnection {
+    socket;
+    queue = [];
+    waiters = [];
+    closed = false;
+    queuedBytes = 0;
+    failure;
+    constructor(socket) {
+        this.socket = socket;
+    }
+    static async open(socket, options = {}) {
+        const connection = new RealtimeTextToSpeechConnection(socket);
+        const timeoutMs = options.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            const succeed = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                resolve();
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                try {
+                    socket.close(1000);
+                }
+                catch {
+                    // The socket may already be closed; opening failed either way.
+                }
+                reject(error);
+            };
+            if (timeoutMs > 0) {
+                timer = setTimeout(() => fail(new Error(`Realtime TTS WebSocket did not open within ${timeoutMs}ms.`)), timeoutMs);
+            }
+            socket.binaryType = "arraybuffer";
+            socket.onopen = () => succeed();
+            socket.onerror = (event) => fail(new Error(`Realtime TTS WebSocket failed to open: ${String(event.type)}`));
+            socket.onclose = (event) => fail(new Error(`Realtime TTS WebSocket closed before opening: ${event.code} ${event.reason}`.trim()));
+        });
+        socket.onmessage = (event) => connection.handleMessage(event.data);
+        socket.onclose = (event) => connection.handleClose(event);
+        socket.onerror = () => connection.finish();
+        return connection;
+    }
+    startTurn(turnId) {
+        this.sendJson({ type: "turn.start", ...(turnId ? { turn_id: turnId } : {}) });
+    }
+    appendText(text) {
+        this.sendJson({ type: "text.append", text });
+    }
+    flush() {
+        this.sendJson({ type: "text.flush" });
+    }
+    endTurn() {
+        this.sendJson({ type: "turn.end" });
+    }
+    cancelTurn() {
+        this.sendJson({ type: "turn.cancel" });
+    }
+    /** Send a keepalive ping. The server answers with a `pong` event. */
+    ping() {
+        this.sendJson({ type: "ping" });
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        if (this.socket.readyState === WEBSOCKET_OPEN) {
+            this.sendJson({ type: "session.close" });
+        }
+        this.socket.close(1000);
+        this.finish();
+    }
+    async *events() {
+        for await (const message of this) {
+            if (message.type !== "audio") {
+                yield message;
+            }
+        }
+    }
+    async *audio() {
+        for await (const message of this) {
+            if (message.type === "audio") {
+                yield message.audio;
+            }
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const entry = this.queue.shift();
+                if (entry) {
+                    this.queuedBytes -= entry.size;
+                    return Promise.resolve({ value: entry.message, done: false });
+                }
+                if (this.failure) {
+                    return Promise.reject(this.failure);
+                }
+                if (this.closed) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+            },
+        };
+    }
+    sendJson(payload) {
+        this.socket.send(JSON.stringify(payload));
+    }
+    handleMessage(data) {
+        if (typeof data === "string") {
+            let parsed;
+            try {
+                parsed = JSON.parse(data);
+            }
+            catch (cause) {
+                this.fail(new BreezeBlueRealtimeError("Realtime TTS returned an invalid JSON event.", { cause }));
+                return;
+            }
+            this.push(camelizeKeys(parsed), data.length);
+            return;
+        }
+        if (data instanceof ArrayBuffer) {
+            this.push({ type: "audio", audio: new Uint8Array(data) }, data.byteLength);
+            return;
+        }
+        if (ArrayBuffer.isView(data)) {
+            this.push({ type: "audio", audio: new Uint8Array(data.buffer, data.byteOffset, data.byteLength) }, data.byteLength);
+        }
+    }
+    handleClose(event) {
+        if (!this.closed && event.code !== 1000) {
+            this.push({
+                type: "session.closed",
+                code: event.code,
+                reason: event.reason,
+                reconnect: event.code === 1012,
+            }, 0);
+        }
+        this.finish();
+    }
+    push(message, size) {
+        if (this.closed) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value: message, done: false });
+            return;
+        }
+        this.queue.push({ message, size });
+        this.queuedBytes += size;
+        if (this.queuedBytes > REALTIME_MAX_BUFFERED_BYTES) {
+            this.fail(new BreezeBlueRealtimeError(`Realtime TTS connection buffered more than ${REALTIME_MAX_BUFFERED_BYTES} bytes without being ` +
+                "consumed, so the connection was closed. Iterate the connection (or its audio()/events() " +
+                "helpers) while the session is active."));
+        }
+    }
+    fail(error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.failure = error;
+        this.queue.length = 0;
+        this.queuedBytes = 0;
+        this.socket.close(1000);
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.reject(error);
+        }
+    }
+    finish() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve({ value: undefined, done: true });
+        }
+    }
+}
 class GenerationJobsResource {
     client;
     constructor(client) {
@@ -175,6 +413,8 @@ class VoicesResource {
             voiceName: request.voiceName,
             voiceDescription: request.voiceDescription,
             labels: request.labels,
+            primaryCategoryCode: request.primaryCategoryCode,
+            visibility: request.visibility,
             playedNotSelectedVoiceIds: request.playedNotSelectedVoiceIds,
         }, options);
     }
@@ -218,6 +458,17 @@ class AccountResource {
         return this.client.requestJson("GET", "/v1/usage", params, undefined, options);
     }
 }
+function readGlobalWebSocket() {
+    return globalThis.WebSocket;
+}
+function requireWebSocket(WebSocketImpl) {
+    if (!WebSocketImpl) {
+        throw new BreezeBlueConfigurationError("Missing WebSocket implementation. Realtime text-to-speech needs a global WebSocket " +
+            "(available in browsers, edge runtimes, and Node 22+) or a webSocket constructor passed to " +
+            "BreezeBlueClient (for example from the 'ws' package on Node 20).");
+    }
+    return WebSocketImpl;
+}
 function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }
@@ -292,9 +543,11 @@ function clonePreviewForm(request) {
 }
 function voiceEditForm(request) {
     const form = new FormData();
-    form.set("name", request.name);
+    appendOptional(form, "name", request.name);
     appendOptional(form, "description", request.description);
     appendOptional(form, "labels", request.labels ? JSON.stringify(request.labels) : undefined);
+    appendOptional(form, "primary_category_code", request.primaryCategoryCode);
+    appendOptional(form, "visibility", request.visibility);
     for (const file of normalizeFiles(request.file, request.files, { required: false })) {
         appendFile(form, "files", file);
     }

package/dist/errors.d.ts

@@ -10,6 +10,32 @@ export declare class BreezeBlueError extends Error {
 }
 export declare class BreezeBlueConfigurationError extends BreezeBlueError {
 }
+/**
+ * A realtime text-to-speech connection failure: the SDK failed the
+ * connection (invalid server frame, unconsumed-buffer overflow, ...) and the
+ * message iterator rejects with this error.
+ *
+ * `recoverable` mirrors the Python SDK's `RealtimeError.recoverable`: it is
+ * `true` only when the failure cancelled just the active turn and the
+ * connection stays usable. SDK-detected connection failures are never
+ * recoverable. `reconnect` tells you whether opening a new session is
+ * expected to succeed.
+ */
+export declare class BreezeBlueRealtimeError extends BreezeBlueError {
+    readonly code: string | undefined;
+    readonly meta: Record<string, unknown> | null;
+    readonly closeCode: number | undefined;
+    readonly reconnect: boolean;
+    readonly recoverable: boolean;
+    constructor(message: string, params?: {
+        code?: string;
+        meta?: Record<string, unknown> | null;
+        closeCode?: number;
+        reconnect?: boolean;
+        recoverable?: boolean;
+        cause?: unknown;
+    });
+}
 export declare class BreezeBlueAPIError extends BreezeBlueError {
     readonly status: number;
     readonly code: string;

package/dist/errors.js

@@ -6,6 +6,32 @@ export class BreezeBlueError extends Error {
 }
 export class BreezeBlueConfigurationError extends BreezeBlueError {
 }
+/**
+ * A realtime text-to-speech connection failure: the SDK failed the
+ * connection (invalid server frame, unconsumed-buffer overflow, ...) and the
+ * message iterator rejects with this error.
+ *
+ * `recoverable` mirrors the Python SDK's `RealtimeError.recoverable`: it is
+ * `true` only when the failure cancelled just the active turn and the
+ * connection stays usable. SDK-detected connection failures are never
+ * recoverable. `reconnect` tells you whether opening a new session is
+ * expected to succeed.
+ */
+export class BreezeBlueRealtimeError extends BreezeBlueError {
+    code;
+    meta;
+    closeCode;
+    reconnect;
+    recoverable;
+    constructor(message, params = {}) {
+        super(message, params.cause === undefined ? undefined : { cause: params.cause });
+        this.code = params.code;
+        this.meta = params.meta ?? null;
+        this.closeCode = params.closeCode;
+        this.reconnect = params.reconnect ?? false;
+        this.recoverable = params.recoverable ?? false;
+    }
+}
 export class BreezeBlueAPIError extends BreezeBlueError {
     status;
     code;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AudioResponse } from "./audio.js";
-export { BreezeBlueAPIError, BreezeBlueAuthenticationError, BreezeBlueBadRequestError, BreezeBlueConfigurationError, BreezeBlueConflictError, BreezeBlueError, BreezeBlueForbiddenError, BreezeBlueGenerationNotReadyError, BreezeBlueInsufficientCreditsError, BreezeBlueNotFoundError, BreezeBlueRateLimitError, BreezeBlueServiceUnavailableError, BreezeBlueUpstreamError, BreezeBlueValidationError, } from "./errors.js";
-export { BreezeBlueClient } from "./client.js";
+export { BreezeBlueAPIError, BreezeBlueAuthenticationError, BreezeBlueBadRequestError, BreezeBlueConfigurationError, BreezeBlueConflictError, BreezeBlueError, BreezeBlueForbiddenError, BreezeBlueGenerationNotReadyError, BreezeBlueInsufficientCreditsError, BreezeBlueNotFoundError, BreezeBlueRateLimitError, BreezeBlueRealtimeError, BreezeBlueServiceUnavailableError, BreezeBlueUpstreamError, BreezeBlueValidationError, } from "./errors.js";
+export { BreezeBlueClient, RealtimeTextToSpeechConnection } from "./client.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { AudioResponse } from "./audio.js";
-export { BreezeBlueAPIError, BreezeBlueAuthenticationError, BreezeBlueBadRequestError, BreezeBlueConfigurationError, BreezeBlueConflictError, BreezeBlueError, BreezeBlueForbiddenError, BreezeBlueGenerationNotReadyError, BreezeBlueInsufficientCreditsError, BreezeBlueNotFoundError, BreezeBlueRateLimitError, BreezeBlueServiceUnavailableError, BreezeBlueUpstreamError, BreezeBlueValidationError, } from "./errors.js";
-export { BreezeBlueClient } from "./client.js";
+export { BreezeBlueAPIError, BreezeBlueAuthenticationError, BreezeBlueBadRequestError, BreezeBlueConfigurationError, BreezeBlueConflictError, BreezeBlueError, BreezeBlueForbiddenError, BreezeBlueGenerationNotReadyError, BreezeBlueInsufficientCreditsError, BreezeBlueNotFoundError, BreezeBlueRateLimitError, BreezeBlueRealtimeError, BreezeBlueServiceUnavailableError, BreezeBlueUpstreamError, BreezeBlueValidationError, } from "./errors.js";
+export { BreezeBlueClient, RealtimeTextToSpeechConnection } from "./client.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";

package/dist/node.js

@@ -29,7 +29,11 @@ export async function play(audio, options = {}) {
     await spawnAndPipeBytes(command.command, command.args, await audio.bytes());
 }
 export async function stream(audio, options = {}) {
-    const selected = selectStreamPlaybackCommand();
+    const selected = selectStreamPlaybackCommand({
+        contentType: audio.contentType,
+        sampleRate: numberHeader(audio, "x-breeze-sample-rate"),
+        channels: numberHeader(audio, "x-breeze-channels"),
+    });
     const command = options.command ?? selected.command;
     const args = options.args ?? selected.args;
     await spawnAndPipeReadable(command, args, audio.response.body);
@@ -57,6 +61,10 @@ async function spawnAndPipeReadable(command, args, body) {
     Readable.fromWeb(body).pipe(child.stdin);
     await waitForChild(child);
 }
+function numberHeader(audio, header) {
+    const value = Number.parseInt(audio.headers.get(header) ?? "", 10);
+    return Number.isFinite(value) && value > 0 ? value : null;
+}
 async function spawnAndWait(command, args) {
     await waitForChild(spawn(command, args, { stdio: "inherit" }));
 }

package/dist/types.d.ts

@@ -1,11 +1,16 @@
 export type JsonObject = Record<string, unknown>;
 export type BreezeBlueFetch = typeof fetch;
 export interface BreezeBlueClientOptions {
+    /**
+     * API key for REST calls. Optional: browser and edge callers that only use
+     * `textToSpeech.realtime.connect` with a `clientSecret` do not need one.
+     */
     apiKey?: string;
     baseUrl?: string;
     fetch?: BreezeBlueFetch;
     headers?: HeadersInit;
     timeout?: number;
+    webSocket?: BreezeBlueWebSocketConstructor;
 }
 export interface RequestOptions {
     headers?: HeadersInit;
@@ -19,6 +24,129 @@ export interface StreamTextToSpeechOptions extends AudioRequestOptions {
     optimizeStreamingLatency?: number;
     enableLogging?: boolean;
 }
+export type BreezeBlueWebSocketConstructor = new (url: string, protocols?: string | string[]) => BreezeBlueWebSocket;
+export interface BreezeBlueWebSocket {
+    binaryType: string;
+    readyState: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+}
+export interface RealtimeTextToSpeechSessionRequest {
+    modelId?: string;
+    languageCode?: string;
+    instructions?: string;
+    voiceSettings?: {
+        guidanceScale?: number | null;
+    };
+    inactivityTimeoutSeconds?: number;
+    enableLogging?: boolean;
+}
+export interface RealtimeTextToSpeechAudioFormat {
+    codec: "pcm_s16le" | string;
+    sampleRate: number;
+    channels: number;
+    sampleWidthBits: number;
+}
+export interface RealtimeTextToSpeechSession {
+    clientSecret: string;
+    websocketUrl: string;
+    expiresAt: string;
+    audioFormat: RealtimeTextToSpeechAudioFormat;
+}
+export interface RealtimeTextToSpeechConnectOptions extends RealtimeTextToSpeechSessionRequest {
+    clientSecret?: string;
+    websocketUrl?: string;
+    webSocket?: BreezeBlueWebSocketConstructor;
+    /** Handshake timeout in milliseconds. Defaults to the client `timeout`. */
+    timeout?: number;
+}
+export interface RealtimeTextToSpeechSessionReadyEvent {
+    type: "session.ready";
+    sessionId: string;
+    audioFormat: RealtimeTextToSpeechAudioFormat;
+    maxAppendBytes: number;
+    maxTurnCharacters: number;
+    inactivityTimeoutSeconds: number;
+    maxSessionSeconds: number;
+}
+export interface RealtimeTextToSpeechPongEvent {
+    type: "pong";
+}
+export interface RealtimeTextToSpeechTurnStartedEvent {
+    type: "turn.started";
+    turnId: string;
+    historyItemId: string;
+}
+export interface RealtimeTextToSpeechAudioStartedEvent {
+    type: "audio.started";
+    turnId: string;
+    ttfaMs: number;
+    audioFormat: RealtimeTextToSpeechAudioFormat;
+}
+export interface RealtimeTextToSpeechTurnSummary {
+    turnId: string;
+    historyItemId: string;
+    status: string;
+    textCharacters: number;
+    audioBytes: number;
+    durationMs: number | null;
+    ttfaMs: number | null;
+}
+export interface RealtimeTextToSpeechTurnDoneEvent extends RealtimeTextToSpeechTurnSummary {
+    type: "turn.done";
+}
+export interface RealtimeTextToSpeechTurnCancelledEvent extends RealtimeTextToSpeechTurnSummary {
+    type: "turn.cancelled";
+}
+export interface RealtimeTextToSpeechUsageCommittedEvent {
+    type: "usage.committed";
+    turnId: string;
+    historyItemId: string;
+    textCharacters: number;
+    outputFormat: string;
+    ttfaMs: number | null;
+}
+/**
+ * Sent by the server after a clean `session.close` (with `sessionId`), or
+ * synthesized by the SDK when the WebSocket closes abnormally (with `code`,
+ * `reason`, and `reconnect`).
+ */
+export interface RealtimeTextToSpeechSessionClosedEvent {
+    type: "session.closed";
+    sessionId?: string;
+    code?: number;
+    reason?: string;
+    reconnect?: boolean;
+}
+export interface RealtimeTextToSpeechErrorEvent {
+    type: "error";
+    code: string;
+    message: string;
+    meta?: {
+        reconnect?: boolean;
+        reason?: string;
+        turnId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Server events currently sent on a realtime text-to-speech connection.
+ *
+ * Treat this union as non-exhaustive: the server may add new event types,
+ * and the SDK passes unknown JSON events through to the iterator unchanged
+ * (with camelCase keys). Do not rely on an exhaustive `switch` over `type`;
+ * ignore event types you do not recognize.
+ */
+export type RealtimeTextToSpeechEvent = RealtimeTextToSpeechSessionReadyEvent | RealtimeTextToSpeechPongEvent | RealtimeTextToSpeechTurnStartedEvent | RealtimeTextToSpeechAudioStartedEvent | RealtimeTextToSpeechTurnDoneEvent | RealtimeTextToSpeechTurnCancelledEvent | RealtimeTextToSpeechUsageCommittedEvent | RealtimeTextToSpeechSessionClosedEvent | RealtimeTextToSpeechErrorEvent;
+export interface RealtimeTextToSpeechAudioMessage {
+    type: "audio";
+    audio: Uint8Array;
+}
+export type RealtimeTextToSpeechMessage = RealtimeTextToSpeechEvent | RealtimeTextToSpeechAudioMessage;
 export interface VoiceSettings {
     stability?: number;
     similarityBoost?: number;
@@ -71,7 +199,7 @@ export interface GenerationJob {
     source: string;
     voiceId?: string | null;
     voiceName?: string | null;
-    voiceCategory?: string | null;
+    origin?: string | null;
     modelId?: string | null;
     text?: string | null;
     contentType?: string | null;
@@ -100,15 +228,27 @@ export interface Model {
 export interface Voice {
     voiceId: string;
     name: string;
-    category: string;
+    origin: string;
     voiceType: string;
     labels: Record<string, string>;
     previewUrl?: string | null;
     settings: Required<VoiceSettings>;
     description?: string | null;
     createdAtUnix?: number | null;
+    primaryCategoryCode?: string | null;
+    visibility?: string | null;
     [key: string]: unknown;
 }
+export interface SavedVoice {
+    voiceId: string;
+    name: string;
+    origin: string;
+    previewUrl?: string | null;
+    description?: string | null;
+    createdAtUnix?: number | null;
+    primaryCategoryCode?: string | null;
+    visibility?: string | null;
+}
 export interface VoiceList {
     voices: Voice[];
     hasMore: boolean;
@@ -119,7 +259,7 @@ export interface VoiceList {
 }
 export interface VoiceSearchParams {
     search?: string;
-    category?: "premade" | "generated" | "cloned" | string;
+    origin?: "designed" | "cloned" | string;
     voiceType?: "all" | "default" | "personal" | string;
     sort?: "created_at_unix" | "name" | string;
     sortDirection?: "asc" | "desc";
@@ -151,9 +291,11 @@ export interface VoiceClonePreview {
     requiresVerification: boolean;
 }
 export interface VoiceEditRequest {
-    name: string;
+    name?: string;
     description?: string;
     labels?: Record<string, string>;
+    primaryCategoryCode?: string;
+    visibility?: "private" | "public" | string;
     file?: UploadData | UploadFile;
     files?: Array<UploadData | UploadFile>;
 }
@@ -184,13 +326,15 @@ export interface SaveVoiceRequest {
     voiceName: string;
     voiceDescription?: string | null;
     labels?: Record<string, string>;
+    primaryCategoryCode?: string;
+    visibility?: "private" | "public" | string;
     playedNotSelectedVoiceIds?: string[];
 }
 export interface HistoryItem {
     historyItemId: string;
     voiceId?: string | null;
     voiceName?: string | null;
-    voiceCategory?: string | null;
+    origin?: string | null;
     modelId?: string | null;
     text?: string | null;
     source: string;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.4.1";
+export declare const SDK_VERSION = "0.5.0";
 export declare const SDK_NAME = "@breeze.blue/sdk";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.4.1";
+export const SDK_VERSION = "0.5.0";
 export const SDK_NAME = "@breeze.blue/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breeze.blue/sdk",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breeze.blue>",