@breeze.blue/sdk 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.20.0
+
+- Manage Studio projects, chapters, clips, auxiliary tracks, audio instances and files through `client.studio`.
+- Import multi-chapter scripts with existing voices, preserve edit tokens and error metadata, and upload materials without forwarding API credentials.
+- Convert seconds and 48 kHz timeline frames with SDK helpers.
+
+## 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,11 @@ 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.
+
+## Studio management
+
+`client.studio` exposes `projects`, `chapters`, `clips`, `tracks`, `instances`, and `files`. Import scripts with existing voice IDs, edit inherited instructions and silence, upload MP3/WAV materials, and arrange background audio. Project writes require the latest edit token and a UUID operation ID. Conflicts preserve error metadata and are not retried automatically.
+
+See the [Studio initialization guide](https://docs.breezeblue.ai/guides/studio-projects) for a complete workflow. Signed uploads use a separate request without the API key. Management operations do not generate speech or export projects.

package/dist/_transform.js

@@ -19,7 +19,7 @@ function transform(value, keyFn) {
     if (isPlainObject(value)) {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
-            out[keyFn(k)] = transform(v, keyFn);
+            out[keyFn(k)] = ["client_refs", "clientRefs", "headers"].includes(k) ? v : transform(v, keyFn);
         }
         return out;
     }

package/dist/client.d.ts

@@ -1,6 +1,7 @@
+import { StudioResource } from "./studio.js";
 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;
@@ -14,6 +15,7 @@ export declare class BreezeBlueClient {
     readonly history: HistoryResource;
     readonly models: ModelsResource;
     readonly account: AccountResource;
+    readonly studio: StudioResource;
     constructor(options?: BreezeBlueClientOptions);
     requestJson<T>(method: string, path: string, params?: object, body?: unknown, options?: RequestOptions): Promise<T>;
     requestAudio(method: string, path: string, params?: object, body?: unknown, options?: RequestOptions): Promise<AudioResponse>;
@@ -252,6 +254,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 +276,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

@@ -1,3 +1,4 @@
+import { StudioResource } from "./studio.js";
 import { SpeechTimingStream } from "./timestamps.js";
 import { AudioResponse } from "./audio.js";
 import { BreezeBlueAPIError, BreezeBlueConfigurationError, BreezeBlueRealtimeError, errorFromResponse, } from "./errors.js";
@@ -33,6 +34,7 @@ export class BreezeBlueClient {
     history;
     models;
     account;
+    studio;
     constructor(options = {}) {
         const envApiKey = typeof process !== "undefined" ? process.env.BREEZE_API_KEY : undefined;
         const envBaseUrl = typeof process !== "undefined" ? process.env.BREEZE_BASE_URL : undefined;
@@ -50,6 +52,7 @@ export class BreezeBlueClient {
         this.history = new HistoryResource(this);
         this.models = new ModelsResource(this);
         this.account = new AccountResource(this);
+        this.studio = new StudioResource(this);
     }
     async requestJson(method, path, params, body, options) {
         const response = await this.request(method, path, params, body, options);
@@ -1580,6 +1583,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 +1617,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 +1773,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 +1785,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/index.d.ts

@@ -6,3 +6,5 @@ export type * from "./types.js";
 export * from "./voice-metadata.js";
 export { SpeechTimingStream } from "./timestamps.js";
 export type { SpeechTimingChunk, SpeechWithTimestamps, WordTimestamp } from "./timestamps.js";
+export * from "./studio.js";
+export type * from "./studio-types.js";

package/dist/index.js

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

package/dist/studio-types.d.ts

@@ -0,0 +1,337 @@
+export interface StudioChapterCreate {
+    expectedEditToken: string;
+    operationId: string;
+    title: string;
+}
+export interface StudioChapterDelete {
+    expectedEditToken: string;
+    operationId: string;
+    moveToChapterId?: string | null;
+}
+export interface StudioChapterList {
+    items: Array<StudioChapterView>;
+    editToken: string;
+}
+export interface StudioChapterPatch {
+    expectedEditToken: string;
+    operationId: string;
+    title: string;
+}
+export interface StudioChapterResult {
+    chapter: StudioChapterView;
+    editToken: string;
+}
+export interface StudioChapterView {
+    id: string;
+    title: string;
+    deleted: boolean;
+    clipIds: Array<string>;
+}
+export interface StudioClipBatchCreate {
+    expectedEditToken: string;
+    operationId: string;
+    chapterId?: string | null;
+    afterClipId?: string | null;
+    clips: Array<StudioClipFields>;
+}
+export interface StudioClipBatchPatch {
+    expectedEditToken: string;
+    operationId: string;
+    updates: Array<StudioClipUpdateItem>;
+}
+export interface StudioClipBulkDelete {
+    expectedEditToken: string;
+    operationId: string;
+    clipIds: Array<string>;
+}
+export interface StudioClipCreate {
+    expectedEditToken: string;
+    operationId: string;
+    clientRef?: string | null;
+    name?: string;
+    script?: string;
+    instructions?: string;
+    voiceId?: string | null;
+    playback?: StudioPlayback;
+    trailingSilenceMs?: number | null;
+    chapterId?: string | null;
+    afterClipId?: string | null;
+}
+export interface StudioClipFields {
+    clientRef?: string | null;
+    name?: string;
+    script?: string;
+    instructions?: string;
+    voiceId?: string | null;
+    playback?: StudioPlayback;
+    trailingSilenceMs?: number | null;
+}
+export interface StudioClipList {
+    items: Array<StudioClipView>;
+    editToken: string;
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface StudioClipMove {
+    expectedEditToken: string;
+    operationId: string;
+    clipIds: Array<string>;
+    chapterId: string;
+    afterClipId?: string | null;
+}
+export interface StudioClipPatch {
+    expectedEditToken: string;
+    operationId: string;
+    name?: string | null;
+    script?: string | null;
+    instructions?: string | null;
+    voiceId?: string | null;
+    playback?: StudioPlayback | null;
+    trailingSilenceMs?: number | null;
+}
+export interface StudioClipReorder {
+    expectedEditToken: string;
+    operationId: string;
+    ids: Array<string>;
+    chapterId: string;
+}
+export interface StudioClipResult {
+    clip: StudioClipView;
+    editToken: string;
+}
+export interface StudioClipUpdateItem {
+    name?: string | null;
+    script?: string | null;
+    instructions?: string | null;
+    voiceId?: string | null;
+    playback?: StudioPlayback | null;
+    trailingSilenceMs?: number | null;
+    clipId: string;
+}
+export interface StudioClipView {
+    id: string;
+    chapterId: string | null;
+    name: string;
+    script: string;
+    instructions: string;
+    voiceId: string | null;
+    voice: StudioVoiceSummary | null;
+    playback: StudioPlayback;
+    trailingSilenceMs: number | null;
+    effectiveInstructions: string;
+    effectiveTrailingSilenceMs: number;
+    version: number;
+}
+export interface StudioDeleted {
+    deleted?: boolean;
+    editToken?: string | null;
+}
+export interface StudioEdit {
+    expectedEditToken: string;
+    operationId: string;
+}
+export interface StudioEffects {
+    speed?: number;
+    volume?: number;
+    fadeInSeconds?: number;
+    fadeOutSeconds?: number;
+}
+export interface StudioFileCreate {
+    operationId: string;
+    projectId?: string | null;
+    name: string;
+    sizeBytes: number;
+    mimeType: "audio/mpeg" | "audio/wav";
+}
+export interface StudioFileDelete {
+    expectedRevision: number;
+}
+export interface StudioFileList {
+    items: Array<StudioFileView>;
+    nextOffset: number | null;
+}
+export interface StudioFilePatch {
+    expectedRevision: number;
+    name: string;
+}
+export interface StudioFileView {
+    id: string;
+    projectId: string | null;
+    name: string;
+    revision: number;
+    status: string;
+    frames: number | null;
+    sampleRate: number;
+    sizeBytes: number | null;
+    errorCode: string | null;
+    errorReason: string | null;
+    errorMessage: string | null;
+    references: number;
+}
+export interface StudioImportChapter {
+    clientRef?: string | null;
+    title: string;
+    clips: Array<StudioClipFields>;
+}
+export interface StudioInstanceCreate {
+    expectedEditToken: string;
+    operationId: string;
+    fileId: string;
+    position?: StudioPosition;
+    trimStart?: number;
+    trimEnd: number;
+    effects?: StudioEffects;
+    length?: number | null;
+}
+export interface StudioInstanceList {
+    items: Array<StudioInstanceView>;
+    editToken: string;
+}
+export interface StudioInstancePatch {
+    expectedEditToken: string;
+    operationId: string;
+    fileId?: string | null;
+    position?: StudioPosition | null;
+    trimStart?: number | null;
+    trimEnd?: number | null;
+    effects?: StudioEffects | null;
+    length?: number | null;
+    trackId?: string | null;
+}
+export interface StudioInstanceResult {
+    instance: StudioInstanceView;
+    editToken: string;
+}
+export interface StudioInstanceView {
+    id: string;
+    fileId: string;
+    position: StudioPosition;
+    trimStart: number;
+    trimEnd: number;
+    effects: StudioEffects;
+    length?: number | null;
+    phase?: number;
+    envelopeOffset?: number;
+    envelopeLength?: number | null;
+    issues?: Array<string>;
+}
+export interface StudioPlayback {
+    speed?: number;
+    volume?: number;
+}
+export interface StudioPosition {
+    mode?: "fixed" | "follow";
+    frame?: number;
+    clipId?: string | null;
+    edge?: "start" | "end";
+    offset?: number;
+}
+export interface StudioProjectCreate {
+    title?: string;
+    description?: string;
+    ttsSettings?: StudioTtsSettings | null;
+    defaultVoiceId?: string | null;
+    defaultInstructions?: string;
+    defaultSilenceMs?: number;
+    operationId: string;
+}
+export interface StudioProjectImport {
+    title?: string;
+    description?: string;
+    ttsSettings?: StudioTtsSettings | null;
+    defaultVoiceId?: string | null;
+    defaultInstructions?: string;
+    defaultSilenceMs?: number;
+    operationId: string;
+    chapters: Array<StudioImportChapter>;
+}
+export interface StudioProjectList {
+    items: Array<StudioProjectView>;
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface StudioProjectPatch {
+    expectedEditToken: string;
+    operationId: string;
+    title?: string | null;
+    description?: string | null;
+    ttsSettings?: StudioTtsSettings | null;
+    defaultVoiceId?: string | null;
+    defaultInstructions?: string | null;
+    defaultSilenceMs?: number | null;
+}
+export interface StudioProjectResult {
+    project: StudioProjectView;
+    editToken: string;
+    clientRefs?: Record<string, string>;
+    createdIds?: Array<string>;
+}
+export interface StudioProjectView {
+    title?: string;
+    description?: string;
+    ttsSettings?: StudioTtsSettings | null;
+    defaultVoiceId?: string | null;
+    defaultInstructions?: string;
+    defaultSilenceMs?: number;
+    id: string;
+    editToken: string;
+    createdAt: string;
+    updatedAt: string;
+    chapterCount: number;
+    clipCount: number;
+}
+export interface StudioReorder {
+    expectedEditToken: string;
+    operationId: string;
+    ids: Array<string>;
+}
+export interface StudioTrackCreate {
+    expectedEditToken: string;
+    operationId: string;
+    name: string;
+    chapterId?: string | null;
+    volume?: number;
+    muted?: boolean;
+}
+export interface StudioTrackList {
+    items: Array<StudioTrackView>;
+    editToken: string;
+}
+export interface StudioTrackPatch {
+    expectedEditToken: string;
+    operationId: string;
+    name?: string | null;
+    chapterId?: string | null;
+    volume?: number | null;
+    muted?: boolean | null;
+}
+export interface StudioTrackResult {
+    track: StudioTrackView;
+    editToken: string;
+}
+export interface StudioTrackView {
+    id: string;
+    name: string;
+    chapterId?: string | null;
+    volume?: number;
+    muted?: boolean;
+    readonly?: boolean;
+    instances?: Array<StudioInstanceView>;
+}
+export interface StudioTtsSettings {
+    model?: string | null;
+    language?: string | null;
+    generationLanguage?: string | null;
+    guidanceScale?: number | null;
+}
+export interface StudioUploadResult {
+    uploadUrl: string;
+    headers?: Record<string, string>;
+}
+export interface StudioVoiceSummary {
+    id: string;
+    name: string;
+    available: boolean;
+}

package/dist/studio-types.js

@@ -0,0 +1 @@
+export {};

package/dist/studio.d.ts

@@ -0,0 +1,91 @@
+import type { BreezeBlueClient } from "./client.js";
+import type { RequestOptions } from "./types.js";
+import type * as Types from "./studio-types.js";
+export declare function secondsToFrames(seconds: number): number;
+export declare function framesToSeconds(frames: number): number;
+export declare class StudioProjectsResource {
+    private client;
+    constructor(client: BreezeBlueClient);
+    list(params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectList>;
+    create(body: Types.StudioProjectCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    importProject(body: Types.StudioProjectImport, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    get(projectId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    update(projectId: string, body: Types.StudioProjectPatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    delete(projectId: string, body: Types.StudioEdit, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioDeleted>;
+}
+export declare class StudioChaptersResource {
+    private client;
+    constructor(client: BreezeBlueClient);
+    list(projectId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioChapterList>;
+    create(projectId: string, body: Types.StudioChapterCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    reorder(projectId: string, body: Types.StudioReorder, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    get(projectId: string, chapterId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioChapterResult>;
+    update(projectId: string, chapterId: string, body: Types.StudioChapterPatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    delete(projectId: string, chapterId: string, body: Types.StudioChapterDelete, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    restore(projectId: string, chapterId: string, body: Types.StudioEdit, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+}
+export declare class StudioClipsResource {
+    private client;
+    constructor(client: BreezeBlueClient);
+    list(projectId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioClipList>;
+    create(projectId: string, body: Types.StudioClipCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    batchCreate(projectId: string, body: Types.StudioClipBatchCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    batchUpdate(projectId: string, body: Types.StudioClipBatchPatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    bulkDelete(projectId: string, body: Types.StudioClipBulkDelete, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    reorder(projectId: string, body: Types.StudioClipReorder, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    move(projectId: string, body: Types.StudioClipMove, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    get(projectId: string, clipId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioClipResult>;
+    update(projectId: string, clipId: string, body: Types.StudioClipPatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    delete(projectId: string, clipId: string, body: Types.StudioEdit, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+}
+export declare class StudioTracksResource {
+    private client;
+    constructor(client: BreezeBlueClient);
+    list(projectId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioTrackList>;
+    create(projectId: string, body: Types.StudioTrackCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    reorder(projectId: string, body: Types.StudioReorder, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    get(projectId: string, trackId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioTrackResult>;
+    update(projectId: string, trackId: string, body: Types.StudioTrackPatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    delete(projectId: string, trackId: string, body: Types.StudioEdit, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+}
+export declare class StudioInstancesResource {
+    private client;
+    constructor(client: BreezeBlueClient);
+    list(projectId: string, trackId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioInstanceList>;
+    create(projectId: string, trackId: string, body: Types.StudioInstanceCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    get(projectId: string, trackId: string, instanceId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioInstanceResult>;
+    update(projectId: string, trackId: string, instanceId: string, body: Types.StudioInstancePatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+    delete(projectId: string, trackId: string, instanceId: string, body: Types.StudioEdit, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioProjectResult>;
+}
+export declare class StudioFilesResource {
+    private client;
+    constructor(client: BreezeBlueClient);
+    list(params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioFileList>;
+    create(body: Types.StudioFileCreate, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioFileView>;
+    get(fileId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioFileView>;
+    update(fileId: string, body: Types.StudioFilePatch, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioFileView>;
+    delete(fileId: string, body: Types.StudioFileDelete, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioDeleted>;
+    uploadUrl(fileId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioUploadResult>;
+    complete(fileId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioFileView>;
+    retry(fileId: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Types.StudioFileView>;
+    waitReady(fileId: string, options?: {
+        timeout?: number;
+        pollInterval?: number;
+        signal?: AbortSignal;
+    }): Promise<Types.StudioFileView>;
+    upload(file: Blob, input: {
+        operationId: string;
+        name: string;
+        projectId?: string;
+        wait?: boolean;
+    }, options?: RequestOptions): Promise<Types.StudioFileView>;
+}
+export declare class StudioResource {
+    readonly projects: StudioProjectsResource;
+    readonly chapters: StudioChaptersResource;
+    readonly clips: StudioClipsResource;
+    readonly tracks: StudioTracksResource;
+    readonly instances: StudioInstancesResource;
+    readonly files: StudioFilesResource;
+    constructor(client: BreezeBlueClient);
+}

package/dist/studio.js

@@ -0,0 +1,213 @@
+export function secondsToFrames(seconds) {
+    if (!Number.isFinite(seconds))
+        throw new Error("seconds must be finite");
+    return Math.sign(seconds) * Math.round(Math.abs(seconds) * 48000);
+}
+export function framesToSeconds(frames) { return frames / 48000; }
+export class StudioProjectsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects`, params, undefined, options);
+    }
+    create(body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects`, params, body, options);
+    }
+    importProject(body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/import`, params, body, options);
+    }
+    get(projectId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}`, params, undefined, options);
+    }
+    update(projectId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}`, params, body, options);
+    }
+    delete(projectId, body, params, options) {
+        return this.client.requestJson("DELETE", `/v1/studio/projects/${encodeURIComponent(projectId)}`, params, body, options);
+    }
+}
+export class StudioChaptersResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(projectId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters`, params, undefined, options);
+    }
+    create(projectId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters`, params, body, options);
+    }
+    reorder(projectId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters/reorder`, params, body, options);
+    }
+    get(projectId, chapterId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters/${encodeURIComponent(chapterId)}`, params, undefined, options);
+    }
+    update(projectId, chapterId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters/${encodeURIComponent(chapterId)}`, params, body, options);
+    }
+    delete(projectId, chapterId, body, params, options) {
+        return this.client.requestJson("DELETE", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters/${encodeURIComponent(chapterId)}`, params, body, options);
+    }
+    restore(projectId, chapterId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/chapters/${encodeURIComponent(chapterId)}/restore`, params, body, options);
+    }
+}
+export class StudioClipsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(projectId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips`, params, undefined, options);
+    }
+    create(projectId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips`, params, body, options);
+    }
+    batchCreate(projectId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/batch`, params, body, options);
+    }
+    batchUpdate(projectId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/batch`, params, body, options);
+    }
+    bulkDelete(projectId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/bulk-delete`, params, body, options);
+    }
+    reorder(projectId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/reorder`, params, body, options);
+    }
+    move(projectId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/move`, params, body, options);
+    }
+    get(projectId, clipId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/${encodeURIComponent(clipId)}`, params, undefined, options);
+    }
+    update(projectId, clipId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/${encodeURIComponent(clipId)}`, params, body, options);
+    }
+    delete(projectId, clipId, body, params, options) {
+        return this.client.requestJson("DELETE", `/v1/studio/projects/${encodeURIComponent(projectId)}/clips/${encodeURIComponent(clipId)}`, params, body, options);
+    }
+}
+export class StudioTracksResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(projectId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks`, params, undefined, options);
+    }
+    create(projectId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks`, params, body, options);
+    }
+    reorder(projectId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/reorder`, params, body, options);
+    }
+    get(projectId, trackId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}`, params, undefined, options);
+    }
+    update(projectId, trackId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}`, params, body, options);
+    }
+    delete(projectId, trackId, body, params, options) {
+        return this.client.requestJson("DELETE", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}`, params, body, options);
+    }
+}
+export class StudioInstancesResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(projectId, trackId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}/instances`, params, undefined, options);
+    }
+    create(projectId, trackId, body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}/instances`, params, body, options);
+    }
+    get(projectId, trackId, instanceId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}/instances/${encodeURIComponent(instanceId)}`, params, undefined, options);
+    }
+    update(projectId, trackId, instanceId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}/instances/${encodeURIComponent(instanceId)}`, params, body, options);
+    }
+    delete(projectId, trackId, instanceId, body, params, options) {
+        return this.client.requestJson("DELETE", `/v1/studio/projects/${encodeURIComponent(projectId)}/tracks/${encodeURIComponent(trackId)}/instances/${encodeURIComponent(instanceId)}`, params, body, options);
+    }
+}
+export class StudioFilesResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(params, options) {
+        return this.client.requestJson("GET", `/v1/studio/files`, params, undefined, options);
+    }
+    create(body, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/files`, params, body, options);
+    }
+    get(fileId, params, options) {
+        return this.client.requestJson("GET", `/v1/studio/files/${encodeURIComponent(fileId)}`, params, undefined, options);
+    }
+    update(fileId, body, params, options) {
+        return this.client.requestJson("PATCH", `/v1/studio/files/${encodeURIComponent(fileId)}`, params, body, options);
+    }
+    delete(fileId, body, params, options) {
+        return this.client.requestJson("DELETE", `/v1/studio/files/${encodeURIComponent(fileId)}`, params, body, options);
+    }
+    uploadUrl(fileId, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/files/${encodeURIComponent(fileId)}/upload`, params, undefined, options);
+    }
+    complete(fileId, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/files/${encodeURIComponent(fileId)}/complete`, params, undefined, options);
+    }
+    retry(fileId, params, options) {
+        return this.client.requestJson("POST", `/v1/studio/files/${encodeURIComponent(fileId)}/retry`, params, undefined, options);
+    }
+    async waitReady(fileId, options = {}) {
+        const deadline = Date.now() + (options.timeout ?? 300000);
+        while (true) {
+            options.signal?.throwIfAborted();
+            const value = await this.get(fileId, undefined, { signal: options.signal });
+            if (value.status === "ready")
+                return value;
+            if (value.status === "failed")
+                throw new Error(value.errorMessage ?? "Studio file processing failed");
+            if (Date.now() >= deadline)
+                throw new Error("Studio file is still processing; query the same file ID to resume");
+            await new Promise(resolve => setTimeout(resolve, Math.max(100, Math.min(options.pollInterval ?? 1000, deadline - Date.now()))));
+        }
+    }
+    async upload(file, input, options = {}) {
+        const mimeType = input.name.toLowerCase().endsWith(".mp3") ? "audio/mpeg" : input.name.toLowerCase().endsWith(".wav") ? "audio/wav" : null;
+        if (!mimeType)
+            throw new Error("Studio accepts MP3 or WAV files");
+        let value = await this.create({ operationId: input.operationId, name: input.name, projectId: input.projectId, sizeBytes: file.size, mimeType }, undefined, options);
+        if (value.status === "uploading") {
+            const signed = await this.uploadUrl(value.id, undefined, options);
+            // Never use the API request helper for a signed storage URL.
+            const response = await this.client.fetch(signed.uploadUrl, { method: "PUT", headers: signed.headers, body: file, credentials: "omit", redirect: "error", signal: options.signal });
+            if (!response.ok)
+                throw new Error(`Studio upload failed: ${response.status}`);
+            value = await this.complete(value.id, undefined, options);
+        }
+        return input.wait === false ? value : this.waitReady(value.id, { signal: options.signal });
+    }
+}
+export class StudioResource {
+    projects;
+    chapters;
+    clips;
+    tracks;
+    instances;
+    files;
+    constructor(client) {
+        this.projects = new StudioProjectsResource(client);
+        this.chapters = new StudioChaptersResource(client);
+        this.clips = new StudioClipsResource(client);
+        this.tracks = new StudioTracksResource(client);
+        this.instances = new StudioInstancesResource(client);
+        this.files = new StudioFilesResource(client);
+    }
+}

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.20.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.20.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.20.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breezeblue.ai>",