@breeze.blue/sdk 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.13.0
+
+- `voices.random(...)` accepts optional `languageCode` and `voiceType`
+  (`"default"` or `"personal"`) filters that narrow the random pool.
+- Added `voices.streamDesignPreview(...)`, which returns a live
+  `AudioResponse` with `generatedVoiceId`; the Node `stream()` helper consumes
+  its response body directly.
+- Clarified that `voices.streamPreview(...)` downloads an already completed
+  preview.
+
 ## 0.12.0
 
 - Voice listings preserve the `created_at_unix desc` default and support the

package/README.md

@@ -425,6 +425,8 @@ const settings = await client.voices.getSettings(firstVoiceId);
 
 const randomVoice = await client.voices.random();
 console.log(randomVoice.voiceId, randomVoice.name);
+// Narrow the random pool by language and/or voice source.
+const randomCatalogVoice = await client.voices.random({ languageCode: "zh", voiceType: "default" });
 
 // Discover the current code-only Voice Metadata contract before building a form.
 const metadataOptions = await client.voices.metadataOptions();
@@ -463,9 +465,24 @@ const design = await client.voices.createDesignPreview({
 generatedVoiceId = design.previews[0].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:
+
+```ts
+import { stream } from "@breeze.blue/sdk/node";
+
+const livePreview = await client.voices.streamDesignPreview({
+  voiceDescription: "Warm documentary narrator with clear articulation.",
+  text: "This is a short preview script.",
+});
+await stream(livePreview);
+generatedVoiceId = livePreview.generatedVoiceId!;
+```
+
 `files` is also accepted with exactly one item.
 
-Stream the preview so the user can audition it, then save the one they
+Download a completed preview so the user can audition it, then save the one they
 pick:
 
 ```ts

package/dist/audio.d.ts

@@ -34,6 +34,7 @@ export declare class AudioResponse {
     readonly response: Response;
     readonly contentType: string;
     readonly historyItemId: string | null;
+    readonly generatedVoiceId: string | null;
     readonly filename: string | null;
     constructor(response: Response, options?: AudioResponseOptions);
     get headers(): Headers;

package/dist/audio.js

@@ -2,12 +2,14 @@ export class AudioResponse {
     response;
     contentType;
     historyItemId;
+    generatedVoiceId;
     filename;
     #buffer = null;
     constructor(response, options = {}) {
         this.response = response;
         this.contentType = response.headers.get("content-type")?.split(";", 1)[0].trim() || "application/octet-stream";
         this.historyItemId = response.headers.get("history-item-id");
+        this.generatedVoiceId = response.headers.get("generated-voice-id");
         this.filename = options.filename ?? filenameFromContentDisposition(response.headers.get("content-disposition"));
     }
     get headers() {

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { AudioResponse } from "./audio.js";
-import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, 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, VoiceEditRequest, VoiceList, VoiceMetadataOptions, VoiceSearchParams, VoiceSettings } from "./types.js";
+import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, 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";
 export declare class BreezeBlueClient {
     readonly apiKey: string | undefined;
     readonly baseUrl: string;
@@ -213,7 +213,12 @@ declare class VoicesResource {
      */
     search(params?: VoiceSearchParams, options?: RequestOptions): Promise<VoiceList>;
     get(voiceId: string, options?: RequestOptions): Promise<Voice>;
-    random(options?: RequestOptions): Promise<Voice>;
+    /**
+     * Pick one random voice visible to the account. Pass `languageCode` and/or
+     * `voiceType` to narrow the pool; with no filters the pool is personal
+     * voices plus the public catalog.
+     */
+    random(params?: VoiceRandomParams, options?: RequestOptions): Promise<Voice>;
     /** Return stable Voice Metadata codes and language-accent constraints. */
     metadataOptions(options?: RequestOptions): Promise<VoiceMetadataOptions>;
     edit(voiceId: string, request: VoiceEditRequest, options?: RequestOptions): Promise<GenericStatus>;
@@ -235,7 +240,12 @@ declare class VoicesResource {
      * {@link savePreview}.
      */
     createDesignPreview(request: VoiceDesignRequest, options?: AudioRequestOptions): Promise<VoiceDesignResponse>;
-    /** Stream the audio of a clone or design preview before saving. */
+    /**
+     * Generate exactly one voice design preview as live 24 kHz mono PCM.
+     * A clean end means `generatedVoiceId` is ready for {@link savePreview}.
+     */
+    streamDesignPreview(request: VoiceDesignStreamRequest, options?: RequestOptions): Promise<AudioResponse>;
+    /** 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. */
     savePreview(request: SaveVoiceRequest, options?: RequestOptions): Promise<SavedVoice>;

package/dist/client.js

@@ -1506,8 +1506,13 @@ class VoicesResource {
         const result = await this.client.requestJson("GET", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, undefined, options);
         return stripHiddenVoiceFields(result);
     }
-    async random(options) {
-        const result = await this.client.requestJson("GET", "/v1/voices/random", undefined, undefined, options);
+    /**
+     * Pick one random voice visible to the account. Pass `languageCode` and/or
+     * `voiceType` to narrow the pool; with no filters the pool is personal
+     * voices plus the public catalog.
+     */
+    async random(params = {}, options) {
+        const result = await this.client.requestJson("GET", "/v1/voices/random", params, undefined, options);
         return stripHiddenVoiceFields(result);
     }
     /** Return stable Voice Metadata codes and language-accent constraints. */
@@ -1556,7 +1561,14 @@ class VoicesResource {
     createDesignPreview(request, options = {}) {
         return this.client.requestJson("POST", "/v1/voice-previews/design", { outputFormat: options.outputFormat }, request, options);
     }
-    /** Stream the audio of a clone or design preview before saving. */
+    /**
+     * Generate exactly one voice design preview as live 24 kHz mono PCM.
+     * A clean end means `generatedVoiceId` is ready for {@link savePreview}.
+     */
+    streamDesignPreview(request, options) {
+        return this.client.requestAudio("POST", "/v1/voice-previews/design/stream", undefined, request, 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);
     }

package/dist/types.d.ts

@@ -351,6 +351,12 @@ export interface VoiceMetadataOptions {
     toneMaxItems: number;
     accentCodesByLanguage: Record<VoiceLanguageCode, VoiceAccent[]>;
 }
+export interface VoiceRandomParams {
+    /** Only pick from voices whose saved audio language matches this code. */
+    languageCode?: VoiceLanguageCode;
+    /** Voice source filter. Omit to pick from personal voices and the public catalog. */
+    voiceType?: "default" | "personal" | string;
+}
 export interface VoiceSearchParams {
     search?: string;
     languageCode?: VoiceLanguageCode;
@@ -418,6 +424,13 @@ export interface VoiceDesignRequest {
     guidanceScale?: number | null;
     previewCount?: number;
 }
+export interface VoiceDesignStreamRequest {
+    voiceDescription: string;
+    text?: string;
+    modelId?: string;
+    languageCode?: VoiceLanguageCode;
+    guidanceScale?: number | null;
+}
 export interface VoiceDesignPreview {
     generatedVoiceId: string;
     audioBase64: string;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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