@startsimpli/llm 0.4.29 → 0.4.31

package/src/speech/interface.ts

@@ -1,5 +1,5 @@
 import type { Selectable } from '../providers/registry';
-import type { TranscribeRequest, TranscriptResult } from './types';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult } from './types';
 
 /**
  * What a speech vendor implements. A provider supports whichever directions its
@@ -8,12 +8,11 @@ import type { TranscribeRequest, TranscriptResult } from './types';
  *
  * ADDING A VENDOR: implement this, then
  * `registerSpeechProvider('name', () => new Mine(process.env.MINE_KEY) )` — no
- * edit to `SpeechService`. Text-to-speech joins here as an optional
- * `synthesize` alongside `transcribe` (bd startsim-2lnyg); nothing in the
- * service needs to change for it either.
+ * edit to `SpeechService`. Each direction is an optional method gated by
+ * `capabilities`.
  */
 export interface ISpeechProvider extends Selectable {
-  readonly capabilities: { transcribe: boolean };
+  readonly capabilities: { transcribe: boolean; synthesize?: boolean };
   readonly defaultModel: string;
   /**
    * List price per audio minute, USD, for `model` (default model when omitted).
@@ -21,5 +20,8 @@ export interface ISpeechProvider extends Selectable {
    * that does not state a price is tried after every provider that does.
    */
   costPerMinuteUsd?(model?: string): number;
+  /** List price per 1,000 synthesized characters, USD. `synthesize` prefers the cheapest. */
+  costPer1kCharsUsd?(model?: string): number;
   transcribe?(request: TranscribeRequest): Promise<TranscriptResult>;
+  synthesize?(request: SynthesizeRequest): Promise<SynthesizeResult>;
 }

package/src/speech/providers/elevenlabs-models.ts

@@ -0,0 +1,34 @@
+/**
+ * What ElevenLabs' models can do and cost. Data, not logic: a new model is a
+ * row here. USD per 1,000 characters, elevenlabs.io/pricing/api.
+ */
+const RATE_PER_1K_CHARS: Record<string, number> = {
+  eleven_v3: 0.08,
+  eleven_multilingual_v2: 0.08,
+  eleven_flash_v2_5: 0.04,
+  eleven_v4_turbo: 0.04,
+};
+/** Rate for a model not in the table: the top published tier, so spend is never under-reported. */
+const DEFAULT_RATE_PER_1K_CHARS = 0.10;
+
+/** Models that read `[excited]`-style audio tags; the rest would speak them aloud. */
+const AUDIO_TAG_MODELS = new Set(['eleven_v3', 'eleven_v4', 'eleven_v4_turbo', 'eleven_v3_conversational']);
+
+export const DEFAULT_TTS_MODEL = 'eleven_multilingual_v2';
+
+export function supportsAudioTags(model: string): boolean {
+  return AUDIO_TAG_MODELS.has(model);
+}
+
+export function costUsd(model: string, characters: number): number {
+  return ((RATE_PER_1K_CHARS[model] ?? DEFAULT_RATE_PER_1K_CHARS) * characters) / 1000;
+}
+
+export const DEFAULT_OUTPUT_FORMAT = 'mp3_44100_128';
+
+/** Output formats are `<codec>_<rate>[_<bitrate>]`. */
+export function mimeForFormat(format: string): string {
+  const codec = format.split('_')[0];
+  return ({ mp3: 'audio/mpeg', pcm: 'audio/pcm', ulaw: 'audio/basic', alaw: 'audio/alaw', opus: 'audio/ogg' } as Record<string, string>)[codec]
+    ?? 'application/octet-stream';
+}

package/src/speech/providers/elevenlabs-tts.ts

@@ -0,0 +1,88 @@
+/**
+ * ElevenLabs text-to-speech with timestamps. Split from the provider so the
+ * request/response mapping reads on its own.
+ * https://elevenlabs.io/docs/api-reference/text-to-speech/convert-with-timestamps
+ */
+import { wordsFromCharacters } from '../alignment';
+import { LLMProviderError } from '../../errors';
+import { assertText, speechFetch } from '../http';
+import type { AlignedCharacter, SynthesizeRequest, SynthesizeResult } from '../types';
+import {
+  DEFAULT_OUTPUT_FORMAT, DEFAULT_TTS_MODEL, costUsd, mimeForFormat, supportsAudioTags,
+} from './elevenlabs-models';
+
+interface Alignment {
+  characters?: string[];
+  character_start_times_seconds?: number[];
+  character_end_times_seconds?: number[];
+}
+
+export interface TtsContext {
+  provider: string;
+  apiKey: string;
+  baseUrl: string;
+  defaultVoiceId?: string;
+  fetchImpl?: typeof fetch;
+}
+
+/** Text as sent: style tags go in front, but only on models that read them. */
+export function spokenText(request: SynthesizeRequest, model: string): string {
+  const tags = supportsAudioTags(model) ? (request.style?.tags ?? []) : [];
+  return tags.map((t) => `[${t.replace(/^\[|\]$/g, '')}]`).join('') + (tags.length ? ' ' : '') + request.text;
+}
+
+function voiceSettings(request: SynthesizeRequest): Record<string, number | boolean> | undefined {
+  const { speed, stability } = request.style ?? {};
+  const merged = {
+    ...(speed !== undefined ? { speed } : {}),
+    ...(stability !== undefined ? { stability } : {}),
+    ...request.voiceSettings,
+  };
+  return Object.keys(merged).length ? merged : undefined;
+}
+
+export async function elevenLabsSynthesize(ctx: TtsContext, request: SynthesizeRequest): Promise<SynthesizeResult> {
+  assertText(request, ctx.provider);
+  const voiceId = request.voiceId ?? ctx.defaultVoiceId;
+  if (!voiceId) {
+    throw new LLMProviderError('No voice: pass voiceId or set ELEVENLABS_VOICE_ID.', 'INVALID_REQUEST', false, undefined, ctx.provider);
+  }
+  const model = request.model ?? DEFAULT_TTS_MODEL;
+  const format = request.outputFormat ?? DEFAULT_OUTPUT_FORMAT;
+  const text = spokenText(request, model);
+  const settings = voiceSettings(request);
+
+  const response = await speechFetch(
+    ctx.provider,
+    `${ctx.baseUrl}/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps?output_format=${encodeURIComponent(format)}`,
+    {
+      method: 'POST',
+      headers: { 'xi-api-key': ctx.apiKey, 'content-type': 'application/json' },
+      body: JSON.stringify({
+        text, model_id: model,
+        ...(request.language ? { language_code: request.language } : {}),
+        ...(settings ? { voice_settings: settings } : {}),
+      }),
+    },
+    request.timeoutMs, ctx.fetchImpl, 'synthesis',
+  );
+  const json = (await response.json()) as { audio_base64?: string; alignment?: Alignment | null };
+  const audio = new Uint8Array(Buffer.from(json.audio_base64 ?? '', 'base64'));
+  const characters = alignedCharacters(json.alignment);
+  const words = characters ? wordsFromCharacters(characters, { keepTags: request.keepTags }) : undefined;
+  return {
+    audio, mimeType: mimeForFormat(format),
+    ...(characters ? { characters, durationSec: characters[characters.length - 1].end } : {}),
+    ...(words ? { words } : {}),
+    voiceId, model, provider: ctx.provider,
+    usage: { characters: text.length, costUsd: costUsd(model, text.length) },
+  };
+}
+
+function alignedCharacters(a?: Alignment | null): AlignedCharacter[] | undefined {
+  const chars = a?.characters;
+  const starts = a?.character_start_times_seconds;
+  const ends = a?.character_end_times_seconds;
+  if (!chars?.length || !starts || !ends) return undefined;
+  return chars.map((text, i) => ({ text, start: starts[i], end: ends[i] }));
+}

package/src/speech/providers/elevenlabs.ts

@@ -1,10 +1,12 @@
 /**
- * ElevenLabs Scribe speech-to-text. https://elevenlabs.io/docs/api-reference/speech-to-text
- * Env: ELEVENLABS_API_KEY.
+ * ElevenLabs Scribe speech-to-text and text-to-speech. https://elevenlabs.io/docs/api-reference/speech-to-text
+ * Env: ELEVENLABS_API_KEY; ELEVENLABS_VOICE_ID is the default voice.
  */
 import type { ISpeechProvider } from '../interface';
 import { assertAudio, audioBlob, speechFetch } from '../http';
-import type { TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+import { elevenLabsSynthesize } from './elevenlabs-tts';
+import { DEFAULT_TTS_MODEL, costUsd } from './elevenlabs-models';
 
 export interface ElevenLabsOptions {
   /**
@@ -14,6 +16,8 @@ export interface ElevenLabsOptions {
    */
   sendKeyterms?: boolean;
   apiKey?: string;
+  /** Voice used when a call names none. */
+  voiceId?: string;
   baseUrl?: string;
   fetchImpl?: typeof fetch;
 }
@@ -22,10 +26,11 @@ interface ScribeWord { text: string; start?: number; end?: number; type?: string
 
 export class ElevenLabsSpeechProvider implements ISpeechProvider {
   readonly name = 'elevenlabs';
-  readonly capabilities = { transcribe: true };
+  readonly capabilities = { transcribe: true, synthesize: true };
   readonly defaultModel = 'scribe_v1';
   private readonly apiKey: string;
   private readonly baseUrl: string;
+  private readonly voiceId?: string;
   private readonly fetchImpl?: typeof fetch;
   private readonly sendKeyterms: boolean;
 
@@ -33,6 +38,7 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
     this.sendKeyterms = options.sendKeyterms ?? false;
     this.apiKey = options.apiKey ?? '';
     this.baseUrl = (options.baseUrl ?? 'https://api.elevenlabs.io').replace(/\/+$/, '');
+    this.voiceId = options.voiceId;
     this.fetchImpl = options.fetchImpl;
   }
 
@@ -45,6 +51,18 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
     return 0.22 / 60;
   }
 
+  /** Cheapest TTS tier per 1,000 characters (eleven_flash_v2_5). */
+  costPer1kCharsUsd(model?: string): number {
+    return costUsd(model ?? DEFAULT_TTS_MODEL, 1000);
+  }
+
+  synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    return elevenLabsSynthesize(
+      { provider: this.name, apiKey: this.apiKey, baseUrl: this.baseUrl, defaultVoiceId: this.voiceId, fetchImpl: this.fetchImpl },
+      request,
+    );
+  }
+
   async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
     assertAudio(request, this.name);
     const model = request.model ?? this.defaultModel;
@@ -81,5 +99,5 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
 export function createElevenLabsSpeechProvider(
   env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {},
 ): ElevenLabsSpeechProvider | null {
-  return env.ELEVENLABS_API_KEY ? new ElevenLabsSpeechProvider({ apiKey: env.ELEVENLABS_API_KEY }) : null;
+  return env.ELEVENLABS_API_KEY ? new ElevenLabsSpeechProvider({ apiKey: env.ELEVENLABS_API_KEY, voiceId: env.ELEVENLABS_VOICE_ID || undefined }) : null;
 }

package/src/speech/providers/mock.ts

@@ -1,6 +1,8 @@
 import { LLMProviderError } from '../../errors';
 import type { ISpeechProvider } from '../interface';
-import type { TranscribeRequest, TranscriptResult } from '../types';
+import { wordsFromCharacters } from '../alignment';
+import { assertText } from '../http';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult } from '../types';
 
 export interface MockSpeechBehavior {
   text?: string;
@@ -24,15 +26,33 @@ export function resetMockSpeechBehavior() {
 /** Deterministic transcription for tests — selected with `SPEECH_PROVIDER=mock`. */
 export class MockSpeechProvider implements ISpeechProvider {
   readonly name = 'mock';
-  readonly capabilities = { transcribe: true };
+  readonly capabilities = { transcribe: true, synthesize: true };
   readonly defaultModel = 'mock-transcribe';
   isAvailable() { return true; }
-  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+  private maybeFail() {
     if (behavior.authError) throw new LLMProviderError('mock auth failure', 'AUTHENTICATION_ERROR', false, 401, this.name);
     if (remainingFailures > 0) {
       remainingFailures -= 1;
       throw new LLMProviderError('mock outage', 'SERVICE_UNAVAILABLE', true, 503, this.name);
     }
+  }
+
+  /** Fake audio (one byte per character) with 50ms-per-character alignment. */
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    assertText(request, this.name);
+    this.maybeFail();
+    const characters = [...request.text].map((text, i) => ({ text, start: Math.round(i * 50) / 1000, end: Math.round((i + 1) * 50) / 1000 }));
+    return {
+      audio: new Uint8Array(characters.length).fill(1), mimeType: 'audio/mpeg',
+      characters, words: wordsFromCharacters(characters, { keepTags: request.keepTags }),
+      durationSec: characters[characters.length - 1].end,
+      voiceId: request.voiceId ?? 'mock-voice', model: 'mock-synthesize', provider: this.name,
+      usage: { characters: request.text.length, costUsd: 0 },
+    };
+  }
+
+  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+    this.maybeFail();
     return {
       text: behavior.text ?? `mock transcript of ${request.audio.byteLength} bytes`,
       model: this.defaultModel, provider: this.name, usage: { audioSeconds: 1 },

package/src/speech/providers/openai.ts

@@ -9,8 +9,8 @@
  * URL, default model, word-timing model and price table.
  */
 import type { ISpeechProvider } from '../interface';
-import { assertAudio, audioBlob, speechFetch } from '../http';
-import type { TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+import { assertAudio, assertText, audioBlob, speechFetch } from '../http';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
 
 export interface OpenAISpeechOptions {
   apiKey?: string;
@@ -34,7 +34,7 @@ const OPENAI_PRICES: Record<string, number> = {
 
 export class OpenAISpeechProvider implements ISpeechProvider {
   readonly name: string;
-  readonly capabilities = { transcribe: true };
+  readonly capabilities = { transcribe: true, synthesize: true };
   readonly defaultModel: string;
   private readonly apiKey: string;
   private readonly baseUrl: string;
@@ -62,6 +62,37 @@ export class OpenAISpeechProvider implements ISpeechProvider {
     return this.prices[model ?? this.defaultModel] ?? this.fallbackPrice;
   }
 
+  /** TTS list price per 1,000 characters (tts-1 $15/M; gpt-4o-mini-tts bills about the same per spoken minute). */
+  costPer1kCharsUsd(): number {
+    return 0.015;
+  }
+
+  /** `/v1/audio/speech`. OpenAI returns bare audio: no alignment, so no word timings. */
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    assertText(request, this.name);
+    const model = request.model ?? 'gpt-4o-mini-tts';
+    const voice = request.voiceId ?? 'alloy';
+    const format = request.outputFormat ?? 'mp3';
+    const response = await speechFetch(
+      this.name, `${this.baseUrl}/v1/audio/speech`,
+      {
+        method: 'POST',
+        headers: { authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          model, voice, input: request.text, response_format: format,
+          ...(request.style?.speed !== undefined ? { speed: request.style.speed } : {}),
+        }),
+      },
+      request.timeoutMs, this.fetchImpl, 'synthesis',
+    );
+    const mimeType = ({ mp3: 'audio/mpeg', wav: 'audio/wav', opus: 'audio/ogg', aac: 'audio/aac', flac: 'audio/flac', pcm: 'audio/pcm' } as Record<string, string>)[format] ?? 'application/octet-stream';
+    return {
+      audio: new Uint8Array(await response.arrayBuffer()), mimeType,
+      voiceId: voice, model, provider: this.name,
+      usage: { characters: request.text.length, costUsd: (request.text.length * this.costPer1kCharsUsd()) / 1000 },
+    };
+  }
+
   async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
     assertAudio(request, this.name);
     const wantWords = request.timestamps === 'word';

package/src/speech/repr.ts

@@ -0,0 +1,14 @@
+/** Python-style repr of a string, null or string list, so messages read the same as the Python code's (shared goldens compare messages). */
+export function repr(value: unknown): string {
+  if (value === null || value === undefined) return 'None';
+  if (Array.isArray(value)) return `[${value.map(repr).join(', ')}]`;
+  const s = String(value);
+  const quote = s.includes("'") && !s.includes('"') ? '"' : "'";
+  const body = s.replace(/\\/g, '\\\\').replace(new RegExp(quote, 'g'), `\\${quote}`).replace(/\n/g, '\\n');
+  return `${quote}${body}${quote}`;
+}
+
+/** Python `str(float)` for a finite number: integers keep their `.0`. */
+export function pyFloat(n: number): string {
+  return Number.isInteger(n) ? `${n}.0` : String(n);
+}

package/src/speech/service.ts

@@ -4,7 +4,11 @@ import type { ISpeechProvider } from './interface';
 import { createElevenLabsSpeechProvider } from './providers/elevenlabs';
 import { MockSpeechProvider } from './providers/mock';
 import { createOpenAISpeechProvider } from './providers/openai';
-import type { SpeechServiceConfig, TranscribeRequest, TranscriptResult } from './types';
+import type {
+  SpeechServiceConfig, SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult,
+} from './types';
+
+type Direction = 'transcribe' | 'synthesize';
 
 /**
  * The speech registry. Built-ins register here; a new vendor is
@@ -48,14 +52,15 @@ export class SpeechService {
     return this.getAvailableProviders().length > 0;
   }
 
-  getAvailableProviders(): string[] {
-    return [...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities.transcribe).map(([n]) => n);
+  getAvailableProviders(direction: Direction = 'transcribe'): string[] {
+    return [...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities[direction]).map(([n]) => n);
   }
 
   /** Providers in the order they will be tried: the preferred one (if any), then cheapest first. */
-  private order(): ISpeechProvider[] {
-    const usable = [...this.providers.values()].filter((p) => p.isAvailable() && p.capabilities.transcribe);
-    const price = (p: ISpeechProvider) => p.costPerMinuteUsd?.() ?? Number.POSITIVE_INFINITY;
+  private order(direction: Direction): ISpeechProvider[] {
+    const usable = [...this.providers.values()].filter((p) => p.isAvailable() && p.capabilities[direction]);
+    const price = (p: ISpeechProvider) =>
+      (direction === 'synthesize' ? p.costPer1kCharsUsd?.() : p.costPerMinuteUsd?.()) ?? Number.POSITIVE_INFINITY;
     // Array.sort is stable, so equal/unknown prices keep registration order.
     const byPrice = [...usable].sort((a, b) => price(a) - price(b));
     const wanted = this.config.preferredProvider
@@ -71,18 +76,24 @@ export class SpeechService {
     // (an English note came back in French once). A per-call `language` wins.
     const env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {};
     const request = input.language || !env.SPEECH_LANGUAGE ? input : { ...input, language: env.SPEECH_LANGUAGE };
-    const order = this.order();
-    if (!order.length) {
-      throw new LLMProviderError(
-        'No speech providers available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
-        'AUTHENTICATION_ERROR', false,
-      );
-    }
+    return this.run('transcribe', 'No speech providers available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
+      (provider) => provider.transcribe!(request));
+  }
+
+  /** Text to speech, with the same retry, backoff and fallback as `transcribe`. */
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    return this.run('synthesize', 'No text-to-speech provider available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
+      (provider) => provider.synthesize!(request));
+  }
+
+  private async run<T>(direction: Direction, none: string, call: (provider: ISpeechProvider) => Promise<T>): Promise<T> {
+    const order = this.order(direction);
+    if (!order.length) throw new LLMProviderError(none, 'AUTHENTICATION_ERROR', false);
     let last: unknown;
     for (const provider of order) {
       for (let attempt = 0; ; attempt += 1) {
         try {
-          return await provider.transcribe!(request);
+          return await call(provider);
         } catch (error) {
           last = error;
           const typed = error instanceof LLMProviderError ? error : null;

package/src/speech/types.ts

@@ -14,8 +14,10 @@ export interface TranscriptWord {
 export interface SpeechUsage {
   /** Billable input, when the provider reports it; else derived from word timings. */
   audioSeconds?: number;
-  /** Characters synthesized (TTS). */
+  /** Characters synthesized (TTS), as billed: tags included. */
   characters?: number;
+  /** Cost at the vendor's list rate, when the provider knows it. */
+  costUsd?: number;
 }
 
 export interface TranscribeRequest {
@@ -47,6 +49,58 @@ export interface TranscriptResult {
   usage: SpeechUsage;
 }
 
+/** One aligned unit (a character) with its time span, in seconds from the start of the audio. */
+export interface AlignedCharacter {
+  text: string;
+  start: number;
+  end: number;
+}
+
+/**
+ * Per-call delivery. Providers apply what their model supports and ignore the
+ * rest — a caller never needs to know which model reads which knob.
+ */
+export interface SpeechStyle {
+  /** Audio tags (`excited`, `whispers`), written as `[tag]` ahead of the text on models that read them. */
+  tags?: string[];
+  speed?: number;
+  /** Lower is more expressive. */
+  stability?: number;
+}
+
+export interface SynthesizeRequest {
+  text: string;
+  /** Provider voice id. Omit to use the provider's configured default (ELEVENLABS_VOICE_ID). */
+  voiceId?: string;
+  /** Provider-specific model override. */
+  model?: string;
+  /** ISO-639 hint. */
+  language?: string;
+  /** Vendor output format (`mp3_44100_128`, `pcm_22050`). Default: mp3. */
+  outputFormat?: string;
+  style?: SpeechStyle;
+  /** Raw vendor voice settings; wins over `style` where both set a key. */
+  voiceSettings?: Record<string, number | boolean>;
+  /** Keep `[tag]` markup in the returned words. Default false: tags are delivery, not speech. */
+  keepTags?: boolean;
+  timeoutMs?: number;
+}
+
+export interface SynthesizeResult {
+  audio: Uint8Array;
+  mimeType: string;
+  /** Per-character timings, exactly as the vendor aligned the text it was sent. Absent when the vendor gives none. */
+  characters?: AlignedCharacter[];
+  /** Word timings derived from `characters`; audio tags removed unless `keepTags`. */
+  words?: TranscriptWord[];
+  /** End of the last aligned character; absent without alignment. */
+  durationSec?: number;
+  voiceId?: string;
+  model: string;
+  provider: string;
+  usage: SpeechUsage;
+}
+
 export interface SpeechServiceConfig {
   /** Provider tried first. Default: `SPEECH_PROVIDER`, else the cheapest vendor with a key. */
   preferredProvider?: string;

package/src/speech/voices/cast-voices.json

@@ -0,0 +1,127 @@
+{
+  "version": 1,
+  "about": "Cast voice config: a library of ElevenLabs voices keyed by neutral voice id (never by avatar: a show maps its avatars to these, or to a raw voice id, in its cast), with model and settings, and how timeline emotions steer them. Data only: no keys. Edit this file (or point voice.cast_voices at another) to change a voice, a model or a mapping; nothing here is read from code.",
+  "default_model": "eleven_v3",
+  "models": {
+    "eleven_v3": {"tags": true, "usd_per_1k_chars": 0.08, "price_source": "elevenlabs.io/pricing/api 2026-11-02"},
+    "eleven_v4": {"tags": true, "usd_per_1k_chars": 0.08, "price_source": "assumed equal to v3: v4 is not on the pricing page"},
+    "eleven_v4_turbo": {"tags": true, "usd_per_1k_chars": 0.04, "price_source": "elevenlabs.io/pricing/api 2026-11-02"},
+    "eleven_v3_conversational": {"tags": true, "usd_per_1k_chars": 0.08, "price_source": "assumed equal to v3"},
+    "eleven_multilingual_v2": {"tags": false, "usd_per_1k_chars": 0.08, "price_source": "elevenlabs.io/pricing/api 2026-11-02"},
+    "eleven_flash_v2_5": {"tags": false, "usd_per_1k_chars": 0.04, "price_source": "elevenlabs.io/pricing/api 2026-11-02"}
+  },
+  "tag_pattern": "\\[[^\\[\\]]{1,40}\\]",
+  "voice_id_pattern": "^[A-Za-z0-9]{20}$",
+  "settings_limits": {
+    "stability": [0.0, 1.0], "similarity_boost": [0.0, 1.0], "style": [0.0, 1.0], "speed": [0.7, 1.2]
+  },
+  "emotion_mode_default": "tags",
+  "emotion_map": {
+    "about": "tag: audio tag prepended to the spoken text on tag-capable models (never shown in captions). settings_delta: added to the role's settings on models that take no tags (or on all models when tag_models_use_delta is true). An emotion not listed here falls back to neutral.",
+    "tag_models_use_delta": false,
+    "emotions": {
+      "neutral": {"tag": null, "settings_delta": {}},
+      "excited": {"tag": "[excited]", "settings_delta": {"stability": -0.1, "style": 0.2, "speed": 0.04}},
+      "skeptical": {"tag": "[skeptical]", "settings_delta": {"style": 0.1, "speed": -0.03}},
+      "explaining": {"tag": "[calm]", "settings_delta": {"stability": 0.05, "speed": -0.02}},
+      "thinking": {"tag": "[thoughtful]", "settings_delta": {"stability": 0.05, "speed": -0.06}}
+    }
+  },
+  "languages_about": "Per language: the model the library voices speak it with, the Rhubarb recognizer for the lip-sync cues, and optional voice ids per NEUTRAL role id (roles.<role>.voice_id, never an avatar); a role with no row keeps its own voice on the language's model. The default language is the unchanged path. A language not listed here fails loudly. Models and languages: elevenlabs.io/docs (eleven_multilingual_v2 speaks these). The shared speech CLI takes no language field on synthesize: the model infers it from the text. Rhubarb's default recognizer is English-only; `phonetic` follows the sounds of any language.",
+  "languages": {
+    "en": {"default": true},
+    "es": {"model": "eleven_multilingual_v2", "rhubarb_recognizer": "phonetic", "roles": {}},
+    "fr": {"model": "eleven_multilingual_v2", "rhubarb_recognizer": "phonetic", "roles": {}},
+    "de": {"model": "eleven_multilingual_v2", "rhubarb_recognizer": "phonetic", "roles": {}},
+    "it": {"model": "eleven_multilingual_v2", "rhubarb_recognizer": "phonetic", "roles": {}},
+    "pt": {"model": "eleven_multilingual_v2", "rhubarb_recognizer": "phonetic", "roles": {}},
+    "ja": {"model": "eleven_multilingual_v2", "rhubarb_recognizer": "phonetic", "roles": {}}
+  },
+  "default_pool": ["presenter", "engineer", "manager", "ai_assistant", "customer"],
+  "roles": {
+    "presenter": {
+      "name": "Mira - Bright & Friendly Narrator", "voice_id": "rdEyNni8e60Jlx1RsV9N", "kind": "library",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 0.35},
+        "eleven_multilingual_v2": {"stability": 0.35, "similarity_boost": 0.75, "style": 0.5, "speed": 1.0}
+      },
+      "stand_in_for": "anim/out/voices 01/02 (Jessica, a Default voice that dies 2026-12-31): same bright upbeat host"
+    },
+    "engineer": {
+      "name": "Baxter - Dry Calm Aussie", "voice_id": "jSuBIjxMKhqIfb0wCK1F", "kind": "professional",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 0.5},
+        "eleven_multilingual_v2": {"stability": 0.5, "similarity_boost": 0.8, "style": 0.2, "speed": 1.0}
+      },
+      "stand_in_for": "anim/out/voices 03 (Charlie, a Default voice): casual dry Aussie engineer"
+    },
+    "manager": {
+      "name": "Wyatt - Seasoned Mentor", "voice_id": "FrS6cKLB1wg4WYgPa9GW", "kind": "professional",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 0.5},
+        "eleven_multilingual_v2": {"stability": 0.6, "similarity_boost": 0.8, "style": 0.3, "speed": 0.92}
+      },
+      "stand_in_for": "anim/out/voices 04/05 (Bill, George: Default voices): older, slow, grey-hair-and-tie"
+    },
+    "ai_assistant": {
+      "name": "CI - Narrator (neutral)", "voice_id": "xB7U4iivDiPcO06WZ47T", "kind": "library",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 1.0},
+        "eleven_multilingual_v2": {"stability": 1.0, "similarity_boost": 0.9, "style": 0.0, "speed": 1.1}
+      },
+      "stand_in_for": "anim/out/voices 06/07 (River, Daniel: Default voices): flat even machine tone",
+      "emotion_map": {"about": "the assistant stays even: no emotion steering", "emotions": {}}
+    },
+    "customer": {
+      "name": "Callum - Husky Trickster (library copy)", "voice_id": "5OSluWlAJntR1KG2pWaB", "kind": "professional",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 0.0},
+        "eleven_multilingual_v2": {"stability": 0.35, "similarity_boost": 0.75, "style": 0.4, "speed": 1.0}
+      },
+      "stand_in_for": "anim/out/voices 08/09 (Callum, the Default-voice copy): husky trickster, most character of the set"
+    },
+    "clone_1": {
+      "name": "Instant voice clone 1", "voice_id": "WBpAa2ue6cyOek99incw", "kind": "clone",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 0.5},
+        "eleven_multilingual_v2": {"stability": 0.5, "similarity_boost": 0.85, "style": 0.2, "speed": 1.0}
+      },
+      "stand_in_for": "an instant clone of the 2:27 host recording (bspike-448.15.59); a show or cast member selects it with voice: clone_1"
+    },
+    "santa": {
+      "name": "Mr. Claus - The Classic Jolly Santa", "voice_id": "uDsPstFWFBUXjIBimV7s", "kind": "library",
+      "model": "eleven_v3",
+      "settings": {
+        "eleven_v3": {"stability": 0.4},
+        "eleven_multilingual_v2": {"stability": 0.4, "similarity_boost": 0.8, "style": 0.5, "speed": 0.95}
+      },
+      "stand_in_for": "Santa Claus in the holiday video: a deep, warm, playful stock voice with a hearty laugh (ElevenLabs shared library; the shared-voices search for 'santa', picked 2026-11-04)"
+    },
+    "open_slot_1": {
+      "voice_id": null, "kind": "unfilled", "model": "eleven_v3", "settings": {},
+      "fill": "INPUT bspike-448.15.22.10: pick or design this voice (the sidekick's). Set voice_id and settings.<model> here."
+    }
+  },
+  "retired_voice_ids": {
+    "21m00Tcm4TlvDq8ikWAM": "Rachel: dead on the v1 pool (402)",
+    "MF3mGyEYCl7XYWbV9V6O": "Elli: dead on the v1 pool (402)",
+    "TxGEqnHWrfWW9XjX5Xl0": "Josh: dead on the v1 pool (404)",
+    "ErXwobaYiN019PkySvjV": "Antoni: v1 pool, legacy voice"
+  },
+  "expiring_deadline": "2026-12-31",
+  "default_voice_ids_expiring_2026_12_31": {
+    "CwhRBWXzGAHq8TQ4Fs17": "Roger", "EXAVITQu4vr4xnSDxMaL": "Sarah", "FGY2WhTYpPnrIDTdsKH5": "Laura",
+    "IKne3meq5aSn9XLyUdCD": "Charlie", "JBFqnCBsd6RMkjVDRZzb": "George", "N2lVS1w4EtoT3dr4eOWO": "Callum (Default copy)",
+    "SAz9YHcvj6GT2YYXdXww": "River", "SOYHLrjzK2X1ezoPC6cr": "Harry", "TX3LPaxmHKxFdv7VOQHJ": "Liam",
+    "Xb7hH8MSUJpSbSDYk0k2": "Alice", "XrExE9yKIg1WjnnlVkGX": "Matilda", "bIHbv24MWmeRgasZH58o": "Will",
+    "cgSgspJ2msm6clMCkdW9": "Jessica", "cjVigY5qzO86Huf0OWal": "Eric", "hpp4J3VqNfWAUOO0d1Us": "Bella",
+    "iP95p4xoKVk53GoZ742B": "Chris", "nPczCjzI2devNBz1zQrb": "Brian", "onwK4e9ZLuTAKqWW03F9": "Daniel",
+    "pFZP5JQG7iQjIQuC4Bku": "Lily", "pNInz6obpgDQGcFmaJgB": "Adam", "pqHfZKP75CvOlQylNhV4": "Bill"
+  }
+}