@breeze.blue/sdk 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.17.0
+
+- Generate synchronous speech or stream audio with word timestamps and safe stream cleanup.
+- Create and poll voice localization previews before auditioning and saving them.
+- Control TTS output volume alongside speaking speed.
+
+## 0.16.0
+
+- Clone previews use an automatically generated script in the reference audio language. Custom text, instructions, and language hints are not accepted.
+- Breaking: remove `text`, `instructions`, `languageCode`, and `previewLanguageCode` from `voices.createClonePreview(...)` calls. Use Text to Speech with a saved voice for custom scripts and performance instructions.
+
 ## 0.15.0
 
 - Added `previewLanguageCode` to Voice Clone previews independently of the reference audio language hint.

package/README.md

@@ -440,7 +440,7 @@ Daily Trend order. Search queries remain relevance-ranked; Trend is only a
 weak prior within the same relevance tier.
 
 Breeze voice creation is always two steps: produce a **preview**, let the
-user accept it, then **save the preview** as a real voice. Two ways to
+user accept it, then **save the preview** as a real voice. Three ways to
 produce a preview:
 
 ```ts
@@ -454,7 +454,6 @@ const clonePreview = await client.voices.createClonePreview({
     filename: "sample.wav",
     contentType: "audio/wav",
   },
-  text: "This is a short preview script.",
 });
 let generatedVoiceId = clonePreview.generatedVoiceId;
 
@@ -465,6 +464,29 @@ const design = await client.voices.createDesignPreview({
 generatedVoiceId = design.previews[0].generatedVoiceId;
 ```
 
+Option C keeps an existing voice and makes it speak another language.
+Localization runs as a background job: start it, then poll until the status is
+`ready`. `name` defaults to the source voice name.
+
+```ts
+const job = await client.voices.createLocalizePreview({
+  voiceId: firstVoiceId,
+  languageCode: "es",
+  name: "Documentary narrator (Spanish)",
+});
+
+let localized = await client.voices.getLocalizePreview(job.generationJobId);
+while (localized.status !== "ready") {
+  if (localized.status === "failed" || localized.status === "cancelled") {
+    throw new Error(localized.error?.detail ?? localized.status);
+  }
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+  localized = await client.voices.getLocalizePreview(job.generationJobId);
+}
+
+generatedVoiceId = localized.generatedVoiceId!;
+```
+
 For the fastest first audio, generate one design preview as a live 24 kHz mono
 PCM response. The Node `stream()` helper consumes the response body directly;
 a clean end means `generatedVoiceId` is ready to save:
@@ -574,8 +596,16 @@ try {
 
 Each API error exposes `status`, `code`, `detail`, `meta`, and `headers`.
 
-Clone previews identify the reference audio language and preview text language independently. Use `previewLanguageCode` for an explicit target hint when the text is ambiguous. Reference language hints do not override audio recognition; save cross-language previews with the original reference language.
+Clone previews automatically generate a short script in the detected reference audio language. They accept a reference sample, name, and optional description. Save the preview as a voice, then use Text to Speech for custom scripts, instructions, or target languages.
 
 ### HTTP TTS speed
 
 Pass `voiceSettings: { speed: 1.25 }` to control speech speed without changing pitch, from 0.5 to 2.0. Omission always means 1.0; saved voice speed is not inherited. Sync, async and HTTP streaming support this parameter; Realtime does not.
+
+Pass `voiceSettings: { volume: 1.5 }` to apply a request-level linear amplitude multiplier. Values range from 0.01 to 2.0; omission means 1.0. Values above 1.0 may clip peaks. Sync, async and HTTP streaming support this parameter; it does not change saved voice settings or apply to Realtime.
+
+## Word timing
+
+Stream audio and word/token timestamps with `client.textToSpeech.streamWithTimestamps(...)`. Use `for await` to consume chunks containing `audioBase64` and `wordTimestamps`; breaking iteration closes the stream. Decode the audio separately and merge repeated word indices. See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) for complete examples and timing semantics.
+
+For a complete response, use `client.textToSpeech.convertWithTimestamps(...)`. It returns base64 audio, its content type, and the full word/token timestamp list. Decode the audio before saving or playback. See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) and [Convert with timestamps](https://docs.breezeblue.ai/api-reference/text-to-speech/convert-with-timestamps).

package/dist/client.d.ts

@@ -1,5 +1,6 @@
+import { SpeechTimingStream, type SpeechWithTimestamps } from "./timestamps.js";
 import { AudioResponse } from "./audio.js";
-import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, CurrentApiKeyResponse, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, RealtimeTextToSpeechConnectOptions, RealtimeTextToSpeechEvent, RealtimeTextToSpeechManagedConnectOptions, RealtimeTextToSpeechMessage, RealtimeTextToSpeechSession, RealtimeTextToSpeechSessionRequest, SavedVoice, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsEnhanceRequest, TtsEnhanceResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceDesignStreamRequest, VoiceEditRequest, VoiceList, VoiceMetadataOptions, VoiceRandomParams, VoiceSearchParams, VoiceSettings } from "./types.js";
+import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, CurrentApiKeyResponse, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, RealtimeTextToSpeechConnectOptions, RealtimeTextToSpeechEvent, RealtimeTextToSpeechManagedConnectOptions, RealtimeTextToSpeechMessage, RealtimeTextToSpeechSession, RealtimeTextToSpeechSessionRequest, SavedVoice, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsEnhanceRequest, TtsEnhanceResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceDesignStreamRequest, VoiceEditRequest, VoiceList, VoiceLocalizeJob, VoiceLocalizePreviewRequest, VoiceLocalizePreviewStatus, VoiceMetadataOptions, VoiceRandomParams, VoiceSearchParams, VoiceSettings } from "./types.js";
 export declare class BreezeBlueClient {
     readonly apiKey: string | undefined;
     readonly baseUrl: string;
@@ -26,6 +27,10 @@ declare class TextToSpeechResource {
     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>;
+    convertWithTimestamps(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<SpeechWithTimestamps>;
+    streamWithTimestamps(voiceId: string, request: TextToSpeechRequest & {
+        timestampMode?: "chunk" | "lookahead";
+    }, options?: StreamTextToSpeechOptions): Promise<SpeechTimingStream>;
     enhance(request: TtsEnhanceRequest, options?: RequestOptions): Promise<TtsEnhanceResponse>;
 }
 declare class RealtimeTextToSpeechResource {
@@ -197,8 +202,9 @@ declare class GenerationJobsResource {
  * Voice CRUD plus the two-step preview → save flow for Breeze voices.
  *
  * Breeze's voice creation is always two steps: produce a preview
- * (`createClonePreview` from an audio sample, or `createDesignPreview` from
- * a text description), then persist it with `savePreview`. Preview generation
+ * (`createClonePreview` from an audio sample, `createDesignPreview` from a
+ * text description, or `createLocalizePreview` from an existing voice plus a
+ * target language), then persist it with `savePreview`. Preview generation
  * never creates a saved voice until `savePreview` is called.
  */
 declare class VoicesResource {
@@ -245,6 +251,20 @@ declare class VoicesResource {
      * A clean end means `generatedVoiceId` is ready for {@link savePreview}.
      */
     streamDesignPreview(request: VoiceDesignStreamRequest, options?: RequestOptions): Promise<AudioResponse>;
+    /**
+     * Start a preview that speaks an existing voice in another language.
+     * Localization runs as a background job: poll the returned
+     * `generationJobId` with {@link getLocalizePreview} until the status is
+     * `ready`, then audition it with {@link streamPreview} and persist it with
+     * {@link savePreview}. `name` defaults to the source voice name.
+     */
+    createLocalizePreview(request: VoiceLocalizePreviewRequest, options?: RequestOptions): Promise<VoiceLocalizeJob>;
+    /**
+     * Read the current state of a localization preview job. `generatedVoiceId`,
+     * `text`, and `languageCode` stay null until the status is `ready`; `error`
+     * is set only when the job ends in `failed`.
+     */
+    getLocalizePreview(generationJobId: string, options?: RequestOptions): Promise<VoiceLocalizePreviewStatus>;
     /** Download the completed audio of a clone or design preview. */
     streamPreview(generatedVoiceId: string, options?: AudioRequestOptions): Promise<AudioResponse>;
     /** Persist a clone or design preview as a real voice asset. */

package/dist/client.js

@@ -1,3 +1,4 @@
+import { SpeechTimingStream } from "./timestamps.js";
 import { AudioResponse } from "./audio.js";
 import { BreezeBlueAPIError, BreezeBlueConfigurationError, BreezeBlueRealtimeError, errorFromResponse, } from "./errors.js";
 import { camelizeKeys, snakeizeKeys } from "./_transform.js";
@@ -119,6 +120,13 @@ class TextToSpeechResource {
             enableLogging: options.enableLogging,
         }, request, options);
     }
+    convertWithTimestamps(voiceId, request, options = {}) {
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps`, { outputFormat: options.outputFormat }, request, options);
+    }
+    async streamWithTimestamps(voiceId, request, options = {}) {
+        const response = await this.client.request("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream/with-timestamps`, { outputFormat: options.outputFormat, optimizeStreamingLatency: options.optimizeStreamingLatency, enableLogging: options.enableLogging }, request, options);
+        return new SpeechTimingStream(response);
+    }
     enhance(request, options) {
         return this.client.requestJson("POST", "/v1/text-to-speech/enhance", undefined, request, options);
     }
@@ -1479,8 +1487,9 @@ class GenerationJobsResource {
  * Voice CRUD plus the two-step preview → save flow for Breeze voices.
  *
  * Breeze's voice creation is always two steps: produce a preview
- * (`createClonePreview` from an audio sample, or `createDesignPreview` from
- * a text description), then persist it with `savePreview`. Preview generation
+ * (`createClonePreview` from an audio sample, `createDesignPreview` from a
+ * text description, or `createLocalizePreview` from an existing voice plus a
+ * target language), then persist it with `savePreview`. Preview generation
  * never creates a saved voice until `savePreview` is called.
  */
 class VoicesResource {
@@ -1568,6 +1577,24 @@ class VoicesResource {
     streamDesignPreview(request, options) {
         return this.client.requestAudio("POST", "/v1/voice-previews/design/stream", undefined, request, options);
     }
+    /**
+     * Start a preview that speaks an existing voice in another language.
+     * Localization runs as a background job: poll the returned
+     * `generationJobId` with {@link getLocalizePreview} until the status is
+     * `ready`, then audition it with {@link streamPreview} and persist it with
+     * {@link savePreview}. `name` defaults to the source voice name.
+     */
+    createLocalizePreview(request, options) {
+        return this.client.requestJson("POST", "/v1/voice-previews/localize", undefined, request, options);
+    }
+    /**
+     * Read the current state of a localization preview job. `generatedVoiceId`,
+     * `text`, and `languageCode` stay null until the status is `ready`; `error`
+     * is set only when the job ends in `failed`.
+     */
+    getLocalizePreview(generationJobId, options) {
+        return this.client.requestJson("GET", `/v1/voice-previews/localize/${encodeURIComponent(generationJobId)}`, undefined, undefined, options);
+    }
     /** Download the completed audio of a clone or design preview. */
     streamPreview(generatedVoiceId, options = {}) {
         return this.client.requestAudio("GET", `/v1/voice-previews/${encodeURIComponent(generatedVoiceId)}/stream`, { outputFormat: options.outputFormat }, undefined, options);
@@ -1727,13 +1754,14 @@ function clonePreviewForm(request) {
     if (request.removeBackgroundNoise) {
         throw new BreezeBlueConfigurationError("removeBackgroundNoise is not supported by the Breeze Developer API.");
     }
+    for (const field of ["text", "instructions", "languageCode", "previewLanguageCode"]) {
+        if (field in request) {
+            throw new BreezeBlueConfigurationError(`Clone previews do not accept ${field}; the script and language are generated automatically.`);
+        }
+    }
     const form = new FormData();
     form.set("name", request.name);
     appendOptional(form, "description", request.description);
-    appendOptional(form, "language_code", request.languageCode);
-    appendOptional(form, "preview_language_code", request.previewLanguageCode);
-    appendOptional(form, "text", request.text);
-    appendOptional(form, "instructions", request.instructions);
     for (const file of normalizeFiles(request.file, request.files, { required: true })) {
         appendFile(form, "files", file);
     }

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export { BreezeBlueClient, ManagedRealtimeTextToSpeechConnection, RealtimeTextTo
 export { SDK_NAME, SDK_VERSION } from "./version.js";
 export type * from "./types.js";
 export * from "./voice-metadata.js";
+export { SpeechTimingStream } from "./timestamps.js";
+export type { SpeechTimingChunk, SpeechWithTimestamps, WordTimestamp } from "./timestamps.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export { BreezeBlueAPIError, BreezeBlueAuthenticationError, BreezeBlueBadRequest
 export { BreezeBlueClient, ManagedRealtimeTextToSpeechConnection, RealtimeTextToSpeechConnection, } from "./client.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";
 export * from "./voice-metadata.js";
+export { SpeechTimingStream } from "./timestamps.js";

package/dist/timestamps.d.ts

@@ -0,0 +1,22 @@
+export interface WordTimestamp {
+    index: number;
+    word: string;
+    start: number;
+    end: number;
+}
+export interface SpeechTimingChunk {
+    audioBase64: string;
+    wordTimestamps: WordTimestamp[];
+}
+export interface SpeechWithTimestamps extends SpeechTimingChunk {
+    contentType: string;
+}
+/** Single-use stream. Breaking iteration cancels the response body. */
+export declare class SpeechTimingStream implements AsyncIterable<SpeechTimingChunk> {
+    private readonly response;
+    readonly historyItemId: string | null;
+    private reader?;
+    constructor(response: Response);
+    close(): Promise<void>;
+    [Symbol.asyncIterator](): AsyncGenerator<SpeechTimingChunk>;
+}

package/dist/timestamps.js

@@ -0,0 +1,64 @@
+import { camelizeKeys } from "./_transform.js";
+/** Single-use stream. Breaking iteration cancels the response body. */
+export class SpeechTimingStream {
+    response;
+    historyItemId;
+    reader;
+    constructor(response) {
+        this.response = response;
+        this.historyItemId = response.headers.get("history-item-id");
+    }
+    async close() {
+        if (this.reader)
+            await this.reader.cancel();
+        else
+            await this.response.body?.cancel();
+    }
+    async *[Symbol.asyncIterator]() {
+        const reader = this.response.body?.getReader();
+        if (!reader)
+            throw new Error("Speech stream has no response body.");
+        this.reader = reader;
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        let pending = "";
+        const parse = (line) => {
+            if (line.length > 4 * 1024 * 1024)
+                throw new Error("Timestamp stream line is too large.");
+            const value = JSON.parse(line);
+            if (value.error)
+                throw new Error(`Speech stream failed: ${JSON.stringify(value.error)}`);
+            if (typeof value.audio_base64 !== "string" || !Array.isArray(value.word_timestamps))
+                throw new Error("Invalid timestamp stream event.");
+            return camelizeKeys(value);
+        };
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                pending += decoder.decode(value, { stream: !done });
+                let boundary = pending.indexOf("\n");
+                while (boundary >= 0) {
+                    const line = pending.slice(0, boundary);
+                    pending = pending.slice(boundary + 1);
+                    if (line.trim())
+                        yield parse(line);
+                    boundary = pending.indexOf("\n");
+                }
+                if (pending.length > 4 * 1024 * 1024)
+                    throw new Error("Timestamp stream line is too large.");
+                if (done)
+                    break;
+            }
+            if (pending.trim())
+                yield parse(pending);
+        }
+        finally {
+            try {
+                await reader.cancel();
+            }
+            finally {
+                reader.releaseLock();
+                this.reader = undefined;
+            }
+        }
+    }
+}

package/dist/types.d.ts

@@ -234,6 +234,11 @@ export interface VoiceSettings {
     speed?: number;
     guidanceScale?: number | null;
 }
+/** Request-only HTTP TTS settings. Volume is a linear amplitude multiplier. */
+export interface TtsVoiceSettings extends VoiceSettings {
+    /** Linear amplitude multiplier (0.01–2.0); omitted means 1.0. */
+    volume?: number;
+}
 export interface PronunciationDictionaryLocator {
     pronunciationDictionaryId: string;
     versionId: string;
@@ -243,7 +248,7 @@ export interface TextToSpeechRequest {
     modelId?: string;
     languageCode?: string;
     instructions?: string;
-    voiceSettings?: VoiceSettings;
+    voiceSettings?: TtsVoiceSettings;
     seed?: number;
     pronunciationDictionaryLocators?: PronunciationDictionaryLocator[];
     previousText?: string;
@@ -313,6 +318,9 @@ export interface Voice {
     createdAtUnix?: number | null;
     primaryCategoryCode?: string | null;
     visibility?: string | null;
+    publicationStatus?: string | null;
+    publicationJobId?: string | null;
+    publicationErrorCode?: string | null;
     languageCode: VoiceLanguageCode;
     gender: VoiceGender | null;
     age: VoiceAge | null;
@@ -379,6 +387,9 @@ export interface VoiceSearchParams {
 }
 export interface GenericStatus {
     status: string;
+    visibility?: string | null;
+    publicationStatus?: string | null;
+    publicationJobId?: string | null;
 }
 export type UploadData = Blob | ArrayBuffer | Uint8Array | string;
 export interface UploadFile {
@@ -392,12 +403,6 @@ export interface VoiceClonePreviewRequest {
     files?: Array<UploadData | UploadFile>;
     description?: string;
     removeBackgroundNoise?: boolean;
-    /** Reference language hint; audio recognition remains authoritative. */
-    languageCode?: VoiceLanguageCode;
-    /** Target hint used when preview text language is uncertain. */
-    previewLanguageCode?: VoiceLanguageCode;
-    text?: string;
-    instructions?: string;
 }
 export interface VoiceClonePreview {
     generatedVoiceId: string;
@@ -446,6 +451,23 @@ export interface VoiceDesignResponse {
     previews: VoiceDesignPreview[];
     text: string;
 }
+export interface VoiceLocalizePreviewRequest {
+    voiceId: string;
+    languageCode: VoiceLanguageCode;
+    name?: string;
+}
+export interface VoiceLocalizeJob {
+    generationJobId: string;
+    status: string;
+}
+export interface VoiceLocalizePreviewStatus {
+    generationJobId: string;
+    status: string;
+    languageCode?: VoiceLanguageCode | null;
+    generatedVoiceId?: string | null;
+    text?: string | null;
+    error?: GenerationJobError | null;
+}
 export interface SaveVoiceRequest {
     generatedVoiceId: string;
     voiceName: string;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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