@breeze.blue/sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.19.0
+
+- Create Voice Remix candidates from custom descriptions or curated presets, with automatic input preparation and Expressive (4) as the default strength.
+- List Remix presets, reuse a prepared performance across candidates, and read source metadata and original-audio comparisons.
+- Retry Remix submissions with an idempotency key and save candidates using their source voice's name and description by default.
+
 ## 0.18.0
 
 - Create asynchronous speech jobs with word timestamps and read timing from completed job results.

package/README.md

@@ -488,6 +488,45 @@ while (localized.status !== "ready") {
 generatedVoiceId = localized.generatedVoiceId!;
 ```
 
+Voice Remix creates a same-language candidate from an owned or official voice
+and a custom description or preset. Each successful candidate uses the Voice Design candidate
+price. The source remains unchanged.
+
+```ts
+const remixJob = await client.voices.createRemixPreview({
+  voiceId: firstVoiceId,
+  prompt: "Make the voice warmer and more expressive.",
+  guidanceScale: 4,
+});
+let remix = await client.voices.getRemixPreview(remixJob.generationJobId);
+while (remix.status !== "ready") {
+  if (remix.status === "failed" || remix.status === "cancelled") {
+    throw new Error(remix.error?.detail ?? remix.status);
+  }
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+  remix = await client.voices.getRemixPreview(remixJob.generationJobId);
+}
+generatedVoiceId = remix.generatedVoiceId!;
+```
+
+Use `streamPreview` and `savePreview` with the generated ID to audition and save
+a private, independent voice. A client timeout leaves the server job running.
+
+Custom input is enhanced into an instruction and matching script in the source
+language. List templates with `client.voices.listRemixPresets()` and pass
+`presetId` instead of `prompt` to use one. Edited templates are enhanced;
+unchanged templates are translated only when the source language differs.
+
+To compare strengths, call `client.voices.prepareRemixPreview(...)` first and
+pass its `preparationToken` to each create call with the same input. The token
+lasts 24 hours. Values 2 / 4 / 6 / 8 mean Stable / Expressive / Creative / Intense;
+4 is the default. Web Auto compares separate candidates at 4, 6, and 8.
+Use `options.headers["Idempotency-Key"]` to retry uncertain submissions safely,
+with a distinct key per candidate. Status includes `comparisonAudioUrl`,
+`comparisonText`, and `sourceVoice`. Saving without `voiceName` or
+`voiceDescription` uses the source values.
+See the [Voice Remix guide](https://docs.breezeblue.ai/guides/voice-remix).
+
 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:
@@ -612,3 +651,5 @@ Stream audio and word/token timestamps with `client.textToSpeech.streamWithTimes
 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).
 
 For background generation with timing, use `client.textToSpeech.createJobWithTimestamps(...)`. Poll with `client.generationJobs.get(jobId)`; a ready job includes `wordTimestamps` and the audio download URL.
+
+Clone preview creation accepts an omitted name. The server uses the filename stem or `Cloned Voice`; saving a Clone preview without a name keeps its preview name. Other preview types still require a save name. Explicit names longer than 80 Unicode characters are rejected.

package/dist/client.d.ts

@@ -1,6 +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, VoiceLocalizeJob, VoiceLocalizePreviewRequest, VoiceLocalizePreviewStatus, 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, VoiceRemixPreviewRequest, VoiceRemixPrepareRequest, VoiceRemixPresets, VoiceRemixPreparation, VoiceRemixJob, VoiceRemixPreviewStatus, VoiceMetadataOptions, VoiceRandomParams, VoiceSearchParams, VoiceSettings } from "./types.js";
 export declare class BreezeBlueClient {
     readonly apiKey: string | undefined;
     readonly baseUrl: string;
@@ -252,6 +252,14 @@ declare class VoicesResource {
      * A clean end means `generatedVoiceId` is ready for {@link savePreview}.
      */
     streamDesignPreview(request: VoiceDesignStreamRequest, options?: RequestOptions): Promise<AudioResponse>;
+    /** List curated voice changes and their sample recordings. */
+    listRemixPresets(options?: RequestOptions): Promise<VoiceRemixPresets>;
+    /** Prepare once without generating audio; reuse the token for 24 hours with the same input. */
+    prepareRemixPreview(request: VoiceRemixPrepareRequest, options?: RequestOptions): Promise<VoiceRemixPreparation>;
+    /** Create one candidate. Custom input is enhanced automatically; guidance defaults to 4. */
+    createRemixPreview(request: VoiceRemixPreviewRequest, options?: RequestOptions): Promise<VoiceRemixJob>;
+    /** A polling timeout does not cancel the server task. Keep the job ID to resume polling. */
+    getRemixPreview(generationJobId: string, options?: RequestOptions): Promise<VoiceRemixPreviewStatus>;
     /**
      * Start a preview that speaks an existing voice in another language.
      * Localization runs as a background job: poll the returned
@@ -266,9 +274,9 @@ declare class VoicesResource {
      * 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. */
+    /** Download a ready Design, Clone, Remix or Localize preview. */
     streamPreview(generatedVoiceId: string, options?: AudioRequestOptions): Promise<AudioResponse>;
-    /** Persist a clone or design preview as a real voice asset. */
+    /** Save a ready preview; Remix defaults name and description to its source. */
     savePreview(request: SaveVoiceRequest, options?: RequestOptions): Promise<SavedVoice>;
 }
 declare class HistoryResource {

package/dist/client.js

@@ -1580,6 +1580,22 @@ class VoicesResource {
     streamDesignPreview(request, options) {
         return this.client.requestAudio("POST", "/v1/voice-previews/design/stream", undefined, request, options);
     }
+    /** List curated voice changes and their sample recordings. */
+    listRemixPresets(options) {
+        return this.client.requestJson("GET", "/v1/voice-previews/remix/presets", undefined, undefined, options);
+    }
+    /** Prepare once without generating audio; reuse the token for 24 hours with the same input. */
+    prepareRemixPreview(request, options) {
+        return this.client.requestJson("POST", "/v1/voice-previews/remix/prepare", undefined, request, options);
+    }
+    /** Create one candidate. Custom input is enhanced automatically; guidance defaults to 4. */
+    createRemixPreview(request, options) {
+        return this.client.requestJson("POST", "/v1/voice-previews/remix", undefined, request, options);
+    }
+    /** A polling timeout does not cancel the server task. Keep the job ID to resume polling. */
+    getRemixPreview(generationJobId, options) {
+        return this.client.requestJson("GET", `/v1/voice-previews/remix/${encodeURIComponent(generationJobId)}`, undefined, undefined, options);
+    }
     /**
      * Start a preview that speaks an existing voice in another language.
      * Localization runs as a background job: poll the returned
@@ -1598,11 +1614,11 @@ class VoicesResource {
     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. */
+    /** Download a ready Design, Clone, Remix or Localize preview. */
     streamPreview(generatedVoiceId, options = {}) {
         return this.client.requestAudio("GET", `/v1/voice-previews/${encodeURIComponent(generatedVoiceId)}/stream`, { outputFormat: options.outputFormat }, undefined, options);
     }
-    /** Persist a clone or design preview as a real voice asset. */
+    /** Save a ready preview; Remix defaults name and description to its source. */
     async savePreview(request, options) {
         const result = await this.client.requestJson("POST", `/v1/voice-previews/${encodeURIComponent(request.generatedVoiceId)}/save`, undefined, {
             voiceName: request.voiceName,
@@ -1754,6 +1770,9 @@ function mergeHeaders(headers, input) {
     new Headers(input).forEach((value, key) => headers.set(key, value));
 }
 function clonePreviewForm(request) {
+    if (request.name != null && typeof request.name !== "string") {
+        throw new BreezeBlueConfigurationError("Clone name must be a string or null.");
+    }
     if (request.removeBackgroundNoise) {
         throw new BreezeBlueConfigurationError("removeBackgroundNoise is not supported by the Breeze Developer API.");
     }
@@ -1763,7 +1782,7 @@ function clonePreviewForm(request) {
         }
     }
     const form = new FormData();
-    form.set("name", request.name);
+    appendOptional(form, "name", request.name ?? undefined);
     appendOptional(form, "description", request.description);
     for (const file of normalizeFiles(request.file, request.files, { required: true })) {
         appendFile(form, "files", file);

package/dist/types.d.ts

@@ -401,7 +401,7 @@ export interface UploadFile {
     contentType?: string;
 }
 export interface VoiceClonePreviewRequest {
-    name: string;
+    name?: string | null;
     file?: UploadData | UploadFile;
     files?: Array<UploadData | UploadFile>;
     description?: string;
@@ -454,6 +454,56 @@ export interface VoiceDesignResponse {
     previews: VoiceDesignPreview[];
     text: string;
 }
+export interface VoiceRemixPrepareRequest {
+    voiceId: string;
+    prompt?: string;
+    presetId?: string;
+}
+export interface VoiceRemixPreviewRequest extends VoiceRemixPrepareRequest {
+    guidanceScale?: number;
+    preparationToken?: string;
+}
+export interface VoiceRemixSource {
+    voiceId: string | null;
+    name: string | null;
+    description: string | null;
+}
+export interface VoiceRemixPreset {
+    id: string;
+    category: string;
+    name: string;
+    prompt: string;
+    script: string;
+    language: string;
+    guidanceScale: number;
+    previewAudioUrl: string;
+}
+export interface VoiceRemixPresets {
+    presets: VoiceRemixPreset[];
+    exampleVoiceId: string;
+}
+export interface VoiceRemixPreparation {
+    preparationToken: string;
+    languageCode: VoiceLanguageCode;
+    instruction: string;
+    text: string;
+    sourceVoice: VoiceRemixSource;
+}
+export interface VoiceRemixJob {
+    generationJobId: string;
+    status: string;
+}
+export interface VoiceRemixPreviewStatus extends VoiceRemixJob {
+    languageCode?: VoiceLanguageCode | null;
+    generatedVoiceId?: string | null;
+    text?: string | null;
+    error?: GenerationJobError | null;
+    instruction?: string | null;
+    guidanceScale?: number | null;
+    sourceVoice?: VoiceRemixSource | null;
+    comparisonAudioUrl?: string | null;
+    comparisonText?: string | null;
+}
 export interface VoiceLocalizePreviewRequest {
     voiceId: string;
     languageCode: VoiceLanguageCode;
@@ -473,7 +523,7 @@ export interface VoiceLocalizePreviewStatus {
 }
 export interface SaveVoiceRequest {
     generatedVoiceId: string;
-    voiceName: string;
+    voiceName?: string | null;
     voiceDescription?: string | null;
     tags?: string[];
     primaryCategoryCode?: string;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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