@breeze.blue/sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.11.0
+
+- Added canonical Voice `tags`, personal tag overrides, favorite management,
+  exact tag filters, and `voices.updateTags()` / `favorite()` / `unfavorite()`.
+- `voices.savePreview(...)` now requires `languageCode`, preventing saved
+  voices from being created without explicit reference-language metadata.
+- Added `voices.metadataOptions()` and the typed `VoiceLanguageCode` contract
+  for discovering Voice Metadata codes and language-to-accent constraints.
+- Sync and async TTS accept explicit sample-rate and bitrate output profiles,
+  such as `wav_48000` and `mp3_44100_128`.
+
 ## 0.10.0
 
 - Added typed Voice Metadata codes and camelCase response fields for gender,
@@ -205,7 +216,7 @@
 
 ## 0.1.2
 
-- Breaking: all request and response field names are now camelCase (e.g. `modelId`, `voiceId`, `voiceSettings`, `historyItemId`). The SDK transparently translates to the snake_case HTTP wire format on send and from snake_case on receive. `labels: Record<string, string>` is preserved verbatim.
+- Breaking: all request and response field names are now camelCase (e.g. `modelId`, `voiceId`, `voiceSettings`, `historyItemId`). The SDK transparently translates to the snake_case HTTP wire format on send and from snake_case on receive.
 - Removed remaining ElevenLabs-positioning copy from the README and package keywords. Quickstart and reference examples use the published packages only.
 
 ## 0.1.1

package/README.md

@@ -393,6 +393,10 @@ Streaming text-to-speech defaults to `pcm` to reduce time to first audio. Pass
 `{ outputFormat: "wav" }` or `{ outputFormat: "mp3" }` when you need that wire
 format explicitly.
 
+Sync and async text-to-speech also take a sample rate and, for the lossy encodings, a bitrate, such as
+`{ outputFormat: "wav_48000" }`. Breeze resamples its native 24000 Hz output for
+downstream compatibility; profiles carrying a sample rate are not available for streaming.
+
 ## Voices
 
 Search every voice available to the account and inspect a single voice. Public
@@ -402,6 +406,10 @@ or voice ID.
 
 ```ts
 const voices = await client.voices.search({ search: "calm documentary narrator" });
+const taggedFavorites = await client.voices.search({
+  favoritesOnly: true,
+  tags: ["narration", "novel=三体"],
+});
 const firstVoiceId = voices.voices[0].voiceId;
 
 const voice = await client.voices.get(firstVoiceId);
@@ -409,6 +417,11 @@ const settings = await client.voices.getSettings(firstVoiceId);
 
 const randomVoice = await client.voices.random();
 console.log(randomVoice.voiceId, randomVoice.name);
+
+// Discover the current code-only Voice Metadata contract before building a form.
+const metadataOptions = await client.voices.metadataOptions();
+console.log(metadataOptions.languageCodes);
+console.log(metadataOptions.accentCodesByLanguage.en);
 ```
 
 Breeze voice creation is always two steps: produce a **preview**, let the
@@ -454,6 +467,7 @@ const saved = await client.voices.savePreview({
   age: "middle_aged",
   tone: ["warm", "articulate"],
   accent: "american",
+  tags: ["narration", "novel=三体"],
 });
 ```
 
@@ -468,12 +482,18 @@ await client.voices.edit(saved.voiceId, {
 // null clears nullable metadata; [] clears tone. Omitted fields remain unchanged.
 await client.voices.edit(saved.voiceId, { accent: null, tone: [] });
 await client.voices.editSettings(saved.voiceId, { guidanceScale: 1.2 });
+await client.voices.favorite(firstVoiceId);
+await client.voices.updateTags(firstVoiceId, ["narration", "novel=三体"]);
+await client.voices.updateTags(firstVoiceId, []); // Resume owner tag inheritance.
+await client.voices.unfavorite(firstVoiceId);
 await client.voices.delete(saved.voiceId);
 ```
 
 Voice Metadata uses stable code values. `gender`, `age`, and `accent` may be
 `null`; `tone` contains up to three distinct codes. English and Chinese use
 different accent code sets, and other languages require `accent: null`.
+Call `client.voices.metadataOptions()` to discover every accepted code and the
+language-to-accent cascade at runtime.
 
 ## History, Models, and Account
 

package/dist/_transform.js

@@ -1,6 +1,3 @@
-// Keys whose values are user-defined dictionaries; we transform the key itself
-// but never recurse into the value.
-const OPAQUE_VALUE_KEYS = new Set(["labels"]);
 function snakeToCamel(key) {
     return key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
 }
@@ -15,24 +12,22 @@ function isPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
-function transform(value, keyFn, opaqueKey) {
+function transform(value, keyFn) {
     if (Array.isArray(value)) {
-        return value.map((item) => transform(item, keyFn, false));
+        return value.map((item) => transform(item, keyFn));
     }
     if (isPlainObject(value)) {
-        if (opaqueKey)
-            return value;
         const out = {};
         for (const [k, v] of Object.entries(value)) {
-            out[keyFn(k)] = transform(v, keyFn, OPAQUE_VALUE_KEYS.has(k));
+            out[keyFn(k)] = transform(v, keyFn);
         }
         return out;
     }
     return value;
 }
 export function camelizeKeys(value) {
-    return transform(value, snakeToCamel, false);
+    return transform(value, snakeToCamel);
 }
 export function snakeizeKeys(value) {
-    return transform(value, camelToSnake, false);
+    return transform(value, camelToSnake);
 }

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, 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, VoiceEditRequest, VoiceList, VoiceMetadataOptions, VoiceSearchParams, VoiceSettings } from "./types.js";
 export declare class BreezeBlueClient {
     readonly apiKey: string | undefined;
     readonly baseUrl: string;
@@ -212,7 +212,12 @@ declare class VoicesResource {
     search(params?: VoiceSearchParams, options?: RequestOptions): Promise<VoiceList>;
     get(voiceId: string, options?: RequestOptions): Promise<Voice>;
     random(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>;
+    updateTags(voiceId: string, tags: string[], options?: RequestOptions): Promise<Voice>;
+    favorite(voiceId: string, options?: RequestOptions): Promise<Voice>;
+    unfavorite(voiceId: string, options?: RequestOptions): Promise<Voice>;
     delete(voiceId: string, options?: RequestOptions): Promise<GenericStatus>;
     getSettings(voiceId: string, options?: RequestOptions): Promise<Required<VoiceSettings>>;
     editSettings(voiceId: string, settings: VoiceSettings, options?: RequestOptions): Promise<Required<VoiceSettings>>;

package/dist/client.js

@@ -1494,18 +1494,39 @@ class VoicesResource {
      * semantic and text relevance; personal voices match by name, description,
      * or identifier.
      */
-    search(params = {}, options) {
-        return this.client.requestJson("GET", "/v1/voices", params, undefined, options);
+    async search(params = {}, options) {
+        const result = await this.client.requestJson("GET", "/v1/voices", params, undefined, options);
+        return Array.isArray(result.voices)
+            ? { ...result, voices: result.voices.map(stripHiddenVoiceFields) }
+            : result;
     }
-    get(voiceId, options) {
-        return this.client.requestJson("GET", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, undefined, options);
+    async get(voiceId, options) {
+        const result = await this.client.requestJson("GET", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, undefined, options);
+        return stripHiddenVoiceFields(result);
     }
-    random(options) {
-        return this.client.requestJson("GET", "/v1/voices/random", undefined, undefined, options);
+    async random(options) {
+        const result = await this.client.requestJson("GET", "/v1/voices/random", undefined, undefined, options);
+        return stripHiddenVoiceFields(result);
+    }
+    /** Return stable Voice Metadata codes and language-accent constraints. */
+    metadataOptions(options) {
+        return this.client.requestJson("GET", "/v1/voice-metadata/options", undefined, undefined, options);
     }
     edit(voiceId, request, options) {
         return this.client.requestJson("PATCH", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, voiceEditForm(request), options);
     }
+    async updateTags(voiceId, tags, options) {
+        const result = await this.client.requestJson("PUT", `/v1/voices/${encodeURIComponent(voiceId)}/tags`, undefined, { tags }, options);
+        return stripHiddenVoiceFields(result);
+    }
+    async favorite(voiceId, options) {
+        const result = await this.client.requestJson("PUT", `/v1/voices/${encodeURIComponent(voiceId)}/favorite`, undefined, undefined, options);
+        return stripHiddenVoiceFields(result);
+    }
+    async unfavorite(voiceId, options) {
+        const result = await this.client.requestJson("DELETE", `/v1/voices/${encodeURIComponent(voiceId)}/favorite`, undefined, undefined, options);
+        return stripHiddenVoiceFields(result);
+    }
     delete(voiceId, options) {
         return this.client.requestJson("DELETE", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, undefined, options);
     }
@@ -1538,11 +1559,11 @@ class VoicesResource {
         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. */
-    savePreview(request, options) {
-        return this.client.requestJson("POST", `/v1/voice-previews/${encodeURIComponent(request.generatedVoiceId)}/save`, undefined, {
+    async savePreview(request, options) {
+        const result = await this.client.requestJson("POST", `/v1/voice-previews/${encodeURIComponent(request.generatedVoiceId)}/save`, undefined, {
             voiceName: request.voiceName,
             voiceDescription: request.voiceDescription,
-            labels: request.labels,
+            tags: request.tags,
             primaryCategoryCode: request.primaryCategoryCode,
             visibility: request.visibility,
             playedNotSelectedVoiceIds: request.playedNotSelectedVoiceIds,
@@ -1552,6 +1573,7 @@ class VoicesResource {
             tone: request.tone,
             accent: request.accent,
         }, options);
+        return stripHiddenVoiceFields(result);
     }
 }
 class HistoryResource {
@@ -1654,7 +1676,13 @@ function buildUrl(baseUrl, path, params) {
     for (const [key, value] of Object.entries(params ?? {})) {
         if (value === undefined || value === null)
             continue;
-        url.searchParams.set(key, String(value));
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(key, String(item));
+        }
+        else {
+            url.searchParams.set(key, String(value));
+        }
     }
     return url.toString();
 }
@@ -1684,7 +1712,7 @@ function clonePreviewForm(request) {
     const form = new FormData();
     form.set("name", request.name);
     appendOptional(form, "description", request.description);
-    appendOptional(form, "labels", request.labels ? JSON.stringify(request.labels) : undefined);
+    appendOptional(form, "language_code", request.languageCode);
     appendOptional(form, "text", request.text);
     appendOptional(form, "instructions", request.instructions);
     for (const file of normalizeFiles(request.file, request.files, { required: true })) {
@@ -1696,7 +1724,10 @@ function voiceEditForm(request) {
     const form = new FormData();
     appendOptional(form, "name", request.name);
     appendOptional(form, "description", request.description);
-    appendOptional(form, "labels", request.labels ? JSON.stringify(request.labels) : undefined);
+    if (request.tags !== undefined) {
+        for (const tag of request.tags)
+            form.append("tags", tag);
+    }
     appendOptional(form, "primary_category_code", request.primaryCategoryCode);
     appendOptional(form, "visibility", request.visibility);
     appendOptional(form, "language_code", request.languageCode);
@@ -1717,6 +1748,11 @@ function voiceEditForm(request) {
     }
     return form;
 }
+function stripHiddenVoiceFields(voice) {
+    const result = { ...voice };
+    delete result.labels;
+    return result;
+}
 function appendNullable(form, key, value) {
     if (value === undefined)
         return;

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { VoiceAccent, VoiceAge, VoiceGender, VoiceTone } from "./voice-metadata.js";
+import type { VoiceAccent, VoiceAge, VoiceGender, VoiceLanguageCode, VoiceTone } from "./voice-metadata.js";
 export type JsonObject = Record<string, unknown>;
 export type BreezeBlueFetch = typeof fetch;
 export interface BreezeBlueClientOptions {
@@ -303,14 +303,15 @@ export interface Voice {
     name: string;
     origin: string;
     voiceType: string;
-    labels: Record<string, string>;
+    tags: string[];
+    isFavorited: boolean;
     previewUrl?: string | null;
     settings: Required<VoiceSettings>;
     description?: string | null;
     createdAtUnix?: number | null;
     primaryCategoryCode?: string | null;
     visibility?: string | null;
-    languageCode: string;
+    languageCode: VoiceLanguageCode;
     gender: VoiceGender | null;
     age: VoiceAge | null;
     tone: VoiceTone[];
@@ -321,12 +322,14 @@ export interface SavedVoice {
     voiceId: string;
     name: string;
     origin: string;
+    tags: string[];
+    isFavorited: boolean;
     previewUrl?: string | null;
     description?: string | null;
     createdAtUnix?: number | null;
     primaryCategoryCode?: string | null;
     visibility?: string | null;
-    languageCode: string;
+    languageCode: VoiceLanguageCode;
     gender: VoiceGender | null;
     age: VoiceAge | null;
     tone: VoiceTone[];
@@ -340,9 +343,17 @@ export interface VoiceList {
     page: number;
     pageSize: number;
 }
+export interface VoiceMetadataOptions {
+    languageCodes: VoiceLanguageCode[];
+    genderCodes: VoiceGender[];
+    ageCodes: VoiceAge[];
+    toneCodes: VoiceTone[];
+    toneMaxItems: number;
+    accentCodesByLanguage: Record<VoiceLanguageCode, VoiceAccent[]>;
+}
 export interface VoiceSearchParams {
     search?: string;
-    languageCode?: string;
+    languageCode?: VoiceLanguageCode;
     origin?: "designed" | "cloned" | string;
     voiceType?: "all" | "default" | "personal" | string;
     sort?: "created_at_unix" | "name" | string;
@@ -350,6 +361,8 @@ export interface VoiceSearchParams {
     nextPageToken?: string;
     page?: number;
     pageSize?: number;
+    favoritesOnly?: boolean;
+    tags?: string[];
 }
 export interface GenericStatus {
     status: string;
@@ -365,8 +378,8 @@ export interface VoiceClonePreviewRequest {
     file?: UploadData | UploadFile;
     files?: Array<UploadData | UploadFile>;
     description?: string;
-    labels?: Record<string, string>;
     removeBackgroundNoise?: boolean;
+    languageCode?: VoiceLanguageCode;
     text?: string;
     instructions?: string;
 }
@@ -377,10 +390,10 @@ export interface VoiceClonePreview {
 export interface VoiceEditRequest {
     name?: string;
     description?: string;
-    labels?: Record<string, string>;
+    tags?: string[];
     primaryCategoryCode?: string;
     visibility?: "private" | "public" | string;
-    languageCode?: string;
+    languageCode?: VoiceLanguageCode;
     gender?: VoiceGender | null;
     age?: VoiceAge | null;
     tone?: VoiceTone[];
@@ -392,7 +405,7 @@ export interface VoiceDesignRequest {
     voiceDescription: string;
     text?: string;
     modelId?: string;
-    languageCode?: string;
+    languageCode?: VoiceLanguageCode;
     autoGenerateText?: boolean;
     loudness?: number;
     quality?: number;
@@ -414,11 +427,11 @@ export interface SaveVoiceRequest {
     generatedVoiceId: string;
     voiceName: string;
     voiceDescription?: string | null;
-    labels?: Record<string, string>;
+    tags?: string[];
     primaryCategoryCode?: string;
     visibility?: "private" | "public" | string;
     playedNotSelectedVoiceIds?: string[];
-    languageCode?: string;
+    languageCode: VoiceLanguageCode;
     gender?: VoiceGender | null;
     age?: VoiceAge | null;
     tone?: VoiceTone[];

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist/voice-metadata.d.ts

@@ -1,6 +1,8 @@
 export declare const VOICE_GENDER_CODES: readonly ["male", "female", "neutral"];
 export declare const VOICE_AGE_CODES: readonly ["child", "young", "middle_aged", "old"];
 export declare const VOICE_TONE_CODES: readonly ["warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate"];
+export declare const VOICE_LANGUAGE_CODES: readonly ["ar", "cs", "de", "el", "en", "es", "fi", "fr", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ro", "ru", "th", "tr", "uk", "vi", "zh"];
+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"];
@@ -8,4 +10,5 @@ export declare const VOICE_ACCENT_CODES_BY_LANGUAGE: {
 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];

package/dist/voice-metadata.js

@@ -2,6 +2,8 @@
 export const VOICE_GENDER_CODES = ["male", "female", "neutral"];
 export const VOICE_AGE_CODES = ["child", "young", "middle_aged", "old"];
 export const VOICE_TONE_CODES = ["warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate"];
+export const VOICE_LANGUAGE_CODES = ["ar", "cs", "de", "el", "en", "es", "fi", "fr", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ro", "ru", "th", "tr", "uk", "vi", "zh"];
+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"],

package/package.json

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