@shogo-ai/voice 1.9.13 → 2.4.1

package/dist/{types-W9y6eMj3.d.ts → types-CadjTXNH.d.cts}

@@ -96,11 +96,72 @@ declare function readVoiceSettings(raw: unknown): VoiceSettings;
  */
 
 declare const DEFAULT_ELEVENLABS_BASE_URL = "https://api.elevenlabs.io";
-/** TTS models the convai runtime supports as of 2026-Q2. */
+/**
+ * The one ElevenLabs TTS model table. Everything that needs to know which
+ * models exist, which are realtime/convai-capable and how much text each
+ * accepts reads from here — `resolveConvaiTtsModel*()` below, the hosted
+ * `/api/voice/tts` route, and the docs.
+ *
+ * `maxChars` is ElevenLabs' per-request character cap for the model;
+ * `realtime` marks the subset that a convai agent can run on.
+ */
+interface VoiceTtsModel {
+    id: string;
+    label: string;
+    /** Usable as a convai agent's TTS model (low-latency websocket path). */
+    realtime: boolean;
+    /** Per-request character cap enforced by ElevenLabs. */
+    maxChars: number;
+    /** Listed for back-compat; still callable, but not what new agents get. */
+    deprecated?: boolean;
+}
+declare const VOICE_TTS_MODELS: readonly VoiceTtsModel[];
+/** Every model id we know about, in table order. */
+declare const VOICE_TTS_MODEL_IDS: readonly string[];
+/** Default model for a plain one-shot `textToSpeech()` call. */
+declare const DEFAULT_TTS_MODEL = "eleven_v4";
+/** TTS models a convai agent can run on. */
 declare const CONVAI_SUPPORTED_TTS_MODELS: Set<string>;
-declare const CONVAI_TTS_MODEL_FALLBACK = "eleven_turbo_v2_5";
+declare const CONVAI_TTS_MODEL_FALLBACK = "eleven_v4_turbo";
+/**
+ * Last-resort model for a one-shot {@link ElevenLabsClient.textToSpeech} retry.
+ *
+ * Deliberately *not* {@link CONVAI_TTS_MODEL_FALLBACK}: a BYO account on an
+ * older plan can have neither v4 model, and the whole point of the retry is to
+ * land on one that is available to everybody. Flash v2.5 is the
+ * widest-available and cheapest of the current models.
+ */
+declare const TTS_FALLBACK_MODEL = "eleven_flash_v2_5";
+/** Look up a model's metadata, or `undefined` when the id is unknown. */
+declare function getVoiceTtsModel(modelId: string | null | undefined): VoiceTtsModel | undefined;
+interface ConvaiTtsModelResolution {
+    /** The model the agent will actually be configured with. */
+    modelId: string;
+    /** What the caller asked for (null/undefined when they asked for nothing). */
+    requested: string | null;
+    /** True when a requested model was replaced by {@link CONVAI_TTS_MODEL_FALLBACK}. */
+    downgraded: boolean;
+    /** Why the requested model was rejected (absent when nothing was requested). */
+    reason?: string;
+}
+/**
+ * Resolve a requested convai TTS model, reporting whether we had to
+ * substitute it. `eleven_v4`, `eleven_v3` and any unknown id are not
+ * convai-capable and resolve to {@link CONVAI_TTS_MODEL_FALLBACK}; every
+ * distinct downgrade is logged once so a caller can see it in pod logs
+ * instead of silently getting a different voice model.
+ */
+declare function resolveConvaiTtsModelDetailed(requested: string | null | undefined): ConvaiTtsModelResolution;
 /** If `requested` isn't a convai-compatible TTS model, fall back to the default. */
 declare function resolveConvaiTtsModel(requested: string | null | undefined): string;
+/**
+ * Whether an ElevenLabs TTS failure is plausibly about the model rather than
+ * about the request as a whole: 402 (model not in the plan) always counts,
+ * and 400/403/404/422 count only when the body mentions model / plan /
+ * permission. 401, 429, 5xx and network errors never do — retrying those on
+ * another model only hides the real problem.
+ */
+declare function isModelRelatedTtsFailure(status: number, body: string): boolean;
 interface ElevenLabsClientConfig {
     apiKey: string;
     /** Override for tests or self-hosted proxies. Defaults to the public API. */
@@ -156,11 +217,25 @@ interface PatchAgentParams {
 interface TextToSpeechParams {
     voiceId: string;
     text: string;
+    /** Defaults to {@link DEFAULT_TTS_MODEL} (`eleven_v4`). */
     modelId?: string;
     voiceSettings?: VoiceSettings;
     /** Accept header; defaults to `audio/mpeg`. */
     accept?: string;
 }
+/** Result of {@link ElevenLabsClient.textToSpeech}. */
+interface TextToSpeechResult {
+    audio: ArrayBuffer;
+    /** The model that actually produced the audio. */
+    modelId: string;
+    /** The model the caller asked for (defaulted when they passed none). */
+    requestedModel: string;
+    /** True when `modelId !== requestedModel` because of a model-related error. */
+    fellBack: boolean;
+    /** Why we fell back (upstream status + body snippet). */
+    fallbackReason?: string;
+    contentType: string;
+}
 /** Options for the low-level {@link ElevenLabsClient.request} escape hatch. */
 interface ElevenLabsRequestOptions {
     /** HTTP method, e.g. `'POST'`. */
@@ -204,6 +279,70 @@ interface ComposeMusicParams {
     outputFormat?: string;
 }
 declare const DEFAULT_MUSIC_MODEL = "music_v1";
+/**
+ * ElevenLabs speech-to-speech ("voice changer") models. The multilingual one
+ * is the cross-language default; the English one is cheaper and sharper on
+ * English input.
+ */
+declare const VOICE_STS_MODEL_IDS: readonly string[];
+declare const DEFAULT_STS_MODEL = "eleven_multilingual_sts_v2";
+/** ElevenLabs Scribe speech-to-text models. */
+declare const VOICE_SPEECH_TO_TEXT_MODEL_IDS: readonly string[];
+declare const DEFAULT_SPEECH_TO_TEXT_MODEL = "scribe_v1";
+/** ElevenLabs text-to-sound-effects models. */
+declare const VOICE_SOUND_GENERATION_MODEL_IDS: readonly string[];
+declare const DEFAULT_SOUND_GENERATION_MODEL = "eleven_text_to_sound_v2";
+/** Parameters for {@link ElevenLabsClient.speechToSpeech} (the voice changer). */
+interface SpeechToSpeechParams {
+    /** Target voice. `POST /v1/speech-to-speech/{voiceId}`. */
+    voiceId: string;
+    /** Source audio to convert. */
+    audio: Blob;
+    /** Filename sent in the multipart part; defaults to `audio`. */
+    fileName?: string;
+    /** One of `VOICE_STS_MODEL_IDS`; defaults to `eleven_multilingual_sts_v2`. */
+    modelId?: string;
+    voiceSettings?: VoiceSettings;
+    /** Output container/quality, e.g. `mp3_44100_192`. */
+    outputFormat?: string;
+    /** `pcm_s16le_16` / `other` (mp3) / `ulaw_8000`. */
+    fileFormat?: string;
+    seed?: number;
+    removeBackgroundNoise?: boolean;
+}
+/** Parameters for {@link ElevenLabsClient.soundEffects}. */
+interface SoundEffectsParams {
+    text: string;
+    /** 0.5–30 s. */
+    durationSeconds?: number;
+    /** 0–1; how literally the prompt is followed. */
+    promptInfluence?: number;
+    loop?: boolean;
+    /** Defaults to `eleven_text_to_sound_v2`. */
+    modelId?: string;
+    outputFormat?: string;
+}
+/** Parameters for {@link ElevenLabsClient.transcribe} (Scribe speech-to-text). */
+interface TranscribeParams {
+    file: Blob;
+    /** Filename sent in the multipart part; defaults to `audio`. */
+    fileName?: string;
+    /** Defaults to `scribe_v1`. */
+    modelId?: string;
+    /** ISO-639-1/3 code; omit to auto-detect. */
+    languageCode?: string;
+    diarize?: boolean;
+    tagAudioEvents?: boolean;
+    numSpeakers?: number;
+}
+/** A Scribe transcription. Extra provider fields are passed through as-is. */
+interface TranscriptionResult {
+    text: string;
+    language_code?: string;
+    language_probability?: number;
+    words?: unknown[];
+    [key: string]: unknown;
+}
 /**
  * An error thrown when ElevenLabs returns a non-2xx response. Preserves the
  * status and response body so callers can decide how to surface it.
@@ -231,15 +370,17 @@ declare class ElevenLabsClient {
     /** Fetch a short-lived signed URL the browser can use to start a session. */
     getSignedUrl(agentId: string): Promise<string>;
     /**
-     * One-shot TTS. Returns the raw audio bytes plus the model id that was
-     * actually used (some models aren't available for every account, so we
-     * fall back to `eleven_turbo_v2_5` on the first failure).
+     * One-shot TTS. Returns the raw audio bytes plus the model that actually
+     * produced them.
+     *
+     * The requested model is never swapped silently: we only retry on
+     * {@link TTS_FALLBACK_MODEL} when the failure is plausibly about
+     * the model (400/403/404/422 whose body mentions model/plan/permission,
+     * or 402 for an out-of-plan model). Auth (401), rate limit (429), 5xx and
+     * network errors are surfaced as-is. When a fallback does happen the
+     * result reports `requestedModel`, `fellBack` and `fallbackReason`.
      */
-    textToSpeech(params: TextToSpeechParams): Promise<{
-        audio: ArrayBuffer;
-        modelId: string;
-        contentType: string;
-    }>;
+    textToSpeech(params: TextToSpeechParams): Promise<TextToSpeechResult>;
     /**
      * Low-level escape hatch for any ElevenLabs endpoint not covered by a
      * dedicated method (music, sound-generation, speech-to-text, dubbing,
@@ -276,6 +417,45 @@ declare class ElevenLabsClient {
         audio: ArrayBuffer;
         contentType: string;
     }>;
+    /**
+     * Convert speech to speech — the "voice changer": keep the performance,
+     * swap the voice. `POST /v1/speech-to-speech/{voiceId}` with a multipart
+     * audio part. Returns the converted audio bytes.
+     *
+     * @example
+     * ```ts
+     * const { audio } = await el.speechToSpeech({
+     *   voiceId: '21m00Tcm4TlvDq8ikWAM',
+     *   audio: await fetch(myRecording).then((r) => r.blob()),
+     *   modelId: 'eleven_multilingual_sts_v2',
+     * })
+     * ```
+     */
+    speechToSpeech(params: SpeechToSpeechParams): Promise<{
+        audio: ArrayBuffer;
+        contentType: string;
+    }>;
+    /**
+     * Generate a sound effect from a text prompt. `POST /v1/sound-generation`.
+     *
+     * @example
+     * ```ts
+     * const { audio } = await el.soundEffects({ text: 'heavy wooden door creaking' })
+     * ```
+     */
+    soundEffects(params: SoundEffectsParams): Promise<{
+        audio: ArrayBuffer;
+        contentType: string;
+    }>;
+    /**
+     * Transcribe audio with Scribe. `POST /v1/speech-to-text` (multipart).
+     *
+     * @example
+     * ```ts
+     * const { text } = await el.transcribe({ file: recording })
+     * ```
+     */
+    transcribe(params: TranscribeParams): Promise<TranscriptionResult>;
     /** Probe whether a given voice id still exists on the caller's account. */
     voiceExists(voiceId: string): Promise<boolean>;
     /**
@@ -420,7 +600,8 @@ interface CreateCompanionBody {
 type PatchCompanionBody = Partial<CreateCompanionBody>;
 /** Shape of the JSON body for `POST /voice/tts-preview`. */
 interface TtsPreviewBody {
-    voiceId: string;
+    /** ElevenLabs voice id. Optional in proxy mode (the project's voice wins). */
+    voiceId?: string;
     text?: string;
     audioTags?: string[];
     modelId?: string;
@@ -428,4 +609,4 @@ interface TtsPreviewBody {
     characterName?: string;
 }
 
-export { AUDIO_TAGS as A, composeExpressivityBlock as B, CONVAI_SUPPORTED_TTS_MODELS as C, DEFAULT_ALLOWED_TAGS as D, type Expressivity as E, normalizeAudioTags as F, normalizeExpressivity as G, normalizeVoiceSettings as H, readAudioTags as I, readExpressivity as J, readVoiceSettings as K, resolveConvaiTtsModel as L, MEMORY_CLIENT_TOOLS as M, stripAudioTags as N, stripExpressivityBlock as O, type PatchAgentParams as P, type TextToSpeechParams as T, type VoiceMemoryStore as V, AUDIO_TAG_GROUPS as a, type AudioTag as b, type AudioTagGroup as c, CONVAI_TTS_MODEL_FALLBACK as d, type Companion as e, type CompanionStore as f, type ComposeMusicParams as g, type ConvaiClientTool as h, type CreateAgentParams as i, type CreateCompanionBody as j, DEFAULT_ELEVENLABS_BASE_URL as k, DEFAULT_MUSIC_MODEL as l, DEFAULT_VOICE_SETTINGS as m, EXPRESSIVITY_BLOCK_CLOSE as n, EXPRESSIVITY_BLOCK_OPEN as o, EXPRESSIVITY_OPTIONS as p, ElevenLabsApiError as q, ElevenLabsClient as r, type ElevenLabsClientConfig as s, type ElevenLabsRequestOptions as t, type ElevenLabsResponse as u, type PatchCompanionBody as v, type TtsPreviewBody as w, type VoiceSettings as x, type VoiceUser as y, buildPreviewLine as z };
+export { isModelRelatedTtsFailure as $, AUDIO_TAGS as A, type ElevenLabsResponse as B, type CompanionStore as C, DEFAULT_ALLOWED_TAGS as D, ElevenLabsClient as E, type PatchCompanionBody as F, type SpeechToSpeechParams as G, type TextToSpeechParams as H, type TextToSpeechResult as I, type TranscribeParams as J, type TranscriptionResult as K, type TtsPreviewBody as L, MEMORY_CLIENT_TOOLS as M, VOICE_SOUND_GENERATION_MODEL_IDS as N, VOICE_SPEECH_TO_TEXT_MODEL_IDS as O, type PatchAgentParams as P, VOICE_STS_MODEL_IDS as Q, VOICE_TTS_MODELS as R, type SoundEffectsParams as S, TTS_FALLBACK_MODEL as T, VOICE_TTS_MODEL_IDS as U, type VoiceUser as V, type VoiceSettings as W, type VoiceTtsModel as X, buildPreviewLine as Y, composeExpressivityBlock as Z, getVoiceTtsModel as _, type VoiceMemoryStore as a, normalizeAudioTags as a0, normalizeExpressivity as a1, normalizeVoiceSettings as a2, readAudioTags as a3, readExpressivity as a4, readVoiceSettings as a5, resolveConvaiTtsModel as a6, resolveConvaiTtsModelDetailed as a7, stripAudioTags as a8, stripExpressivityBlock as a9, type Expressivity as b, AUDIO_TAG_GROUPS as c, type AudioTag as d, type AudioTagGroup as e, CONVAI_SUPPORTED_TTS_MODELS as f, CONVAI_TTS_MODEL_FALLBACK as g, type Companion as h, type ComposeMusicParams as i, type ConvaiClientTool as j, type ConvaiTtsModelResolution as k, type CreateAgentParams as l, type CreateCompanionBody as m, DEFAULT_ELEVENLABS_BASE_URL as n, DEFAULT_MUSIC_MODEL as o, DEFAULT_SOUND_GENERATION_MODEL as p, DEFAULT_SPEECH_TO_TEXT_MODEL as q, DEFAULT_STS_MODEL as r, DEFAULT_TTS_MODEL as s, DEFAULT_VOICE_SETTINGS as t, EXPRESSIVITY_BLOCK_CLOSE as u, EXPRESSIVITY_BLOCK_OPEN as v, EXPRESSIVITY_OPTIONS as w, ElevenLabsApiError as x, type ElevenLabsClientConfig as y, type ElevenLabsRequestOptions as z };

package/dist/{types-W9y6eMj3.d.cts → types-CadjTXNH.d.ts}

@@ -96,11 +96,72 @@ declare function readVoiceSettings(raw: unknown): VoiceSettings;
  */
 
 declare const DEFAULT_ELEVENLABS_BASE_URL = "https://api.elevenlabs.io";
-/** TTS models the convai runtime supports as of 2026-Q2. */
+/**
+ * The one ElevenLabs TTS model table. Everything that needs to know which
+ * models exist, which are realtime/convai-capable and how much text each
+ * accepts reads from here — `resolveConvaiTtsModel*()` below, the hosted
+ * `/api/voice/tts` route, and the docs.
+ *
+ * `maxChars` is ElevenLabs' per-request character cap for the model;
+ * `realtime` marks the subset that a convai agent can run on.
+ */
+interface VoiceTtsModel {
+    id: string;
+    label: string;
+    /** Usable as a convai agent's TTS model (low-latency websocket path). */
+    realtime: boolean;
+    /** Per-request character cap enforced by ElevenLabs. */
+    maxChars: number;
+    /** Listed for back-compat; still callable, but not what new agents get. */
+    deprecated?: boolean;
+}
+declare const VOICE_TTS_MODELS: readonly VoiceTtsModel[];
+/** Every model id we know about, in table order. */
+declare const VOICE_TTS_MODEL_IDS: readonly string[];
+/** Default model for a plain one-shot `textToSpeech()` call. */
+declare const DEFAULT_TTS_MODEL = "eleven_v4";
+/** TTS models a convai agent can run on. */
 declare const CONVAI_SUPPORTED_TTS_MODELS: Set<string>;
-declare const CONVAI_TTS_MODEL_FALLBACK = "eleven_turbo_v2_5";
+declare const CONVAI_TTS_MODEL_FALLBACK = "eleven_v4_turbo";
+/**
+ * Last-resort model for a one-shot {@link ElevenLabsClient.textToSpeech} retry.
+ *
+ * Deliberately *not* {@link CONVAI_TTS_MODEL_FALLBACK}: a BYO account on an
+ * older plan can have neither v4 model, and the whole point of the retry is to
+ * land on one that is available to everybody. Flash v2.5 is the
+ * widest-available and cheapest of the current models.
+ */
+declare const TTS_FALLBACK_MODEL = "eleven_flash_v2_5";
+/** Look up a model's metadata, or `undefined` when the id is unknown. */
+declare function getVoiceTtsModel(modelId: string | null | undefined): VoiceTtsModel | undefined;
+interface ConvaiTtsModelResolution {
+    /** The model the agent will actually be configured with. */
+    modelId: string;
+    /** What the caller asked for (null/undefined when they asked for nothing). */
+    requested: string | null;
+    /** True when a requested model was replaced by {@link CONVAI_TTS_MODEL_FALLBACK}. */
+    downgraded: boolean;
+    /** Why the requested model was rejected (absent when nothing was requested). */
+    reason?: string;
+}
+/**
+ * Resolve a requested convai TTS model, reporting whether we had to
+ * substitute it. `eleven_v4`, `eleven_v3` and any unknown id are not
+ * convai-capable and resolve to {@link CONVAI_TTS_MODEL_FALLBACK}; every
+ * distinct downgrade is logged once so a caller can see it in pod logs
+ * instead of silently getting a different voice model.
+ */
+declare function resolveConvaiTtsModelDetailed(requested: string | null | undefined): ConvaiTtsModelResolution;
 /** If `requested` isn't a convai-compatible TTS model, fall back to the default. */
 declare function resolveConvaiTtsModel(requested: string | null | undefined): string;
+/**
+ * Whether an ElevenLabs TTS failure is plausibly about the model rather than
+ * about the request as a whole: 402 (model not in the plan) always counts,
+ * and 400/403/404/422 count only when the body mentions model / plan /
+ * permission. 401, 429, 5xx and network errors never do — retrying those on
+ * another model only hides the real problem.
+ */
+declare function isModelRelatedTtsFailure(status: number, body: string): boolean;
 interface ElevenLabsClientConfig {
     apiKey: string;
     /** Override for tests or self-hosted proxies. Defaults to the public API. */
@@ -156,11 +217,25 @@ interface PatchAgentParams {
 interface TextToSpeechParams {
     voiceId: string;
     text: string;
+    /** Defaults to {@link DEFAULT_TTS_MODEL} (`eleven_v4`). */
     modelId?: string;
     voiceSettings?: VoiceSettings;
     /** Accept header; defaults to `audio/mpeg`. */
     accept?: string;
 }
+/** Result of {@link ElevenLabsClient.textToSpeech}. */
+interface TextToSpeechResult {
+    audio: ArrayBuffer;
+    /** The model that actually produced the audio. */
+    modelId: string;
+    /** The model the caller asked for (defaulted when they passed none). */
+    requestedModel: string;
+    /** True when `modelId !== requestedModel` because of a model-related error. */
+    fellBack: boolean;
+    /** Why we fell back (upstream status + body snippet). */
+    fallbackReason?: string;
+    contentType: string;
+}
 /** Options for the low-level {@link ElevenLabsClient.request} escape hatch. */
 interface ElevenLabsRequestOptions {
     /** HTTP method, e.g. `'POST'`. */
@@ -204,6 +279,70 @@ interface ComposeMusicParams {
     outputFormat?: string;
 }
 declare const DEFAULT_MUSIC_MODEL = "music_v1";
+/**
+ * ElevenLabs speech-to-speech ("voice changer") models. The multilingual one
+ * is the cross-language default; the English one is cheaper and sharper on
+ * English input.
+ */
+declare const VOICE_STS_MODEL_IDS: readonly string[];
+declare const DEFAULT_STS_MODEL = "eleven_multilingual_sts_v2";
+/** ElevenLabs Scribe speech-to-text models. */
+declare const VOICE_SPEECH_TO_TEXT_MODEL_IDS: readonly string[];
+declare const DEFAULT_SPEECH_TO_TEXT_MODEL = "scribe_v1";
+/** ElevenLabs text-to-sound-effects models. */
+declare const VOICE_SOUND_GENERATION_MODEL_IDS: readonly string[];
+declare const DEFAULT_SOUND_GENERATION_MODEL = "eleven_text_to_sound_v2";
+/** Parameters for {@link ElevenLabsClient.speechToSpeech} (the voice changer). */
+interface SpeechToSpeechParams {
+    /** Target voice. `POST /v1/speech-to-speech/{voiceId}`. */
+    voiceId: string;
+    /** Source audio to convert. */
+    audio: Blob;
+    /** Filename sent in the multipart part; defaults to `audio`. */
+    fileName?: string;
+    /** One of `VOICE_STS_MODEL_IDS`; defaults to `eleven_multilingual_sts_v2`. */
+    modelId?: string;
+    voiceSettings?: VoiceSettings;
+    /** Output container/quality, e.g. `mp3_44100_192`. */
+    outputFormat?: string;
+    /** `pcm_s16le_16` / `other` (mp3) / `ulaw_8000`. */
+    fileFormat?: string;
+    seed?: number;
+    removeBackgroundNoise?: boolean;
+}
+/** Parameters for {@link ElevenLabsClient.soundEffects}. */
+interface SoundEffectsParams {
+    text: string;
+    /** 0.5–30 s. */
+    durationSeconds?: number;
+    /** 0–1; how literally the prompt is followed. */
+    promptInfluence?: number;
+    loop?: boolean;
+    /** Defaults to `eleven_text_to_sound_v2`. */
+    modelId?: string;
+    outputFormat?: string;
+}
+/** Parameters for {@link ElevenLabsClient.transcribe} (Scribe speech-to-text). */
+interface TranscribeParams {
+    file: Blob;
+    /** Filename sent in the multipart part; defaults to `audio`. */
+    fileName?: string;
+    /** Defaults to `scribe_v1`. */
+    modelId?: string;
+    /** ISO-639-1/3 code; omit to auto-detect. */
+    languageCode?: string;
+    diarize?: boolean;
+    tagAudioEvents?: boolean;
+    numSpeakers?: number;
+}
+/** A Scribe transcription. Extra provider fields are passed through as-is. */
+interface TranscriptionResult {
+    text: string;
+    language_code?: string;
+    language_probability?: number;
+    words?: unknown[];
+    [key: string]: unknown;
+}
 /**
  * An error thrown when ElevenLabs returns a non-2xx response. Preserves the
  * status and response body so callers can decide how to surface it.
@@ -231,15 +370,17 @@ declare class ElevenLabsClient {
     /** Fetch a short-lived signed URL the browser can use to start a session. */
     getSignedUrl(agentId: string): Promise<string>;
     /**
-     * One-shot TTS. Returns the raw audio bytes plus the model id that was
-     * actually used (some models aren't available for every account, so we
-     * fall back to `eleven_turbo_v2_5` on the first failure).
+     * One-shot TTS. Returns the raw audio bytes plus the model that actually
+     * produced them.
+     *
+     * The requested model is never swapped silently: we only retry on
+     * {@link TTS_FALLBACK_MODEL} when the failure is plausibly about
+     * the model (400/403/404/422 whose body mentions model/plan/permission,
+     * or 402 for an out-of-plan model). Auth (401), rate limit (429), 5xx and
+     * network errors are surfaced as-is. When a fallback does happen the
+     * result reports `requestedModel`, `fellBack` and `fallbackReason`.
      */
-    textToSpeech(params: TextToSpeechParams): Promise<{
-        audio: ArrayBuffer;
-        modelId: string;
-        contentType: string;
-    }>;
+    textToSpeech(params: TextToSpeechParams): Promise<TextToSpeechResult>;
     /**
      * Low-level escape hatch for any ElevenLabs endpoint not covered by a
      * dedicated method (music, sound-generation, speech-to-text, dubbing,
@@ -276,6 +417,45 @@ declare class ElevenLabsClient {
         audio: ArrayBuffer;
         contentType: string;
     }>;
+    /**
+     * Convert speech to speech — the "voice changer": keep the performance,
+     * swap the voice. `POST /v1/speech-to-speech/{voiceId}` with a multipart
+     * audio part. Returns the converted audio bytes.
+     *
+     * @example
+     * ```ts
+     * const { audio } = await el.speechToSpeech({
+     *   voiceId: '21m00Tcm4TlvDq8ikWAM',
+     *   audio: await fetch(myRecording).then((r) => r.blob()),
+     *   modelId: 'eleven_multilingual_sts_v2',
+     * })
+     * ```
+     */
+    speechToSpeech(params: SpeechToSpeechParams): Promise<{
+        audio: ArrayBuffer;
+        contentType: string;
+    }>;
+    /**
+     * Generate a sound effect from a text prompt. `POST /v1/sound-generation`.
+     *
+     * @example
+     * ```ts
+     * const { audio } = await el.soundEffects({ text: 'heavy wooden door creaking' })
+     * ```
+     */
+    soundEffects(params: SoundEffectsParams): Promise<{
+        audio: ArrayBuffer;
+        contentType: string;
+    }>;
+    /**
+     * Transcribe audio with Scribe. `POST /v1/speech-to-text` (multipart).
+     *
+     * @example
+     * ```ts
+     * const { text } = await el.transcribe({ file: recording })
+     * ```
+     */
+    transcribe(params: TranscribeParams): Promise<TranscriptionResult>;
     /** Probe whether a given voice id still exists on the caller's account. */
     voiceExists(voiceId: string): Promise<boolean>;
     /**
@@ -420,7 +600,8 @@ interface CreateCompanionBody {
 type PatchCompanionBody = Partial<CreateCompanionBody>;
 /** Shape of the JSON body for `POST /voice/tts-preview`. */
 interface TtsPreviewBody {
-    voiceId: string;
+    /** ElevenLabs voice id. Optional in proxy mode (the project's voice wins). */
+    voiceId?: string;
     text?: string;
     audioTags?: string[];
     modelId?: string;
@@ -428,4 +609,4 @@ interface TtsPreviewBody {
     characterName?: string;
 }
 
-export { AUDIO_TAGS as A, composeExpressivityBlock as B, CONVAI_SUPPORTED_TTS_MODELS as C, DEFAULT_ALLOWED_TAGS as D, type Expressivity as E, normalizeAudioTags as F, normalizeExpressivity as G, normalizeVoiceSettings as H, readAudioTags as I, readExpressivity as J, readVoiceSettings as K, resolveConvaiTtsModel as L, MEMORY_CLIENT_TOOLS as M, stripAudioTags as N, stripExpressivityBlock as O, type PatchAgentParams as P, type TextToSpeechParams as T, type VoiceMemoryStore as V, AUDIO_TAG_GROUPS as a, type AudioTag as b, type AudioTagGroup as c, CONVAI_TTS_MODEL_FALLBACK as d, type Companion as e, type CompanionStore as f, type ComposeMusicParams as g, type ConvaiClientTool as h, type CreateAgentParams as i, type CreateCompanionBody as j, DEFAULT_ELEVENLABS_BASE_URL as k, DEFAULT_MUSIC_MODEL as l, DEFAULT_VOICE_SETTINGS as m, EXPRESSIVITY_BLOCK_CLOSE as n, EXPRESSIVITY_BLOCK_OPEN as o, EXPRESSIVITY_OPTIONS as p, ElevenLabsApiError as q, ElevenLabsClient as r, type ElevenLabsClientConfig as s, type ElevenLabsRequestOptions as t, type ElevenLabsResponse as u, type PatchCompanionBody as v, type TtsPreviewBody as w, type VoiceSettings as x, type VoiceUser as y, buildPreviewLine as z };
+export { isModelRelatedTtsFailure as $, AUDIO_TAGS as A, type ElevenLabsResponse as B, type CompanionStore as C, DEFAULT_ALLOWED_TAGS as D, ElevenLabsClient as E, type PatchCompanionBody as F, type SpeechToSpeechParams as G, type TextToSpeechParams as H, type TextToSpeechResult as I, type TranscribeParams as J, type TranscriptionResult as K, type TtsPreviewBody as L, MEMORY_CLIENT_TOOLS as M, VOICE_SOUND_GENERATION_MODEL_IDS as N, VOICE_SPEECH_TO_TEXT_MODEL_IDS as O, type PatchAgentParams as P, VOICE_STS_MODEL_IDS as Q, VOICE_TTS_MODELS as R, type SoundEffectsParams as S, TTS_FALLBACK_MODEL as T, VOICE_TTS_MODEL_IDS as U, type VoiceUser as V, type VoiceSettings as W, type VoiceTtsModel as X, buildPreviewLine as Y, composeExpressivityBlock as Z, getVoiceTtsModel as _, type VoiceMemoryStore as a, normalizeAudioTags as a0, normalizeExpressivity as a1, normalizeVoiceSettings as a2, readAudioTags as a3, readExpressivity as a4, readVoiceSettings as a5, resolveConvaiTtsModel as a6, resolveConvaiTtsModelDetailed as a7, stripAudioTags as a8, stripExpressivityBlock as a9, type Expressivity as b, AUDIO_TAG_GROUPS as c, type AudioTag as d, type AudioTagGroup as e, CONVAI_SUPPORTED_TTS_MODELS as f, CONVAI_TTS_MODEL_FALLBACK as g, type Companion as h, type ComposeMusicParams as i, type ConvaiClientTool as j, type ConvaiTtsModelResolution as k, type CreateAgentParams as l, type CreateCompanionBody as m, DEFAULT_ELEVENLABS_BASE_URL as n, DEFAULT_MUSIC_MODEL as o, DEFAULT_SOUND_GENERATION_MODEL as p, DEFAULT_SPEECH_TO_TEXT_MODEL as q, DEFAULT_STS_MODEL as r, DEFAULT_TTS_MODEL as s, DEFAULT_VOICE_SETTINGS as t, EXPRESSIVITY_BLOCK_CLOSE as u, EXPRESSIVITY_BLOCK_OPEN as v, EXPRESSIVITY_OPTIONS as w, ElevenLabsApiError as x, type ElevenLabsClientConfig as y, type ElevenLabsRequestOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shogo-ai/voice",
-  "version": "1.9.13",
+  "version": "2.4.1",
   "description": "Shogo Voice — ElevenLabs/Twilio voice agent infrastructure with React + React Native UI primitives.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./live": {
+      "types": "./dist/live/client.d.ts",
+      "import": "./dist/live/client.js",
+      "require": "./dist/live/client.cjs"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js",
@@ -24,6 +29,16 @@
       "import": "./dist/react/index.js",
       "require": "./dist/react/index.cjs"
     },
+    "./react/conversation": {
+      "types": "./dist/react/conversation.d.ts",
+      "import": "./dist/react/conversation.js",
+      "require": "./dist/react/conversation.cjs"
+    },
+    "./react/visuals": {
+      "types": "./dist/react/visuals.d.ts",
+      "import": "./dist/react/visuals.js",
+      "require": "./dist/react/visuals.cjs"
+    },
     "./native": {
       "types": "./dist/native/index.d.ts",
       "import": "./dist/native/index.js",
@@ -58,6 +73,11 @@
       "types": "./dist/route/audio-tags.d.ts",
       "import": "./dist/route/audio-tags.js",
       "require": "./dist/route/audio-tags.cjs"
+    },
+    "./route/op": {
+      "types": "./dist/route/op.d.ts",
+      "import": "./dist/route/op.js",
+      "require": "./dist/route/op.cjs"
     }
   },
   "files": [