@breeze.blue/sdk 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.22.0
+
+- Select PCM or MP3 for realtime TTS sessions and preserve the format across managed connections.
+- Export output-format choices shared with the public API while retaining historical conversion profiles.
+- Breaking: remove `visibility` and `primaryCategoryCode` from `voices.savePreview(...)` and `voices.edit(...)`, and remove reference-sample upload arguments from `voices.edit(...)`.
+- Keep official catalog assignment, publication and reference-sample replacement available through authorized low-level HTTP requests or the CLI. Category search and Clone uploads remain available.
+- Voice Clone accepts `referenceLanguageCode: "zh"` to use Qwen ASR for a Chinese reference sample. Omitting it keeps automatic language detection.
+- Check complete Voice and History request fields against public OpenAPI with a shared, operation-specific historical compatibility whitelist.
+
+## 0.21.1
+
+- Document Voice Design guidance: omitted or null samples 1–4 per preview; explicit values still accept 1–10.
+
+- Clarify speaker boost docs: instructions are always applied; boost is ignored with non-empty instructions and guidance above 1, otherwise guidance is applied as 1. Realtime needs a new session to add instructions only when boost applies with requested guidance above 1.
+
 ## 0.21.0
 
 - Support request-scoped speaker boost across HTTP and realtime TTS, with performance instructions taking priority when guidance exceeds 1.

package/README.md

@@ -7,7 +7,7 @@ models, and account usage.
 The root entrypoint is safe to import in Node, browser, and edge runtimes. Local
 audio playback helpers live in the Node-only `@breeze.blue/sdk/node` subpath.
 
-Guidance accepts 1–10; when omitted, the default 1 is used. HTTP speed and volume are per request and default to 1. Use `voiceSettings: { useSpeakerBoost: true }` for closer similarity to the reference voice (default false): it is ignored with non-empty instructions and guidance above 1, and otherwise instructions are not used. Realtime fixes boost at session creation; create a new session to change instructions while boost applies. Pass `removeBackgroundNoise: true` to denoise a clone sample (default false).
+TTS guidance accepts 1–10; when omitted, the default 1 is used. Voice Design accepts 1–10; omitting guidance or passing null samples uniformly between 1–4 for each preview, rounded to one decimal place. HTTP speed and volume are per request and default to 1. Use `voiceSettings: { useSpeakerBoost: true }` for closer similarity to the reference voice (default false): it is ignored with non-empty instructions and guidance above 1, otherwise guidance is applied as 1; instructions are always applied. Realtime fixes boost at session creation; when boost applies with requested guidance above 1, create a new session to add instructions. Pass `removeBackgroundNoise: true` to denoise a clone sample (default false).
 
 ## Install
 
@@ -107,8 +107,10 @@ 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.
+conversation turns. Realtime supports PCM (default) or MP3 at 24 kHz mono.
+PCM uses raw signed 16-bit little-endian samples. Pass `outputFormat: "mp3"` to
+`realtime.createSession`, `realtime.connect`, or `realtime.connectManaged` to select MP3.
+Each turn's final MP3 bytes arrive before `turn.done`.
 
 Realtime needs a `WebSocket` implementation. Browsers, edge runtimes, and
 Node 22+ provide a global one; on Node 20, pass a constructor (for example the
@@ -396,8 +398,7 @@ Streaming text-to-speech defaults to `pcm` to reduce time to first audio. Pass
 format explicitly.
 
 Sync and async text-to-speech also take a sample rate and, for the lossy encodings, a bitrate, such as
-`{ outputFormat: "wav_48000" }`. Breeze resamples its native 24000 Hz output for
-downstream compatibility; profiles carrying a sample rate are not available for streaming.
+`{ outputFormat: "wav_24000" }`. Profiles carrying a sample rate apply to sync and async conversion; streaming uses bare encoding names.
 
 ## Voices
 
@@ -564,7 +565,9 @@ const saved = await client.voices.savePreview({
 });
 ```
 
-Edit or delete a saved voice:
+Saved previews are private to your account. Editing a voice's metadata preserves its visibility.
+
+Edit a saved voice's name, description, tags, or Voice Metadata, or delete it:
 
 ```ts
 await client.voices.edit(saved.voiceId, {

package/dist/client.js

@@ -163,6 +163,7 @@ class RealtimeTextToSpeechResource {
             voiceSettings: request.voiceSettings == null ? request.voiceSettings : { guidanceScale: request.voiceSettings.guidanceScale, useSpeakerBoost: request.voiceSettings.useSpeakerBoost },
             inactivityTimeoutSeconds: request.inactivityTimeoutSeconds,
             enableLogging: request.enableLogging,
+            outputFormat: request.outputFormat,
         }, options);
     }
     async connect(voiceId, options = {}) {
@@ -170,7 +171,7 @@ class RealtimeTextToSpeechResource {
             options.websocketUrl !== undefined ||
             options.directWebsocketUrl !== undefined) && hasRealtimeSessionParams(options)) {
             console.warn("@breeze.blue/sdk: realtime.connect ignores modelId, languageCode, instructions, voiceSettings, " +
-                "inactivityTimeoutSeconds, and enableLogging when session credentials are provided. " +
+                "inactivityTimeoutSeconds, outputFormat, and enableLogging when session credentials are provided. " +
                 "Configure these initial values when creating the realtime session instead. " +
                 "To change instructions between turns, call connection.updateInstructions() and wait for session.updated.");
         }
@@ -185,6 +186,7 @@ class RealtimeTextToSpeechResource {
                 voiceSettings: options.voiceSettings,
                 inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
                 enableLogging: options.enableLogging,
+                outputFormat: options.outputFormat,
             }, {
                 signal: options.signal,
                 timeout: options.timeout,
@@ -226,7 +228,7 @@ class RealtimeTextToSpeechResource {
     async connectManaged(voiceId, options = {}) {
         if (options.sessionFactory !== undefined && hasRealtimeSessionParams(options)) {
             console.warn("@breeze.blue/sdk: realtime.connectManaged cannot apply modelId, languageCode, instructions, " +
-                "voiceSettings, inactivityTimeoutSeconds, or enableLogging when sessionFactory is provided. " +
+                "voiceSettings, inactivityTimeoutSeconds, outputFormat, or enableLogging when sessionFactory is provided. " +
                 "Configure these when the factory creates each realtime session. After connecting, confirmed " +
                 "updateInstructions() values are carried across managed physical sessions.");
         }
@@ -237,6 +239,7 @@ class RealtimeTextToSpeechResource {
             voiceSettings: options.voiceSettings,
             inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
             enableLogging: options.enableLogging,
+            outputFormat: options.outputFormat,
         };
         const connectionTimeout = options.timeout ?? this.client.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS;
         const createConnection = async (signal) => {
@@ -272,7 +275,8 @@ function hasRealtimeSessionParams(options) {
         options.instructions !== undefined ||
         options.voiceSettings !== undefined ||
         options.inactivityTimeoutSeconds !== undefined ||
-        options.enableLogging !== undefined);
+        options.enableLogging !== undefined ||
+        options.outputFormat !== undefined);
 }
 function realtimeClientSecretSubprotocols(clientSecret) {
     if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/.test(clientSecret)) {
@@ -1634,8 +1638,6 @@ class VoicesResource {
             voiceName: request.voiceName,
             voiceDescription: request.voiceDescription,
             tags: request.tags,
-            primaryCategoryCode: request.primaryCategoryCode,
-            visibility: request.visibility,
             languageCode: request.languageCode,
             gender: request.gender,
             age: request.age,
@@ -1789,6 +1791,7 @@ function clonePreviewForm(request) {
     const form = new FormData();
     appendOptional(form, "name", request.name ?? undefined);
     appendOptional(form, "description", request.description);
+    appendOptional(form, "reference_language_code", request.referenceLanguageCode);
     appendOptional(form, "remove_background_noise", request.removeBackgroundNoise ?? false);
     for (const file of normalizeFiles(request.file, request.files, { required: true })) {
         appendFile(form, "files", file);
@@ -1803,8 +1806,6 @@ function voiceEditForm(request) {
         for (const tag of request.tags)
             form.append("tags", tag);
     }
-    appendOptional(form, "primary_category_code", request.primaryCategoryCode);
-    appendOptional(form, "visibility", request.visibility);
     appendOptional(form, "language_code", request.languageCode);
     appendNullable(form, "gender", request.gender);
     appendNullable(form, "age", request.age);
@@ -1818,9 +1819,6 @@ function voiceEditForm(request) {
         }
     }
     appendNullable(form, "accent", request.accent);
-    for (const file of normalizeFiles(request.file, request.files, { required: false })) {
-        appendFile(form, "files", file);
-    }
     return form;
 }
 function stripHiddenVoiceFields(voice) {

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export { SpeechTimingStream } from "./timestamps.js";
 export type { SpeechTimingChunk, SpeechWithTimestamps, WordTimestamp } from "./timestamps.js";
 export * from "./studio.js";
 export type * from "./studio-types.js";
+export * from "./output-formats.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export { SDK_NAME, SDK_VERSION } from "./version.js";
 export * from "./voice-metadata.js";
 export { SpeechTimingStream } from "./timestamps.js";
 export * from "./studio.js";
+export * from "./output-formats.js";

package/dist/output-formats.d.ts

@@ -0,0 +1,10 @@
+export declare const AUDIO_ENCODINGS: readonly ["mp3", "wav", "flac", "pcm", "aac", "opus"];
+export declare const TTS_OUTPUT_FORMATS: readonly ["mp3", "wav", "flac", "pcm", "aac", "opus", "mp3_24000_64", "mp3_24000_96", "mp3_24000_128", "mp3_24000_160", "wav_24000", "pcm_24000", "flac_24000", "aac_24000_128"];
+export declare const STREAMING_OUTPUT_FORMATS: readonly ["pcm", "mp3", "wav"];
+export declare const REALTIME_OUTPUT_FORMATS: readonly ["pcm", "mp3"];
+export type TtsOutputFormat = typeof TTS_OUTPUT_FORMATS[number] | (string & {});
+export type StreamingOutputFormat = typeof STREAMING_OUTPUT_FORMATS[number];
+export type RealtimeOutputFormat = typeof REALTIME_OUTPUT_FORMATS[number];
+export declare const DEFAULT_TTS_OUTPUT_FORMAT = "mp3";
+export declare const DEFAULT_STREAM_OUTPUT_FORMAT = "pcm";
+export declare const DEFAULT_REALTIME_OUTPUT_FORMAT = "pcm";

package/dist/output-formats.js

@@ -0,0 +1,8 @@
+// Generated from generation_runtime.output_formats; do not edit by hand.
+export const AUDIO_ENCODINGS = ["mp3", "wav", "flac", "pcm", "aac", "opus"];
+export const TTS_OUTPUT_FORMATS = ["mp3", "wav", "flac", "pcm", "aac", "opus", "mp3_24000_64", "mp3_24000_96", "mp3_24000_128", "mp3_24000_160", "wav_24000", "pcm_24000", "flac_24000", "aac_24000_128"];
+export const STREAMING_OUTPUT_FORMATS = ["pcm", "mp3", "wav"];
+export const REALTIME_OUTPUT_FORMATS = ["pcm", "mp3"];
+export const DEFAULT_TTS_OUTPUT_FORMAT = "mp3";
+export const DEFAULT_STREAM_OUTPUT_FORMAT = "pcm";
+export const DEFAULT_REALTIME_OUTPUT_FORMAT = "pcm";

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { TtsOutputFormat, RealtimeOutputFormat } from "./output-formats.js";
 import type { WordTimestamp } from "./timestamps.js";
 import type { VoiceAccent, VoiceWritableAccent, VoiceAge, VoiceGender, VoiceLanguageCode, VoiceTone } from "./voice-metadata.js";
 export type JsonObject = Record<string, unknown>;
@@ -20,7 +21,7 @@ export interface RequestOptions {
     timeout?: number;
 }
 export interface AudioRequestOptions extends RequestOptions {
-    outputFormat?: string;
+    outputFormat?: TtsOutputFormat;
 }
 export interface StreamTextToSpeechOptions extends AudioRequestOptions {
     enableLogging?: boolean;
@@ -38,6 +39,7 @@ export interface BreezeBlueWebSocket {
     close(code?: number, reason?: string): void;
 }
 export interface RealtimeTextToSpeechSessionRequest {
+    outputFormat?: RealtimeOutputFormat;
     modelId?: string;
     languageCode?: string;
     instructions?: string;
@@ -49,7 +51,8 @@ export interface RealtimeTextToSpeechAudioFormat {
     codec: "pcm_s16le" | string;
     sampleRate: number;
     channels: number;
-    sampleWidthBits: number;
+    sampleWidthBits?: number | null;
+    bitrateKbps?: number;
 }
 export interface RealtimeTextToSpeechSession {
     clientSecret: string;
@@ -227,7 +230,7 @@ export type RealtimeTextToSpeechMessage = RealtimeTextToSpeechEvent | RealtimeTe
 export interface TtsVoiceSettings {
     /** Generation guidance strength (1–10). Omitted or null uses the default 1. */
     guidanceScale?: number | null;
-    /** Default false. Ignored with non-empty instructions and guidanceScale > 1; otherwise instructions are not used. */
+    /** Default false. Ignored with non-empty instructions and guidanceScale > 1; otherwise guidanceScale is applied as 1. Instructions are always applied. */
     useSpeakerBoost?: boolean;
     /** Pitch-preserving speed (0.5–2.0). */
     speed?: number;
@@ -386,6 +389,7 @@ export interface UploadFile {
     contentType?: string;
 }
 export interface VoiceClonePreviewRequest {
+    referenceLanguageCode?: "zh";
     name?: string | null;
     file?: UploadData | UploadFile;
     files?: Array<UploadData | UploadFile>;
@@ -400,21 +404,18 @@ export interface VoiceEditRequest {
     name?: string;
     description?: string;
     tags?: string[];
-    primaryCategoryCode?: string;
-    visibility?: "private" | "public" | string;
     languageCode?: VoiceLanguageCode;
     gender?: VoiceGender | null;
     age?: VoiceAge | null;
     tone?: VoiceTone[];
     accent?: VoiceWritableAccent | null;
-    file?: UploadData | UploadFile;
-    files?: Array<UploadData | UploadFile>;
 }
 export interface VoiceDesignRequest {
     voiceDescription: string;
     text?: string;
     modelId?: string;
     languageCode?: VoiceLanguageCode;
+    /** Voice Design accepts 1–10; omitted or null samples 1–4 per preview, rounded to one decimal place. */
     guidanceScale?: number | null;
     previewCount?: number;
 }
@@ -423,6 +424,7 @@ export interface VoiceDesignStreamRequest {
     text?: string;
     modelId?: string;
     languageCode?: VoiceLanguageCode;
+    /** Voice Design accepts 1–10; omitted or null samples 1–4 per preview, rounded to one decimal place. */
     guidanceScale?: number | null;
 }
 export interface VoiceDesignPreview {
@@ -507,8 +509,6 @@ export interface SaveVoiceRequest {
     voiceName?: string | null;
     voiceDescription?: string | null;
     tags?: string[];
-    primaryCategoryCode?: string;
-    visibility?: "private" | "public" | string;
     languageCode: VoiceLanguageCode;
     gender?: VoiceGender | null;
     age?: VoiceAge | null;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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