@breeze.blue/sdk 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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
+  shared Daily Trend with `{ sort: "trend", voiceType: "default" }`, signed
+  snapshot pagination, and language/category/gender/age/tone/accent filters.
+
 ## 0.11.0
 
 - Added canonical Voice `tags`, personal tag overrides, favorite management,

package/README.md

@@ -406,6 +406,14 @@ or voice ID.
 
 ```ts
 const voices = await client.voices.search({ search: "calm documentary narrator" });
+const newestFirst = await client.voices.search();
+const dailyTrend = await client.voices.search({
+  voiceType: "default",
+  sort: "trend",
+  languageCode: "zh",
+  gender: ["female", "neutral"],
+  tone: ["warm"],
+});
 const taggedFavorites = await client.voices.search({
   favoritesOnly: true,
   tags: ["narration", "novel=三体"],
@@ -417,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();
@@ -424,6 +434,11 @@ console.log(metadataOptions.languageCodes);
 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
+weak prior within the same relevance tier.
+
 Breeze voice creation is always two steps: produce a **preview**, let the
 user accept it, then **save the preview** as a real voice. Two ways to
 produce a preview:
@@ -450,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;
@@ -207,11 +207,18 @@ declare class VoicesResource {
     /**
      * Search every voice visible to the account. Catalog results use hybrid
      * semantic and text relevance; personal voices match by name, description,
-     * or identifier.
+     * or identifier. Listings default to stable creation-time order from newest
+     * to oldest. Pass sort: "trend" with voiceType: "default" for the shared
+     * Daily Trend order.
      */
     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>;
@@ -233,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

@@ -1492,10 +1492,12 @@ class VoicesResource {
     /**
      * Search every voice visible to the account. Catalog results use hybrid
      * semantic and text relevance; personal voices match by name, description,
-     * or identifier.
+     * or identifier. Listings default to stable creation-time order from newest
+     * to oldest. Pass sort: "trend" with voiceType: "default" for the shared
+     * Daily Trend order.
      */
     async search(params = {}, options) {
-        const result = await this.client.requestJson("GET", "/v1/voices", params, undefined, options);
+        const result = await this.client.requestJson("GET", "/v1/voices", { sort: "created_at_unix", sortDirection: "desc", ...params }, undefined, options);
         return Array.isArray(result.voices)
             ? { ...result, voices: result.voices.map(stripHiddenVoiceFields) }
             : result;
@@ -1504,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. */
@@ -1554,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,12 +351,23 @@ 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;
+    primaryCategoryCode?: string;
+    gender?: VoiceGender[];
+    age?: VoiceAge[];
+    tone?: VoiceTone[];
+    accent?: VoiceAccent;
     origin?: "designed" | "cloned" | string;
     voiceType?: "all" | "default" | "personal" | string;
-    sort?: "created_at_unix" | "name" | string;
+    sort?: "created_at_unix" | "name" | "trend" | string;
     sortDirection?: "asc" | "desc";
     nextPageToken?: string;
     page?: number;
@@ -413,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.11.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.11.0";
+export const SDK_VERSION = "0.13.0";
 export const SDK_NAME = "@breeze.blue/sdk";

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@breeze.blue/sdk",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
-  "author": "Breeze Blue <support@breeze.blue>",
+  "author": "Breeze Blue <support@breezeblue.ai>",
   "homepage": "https://breezeblue.ai",
   "repository": {
     "type": "git",