@breeze.blue/sdk 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+
 ## 0.17.0
 
 - Generate synchronous speech or stream audio with word timestamps and safe stream cleanup.

package/README.md

@@ -436,7 +436,8 @@ console.log(metadataOptions.accentCodesByLanguage.en);
 
 Voice listings keep the published default of stable creation-time order from
 newest to oldest. Use `{ sort: "trend", voiceType: "default" }` for the shared
-Daily Trend order. Search queries remain relevance-ranked; Trend is only a
+Daily Trend order. Eligible voices not yet ranked follow the snapshot members;
+returned page tokens pin the initial supplemental candidates. 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
@@ -487,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:
@@ -609,3 +649,7 @@ Pass `voiceSettings: { volume: 1.5 }` to apply a request-level linear amplitude
 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).
+
+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;
@@ -26,6 +26,7 @@ declare class TextToSpeechResource {
     constructor(client: BreezeBlueClient);
     convert(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<AudioResponse>;
     createJob(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<AsyncTextToSpeechJob>;
+    createJobWithTimestamps(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 & {
@@ -251,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
@@ -265,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

@@ -113,6 +113,9 @@ class TextToSpeechResource {
     createJob(voiceId, request, options = {}) {
         return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, { outputFormat: options.outputFormat, delivery: "async" }, request, options);
     }
+    createJobWithTimestamps(voiceId, request, options = {}) {
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps`, { outputFormat: options.outputFormat, delivery: "async" }, request, options);
+    }
     stream(voiceId, request, options = {}) {
         return this.client.requestAudio("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream`, {
             outputFormat: options.outputFormat,
@@ -1577,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
@@ -1595,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,
@@ -1751,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.");
     }
@@ -1760,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

@@ -1,4 +1,5 @@
-import type { VoiceAccent, VoiceAge, VoiceGender, VoiceLanguageCode, VoiceTone } from "./voice-metadata.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>;
 export type BreezeBlueFetch = typeof fetch;
 export interface BreezeBlueClientOptions {
@@ -276,6 +277,7 @@ export interface GenerationJobError {
     detail: string;
 }
 export interface GenerationJob {
+    wordTimestamps?: WordTimestamp[];
     generationJobId: string;
     historyItemId: string;
     status: string;
@@ -359,7 +361,7 @@ export interface VoiceMetadataOptions {
     ageCodes: VoiceAge[];
     toneCodes: VoiceTone[];
     toneMaxItems: number;
-    accentCodesByLanguage: Record<VoiceLanguageCode, VoiceAccent[]>;
+    accentCodesByLanguage: Record<VoiceLanguageCode, VoiceWritableAccent[]>;
 }
 export interface VoiceRandomParams {
     /** Only pick from voices whose saved audio language matches this code. */
@@ -375,6 +377,7 @@ export interface VoiceSearchParams {
     age?: VoiceAge[];
     tone?: VoiceTone[];
     accent?: VoiceAccent;
+    accentMode?: "all" | "unmarked";
     origin?: "designed" | "cloned" | string;
     voiceType?: "all" | "default" | "personal" | string;
     sort?: "created_at_unix" | "name" | "trend" | string;
@@ -398,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;
@@ -418,7 +421,7 @@ export interface VoiceEditRequest {
     gender?: VoiceGender | null;
     age?: VoiceAge | null;
     tone?: VoiceTone[];
-    accent?: VoiceAccent | null;
+    accent?: VoiceWritableAccent | null;
     file?: UploadData | UploadFile;
     files?: Array<UploadData | UploadFile>;
 }
@@ -451,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;
@@ -470,7 +523,7 @@ export interface VoiceLocalizePreviewStatus {
 }
 export interface SaveVoiceRequest {
     generatedVoiceId: string;
-    voiceName: string;
+    voiceName?: string | null;
     voiceDescription?: string | null;
     tags?: string[];
     primaryCategoryCode?: string;
@@ -480,7 +533,7 @@ export interface SaveVoiceRequest {
     gender?: VoiceGender | null;
     age?: VoiceAge | null;
     tone?: VoiceTone[];
-    accent?: VoiceAccent | null;
+    accent?: VoiceWritableAccent | null;
 }
 export interface HistoryItem {
     historyItemId: string;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.17.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.17.0";
+export const SDK_VERSION = "0.19.0";
 export const SDK_NAME = "@breeze.blue/sdk";

package/dist/voice-metadata.d.ts

@@ -5,10 +5,14 @@ export declare const VOICE_LANGUAGE_CODES: readonly ["af", "ar", "bg", "bn", "bs
 export declare const VOICE_TONE_MAX_ITEMS: 3;
 export declare const VOICE_ACCENT_CODES_BY_LANGUAGE: {
     readonly en: readonly ["american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese"];
-    readonly zh: readonly ["mandarin_guangdong", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_yunnan", "mandarin_henan", "cantonese"];
+    readonly zh: readonly ["mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese"];
 };
 export type VoiceGender = (typeof VOICE_GENDER_CODES)[number];
 export type VoiceAge = (typeof VOICE_AGE_CODES)[number];
 export type VoiceTone = (typeof VOICE_TONE_CODES)[number];
 export type VoiceLanguageCode = (typeof VOICE_LANGUAGE_CODES)[number];
-export type VoiceAccent = (typeof VOICE_ACCENT_CODES_BY_LANGUAGE)[keyof typeof VOICE_ACCENT_CODES_BY_LANGUAGE][number];
+export declare const VOICE_LEGACY_ACCENT_CODES_BY_LANGUAGE: {
+    readonly zh: readonly ["mandarin_guangdong", "mandarin_yunnan"];
+};
+export type VoiceWritableAccent = (typeof VOICE_ACCENT_CODES_BY_LANGUAGE)[keyof typeof VOICE_ACCENT_CODES_BY_LANGUAGE][number];
+export type VoiceAccent = VoiceWritableAccent | "mandarin_guangdong" | "mandarin_yunnan";

package/dist/voice-metadata.js

@@ -6,5 +6,6 @@ export const VOICE_LANGUAGE_CODES = ["af", "ar", "bg", "bn", "bs", "ca", "cs", "
 export const VOICE_TONE_MAX_ITEMS = 3;
 export const VOICE_ACCENT_CODES_BY_LANGUAGE = {
     en: ["american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese"],
-    zh: ["mandarin_guangdong", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_yunnan", "mandarin_henan", "cantonese"],
+    zh: ["mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese"],
 };
+export const VOICE_LEGACY_ACCENT_CODES_BY_LANGUAGE = { "zh": ["mandarin_guangdong", "mandarin_yunnan"] };

package/package.json

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