@kuralle-syrinx/elevenlabs 4.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,82 @@
+# @kuralle-syrinx/elevenlabs
+
+ElevenLabs voice provider for Syrinx — multi-context WebSocket streaming TTS and Scribe v2
+Realtime streaming STT.
+
+## Install
+
+```bash
+pnpm add @kuralle-syrinx/elevenlabs
+```
+
+## Auth
+
+Pass `api_key` (and `voice_id` for TTS) in plugin config. For local smokes, set `ELEVENLABS_API_KEY`
+in the repo-root `.env` (the live smoke reads `EL_VOICE_ID` for the TTS voice, defaulting to a
+free-accessible premade voice).
+
+## Streaming TTS — `ElevenLabsTTSPlugin`
+
+```typescript
+import { ElevenLabsTTSPlugin } from "@kuralle-syrinx/elevenlabs";
+import { createNodeWsSocket } from "@kuralle-syrinx/ws/node";
+
+const tts = new ElevenLabsTTSPlugin(createNodeWsSocket);
+await tts.initialize(bus, {
+  api_key: process.env.ELEVENLABS_API_KEY!,
+  voice_id: process.env.ELEVENLABS_VOICE_ID,
+  model_id: "eleven_flash_v2_5",
+  sample_rate: 16000,
+});
+```
+
+Connects to `wss://api.elevenlabs.io/v1/text-to-speech/<voice_id>/multi-stream-input`
+(`multi-stream-input`, concurrent contexts keyed by `context_id`) via the shared `tts-core`
+deep module. Sends the required `InitializeConnectionMulti`-style context-init frame
+(`voice_settings` + optional `generation_config`) before a context's first text. `output_format`
+and `generation_config` are dev-configurable, not pinned. Default voice
+(`EXAVITQu4vr4xnSDxMaL`) is a premade voice accessible to free API accounts — library voices
+(e.g. Rachel) require a paid plan; override with `voice_id`.
+
+Usage billing (`usage.recorded{stage:"tts", characters}`) fires on **audio received**, once per
+context — not on `isFinal` (ElevenLabs streams audio with `isFinal:null`, and a rejected
+generation returns an empty final that must not be billed).
+
+## Streaming STT — `ElevenLabsSTTPlugin`
+
+```typescript
+import { ElevenLabsSTTPlugin } from "@kuralle-syrinx/elevenlabs";
+import { createNodeWsSocket } from "@kuralle-syrinx/ws/node";
+
+const stt = new ElevenLabsSTTPlugin(createNodeWsSocket);
+await stt.initialize(bus, {
+  api_key: process.env.ELEVENLABS_API_KEY!,
+  sample_rate: 16000,
+});
+```
+
+Connects to `wss://api.elevenlabs.io/v1/speech-to-text/realtime` (Scribe v2 Realtime, model
+`scribe_v2_realtime` by default) via the shared `@kuralle-syrinx/stt-core` session. Provider
+`partial_transcript` → `stt.interim`, `committed_transcript` → `stt.result` (`speechFinal: true`).
+Usage billing (`usage.recorded{stage:"stt", audioSeconds}`) fires at the final-transcript funnel
+with delta-billing. Owns endpointing (`endpointingCapability.owner: "provider_stt"`).
+
+## Pricing
+
+Cited in `@kuralle-syrinx/core`'s `DEFAULT_PRICE_CATALOG`: Scribe v2 STT $0.39/hr;
+Flash/Turbo TTS $50/1M characters, Multilingual TTS $100/1M characters.
+
+## Status
+
+Live-verified end-to-end (TTS audio + usage, STT transcript + usage).
+
+## Live smoke
+
+From `examples/02-hello-voice-headless` (requires `ELEVENLABS_API_KEY`; optional `EL_VOICE_ID`):
+
+```bash
+pnpm -C examples/02-hello-voice-headless exec tsx scripts/spike-elevenlabs.ts
+```
+
+Exercises both TTS (multi-context WS) and STT (Scribe v2 realtime WS) against the live API,
+including `usage.recorded` on both stages.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kuralle-syrinx/elevenlabs",
+  "version": "4.3.0",
+  "private": false,
+  "description": "ElevenLabs adapters for Syrinx — multi-context WebSocket TTS and Scribe v2 Realtime STT",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "elevenlabs",
+    "speech-to-text",
+    "text-to-speech"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/elevenlabs"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./stt": "./src/stt.ts",
+    "./tts": "./src/tts.ts"
+  },
+  "dependencies": {
+    "@kuralle-syrinx/core": "4.3.0",
+    "@kuralle-syrinx/stt-core": "4.3.0",
+    "@kuralle-syrinx/tts-core": "4.3.0",
+    "@kuralle-syrinx/ws": "4.3.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.6",
+    "ws": "^8.21.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+
+export { ElevenLabsTTSPlugin, ElevenLabsWireProtocol } from "./tts.js";
+export { ElevenLabsSTTPlugin } from "./stt.js";

package/src/stt.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: MIT
+//
+// ElevenLabs Scribe v2 Realtime STT.
+// Wire protocol pinned from:
+//   https://elevenlabs.io/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime
+// Session lifecycle lives in @kuralle-syrinx/stt-core.
+
+import {
+  assertAudioFormat,
+  optionalStringConfig,
+  readProviderRetryConfig,
+  requireStringConfig,
+  type AudioFormat,
+  type PipelineBus,
+  type PluginConfig,
+  type VoicePlugin,
+} from "@kuralle-syrinx/core";
+import {
+  defaultNodeSocketFactory,
+  startStreamingSttSession,
+  type SttEvent,
+  type SttWireProtocol,
+  type StreamingSttSession,
+} from "@kuralle-syrinx/stt-core";
+import type { SocketData, SocketFactory } from "@kuralle-syrinx/ws";
+
+const DEFAULT_MODEL_ID = "scribe_v2_realtime";
+const DEFAULT_ENDPOINT = "wss://api.elevenlabs.io/v1/speech-to-text/realtime";
+
+class ElevenLabsSttWireProtocol implements SttWireProtocol {
+  constructor(
+    private readonly sampleRate: number,
+    private readonly commitStrategy: "manual" | "vad",
+    private readonly language: string,
+  ) {}
+
+  isReady(): boolean {
+    // Session is usable as soon as the socket is up; session_started is informative.
+    return true;
+  }
+
+  encodeAudio(audio: Uint8Array): readonly SocketData[] {
+    return [
+      JSON.stringify({
+        message_type: "input_audio_chunk",
+        audio_base_64: Buffer.from(audio).toString("base64"),
+        commit: false,
+        sample_rate: this.sampleRate,
+      }),
+    ];
+  }
+
+  encodeFinalize(_contextId: string): readonly SocketData[] {
+    if (this.commitStrategy !== "manual") return [];
+    return [
+      JSON.stringify({
+        message_type: "input_audio_chunk",
+        audio_base_64: "",
+        commit: true,
+        sample_rate: this.sampleRate,
+      }),
+    ];
+  }
+
+  decode(data: SocketData, _isBinary: boolean): readonly SttEvent[] {
+    if (typeof data !== "string") return [];
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(data) as Record<string, unknown>;
+    } catch (err) {
+      return [
+        {
+          type: "error",
+          error: new Error(
+            `ElevenLabs STT provider sent malformed JSON: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+        },
+      ];
+    }
+
+    const messageType = typeof msg["message_type"] === "string" ? msg["message_type"] : "";
+    switch (messageType) {
+      case "session_started":
+        return [];
+      case "partial_transcript": {
+        const text = typeof msg["text"] === "string" ? msg["text"].trim() : "";
+        if (!text) return [];
+        return [{ type: "interim", contextId: "", text }];
+      }
+      case "committed_transcript":
+      case "committed_transcript_with_timestamps":
+      case "final_transcript":
+      case "final_transcript_with_timestamps": {
+        const text = typeof msg["text"] === "string" ? msg["text"].trim() : "";
+        if (!text) return [];
+        const language =
+          typeof msg["language_code"] === "string" && msg["language_code"]
+            ? msg["language_code"]
+            : this.language || "en";
+        return [
+          {
+            type: "final",
+            contextId: "",
+            text,
+            confidence: 1,
+            language,
+            speechFinal: true,
+            provider: { words: msg["words"] },
+          },
+        ];
+      }
+      case "error":
+      case "auth_error":
+      case "quota_exceeded":
+      case "commit_throttled":
+      case "unaccepted_terms":
+      case "rate_limited":
+      case "queue_overflow":
+      case "resource_exhausted":
+      case "session_time_limit_exceeded":
+      case "input_error":
+      case "chunk_size_exceeded":
+      case "insufficient_audio_activity":
+      case "transcriber_error":
+        return [{ type: "error", error: elevenLabsSttError(msg, messageType) }];
+      default:
+        return [];
+    }
+  }
+}
+
+export class ElevenLabsSTTPlugin implements VoicePlugin {
+  readonly endpointingCapability = {
+    owner: "provider_stt" as const,
+    disableConfig: {
+      emit_eos_on_final: false,
+    },
+  };
+
+  constructor(private readonly socketFactory?: SocketFactory) {}
+
+  private session: StreamingSttSession | null = null;
+
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    const apiKey = requireStringConfig(config, "api_key");
+    const sampleRate = (config["sample_rate"] as number) ?? 16000;
+    const model =
+      optionalStringConfig(config, "model") ??
+      optionalStringConfig(config, "model_id") ??
+      DEFAULT_MODEL_ID;
+    const language =
+      optionalStringConfig(config, "language") ??
+      optionalStringConfig(config, "language_code") ??
+      "";
+    const endpointUrl = optionalStringConfig(config, "endpoint_url") ?? DEFAULT_ENDPOINT;
+    const strategy = optionalStringConfig(config, "commit_strategy");
+    const commitStrategy: "manual" | "vad" = strategy === "vad" ? "vad" : "manual";
+    const emitEosOnFinal = (config["emit_eos_on_final"] as boolean) ?? true;
+    const audioFormat: AudioFormat = {
+      encoding: "pcm_s16le",
+      sampleRateHz: sampleRate,
+      channels: 1,
+    };
+    assertAudioFormat(audioFormat);
+    const audioFormatParam = pcmAudioFormatParam(sampleRate);
+
+    this.session = await startStreamingSttSession(bus, {
+      protocol: new ElevenLabsSttWireProtocol(sampleRate, commitStrategy, language),
+      provider: { name: "elevenlabs", model, region: "global" },
+      format: audioFormat,
+      language: language || "en",
+      emitEosOnFinal,
+      url: () => {
+        const params = new URLSearchParams({
+          model_id: model,
+          audio_format: audioFormatParam,
+          commit_strategy: commitStrategy,
+        });
+        if (language) params.set("language_code", language);
+        const separator = endpointUrl.includes("?") ? "&" : "?";
+        return `${endpointUrl}${separator}${params.toString()}`;
+      },
+      headers: { "xi-api-key": apiKey },
+      socketFactory: this.socketFactory ?? (await defaultNodeSocketFactory()),
+      retry: readProviderRetryConfig(config),
+      replayBufferSize: (config["replay_buffer_size"] as number) ?? 64,
+      metricPrefix: "stt.elevenlabs",
+    });
+  }
+
+  async close(): Promise<void> {
+    await this.session?.dispose();
+    this.session = null;
+  }
+}
+
+function pcmAudioFormatParam(sampleRate: number): string {
+  switch (sampleRate) {
+    case 8000:
+      return "pcm_8000";
+    case 16000:
+      return "pcm_16000";
+    case 22050:
+      return "pcm_22050";
+    case 24000:
+      return "pcm_24000";
+    case 44100:
+      return "pcm_44100";
+    case 48000:
+      return "pcm_48000";
+    default:
+      return `pcm_${sampleRate}`;
+  }
+}
+
+function elevenLabsSttError(msg: Record<string, unknown>, messageType: string): Error {
+  const detail = typeof msg["error"] === "string" ? msg["error"] : messageType;
+  return new Error(`ElevenLabs STT provider error (${messageType}): ${detail}`);
+}

package/src/tts.ts

@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: MIT
+//
+// ElevenLabs multi-context WebSocket TTS.
+// Wire protocol pinned from:
+//   https://elevenlabs.io/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-multi-stream-input
+// Lifecycle (reconnect/keepalive/finish-timeout) lives in tts-core.
+
+import {
+  Route,
+  assertAudioFormat,
+  assertAudioPayload,
+  optionalStringConfig,
+  readProviderRetryConfig,
+  requireStringConfig,
+  type AudioFormat,
+  type PipelineBus,
+  type PluginConfig,
+  type VoicePlugin,
+} from "@kuralle-syrinx/core";
+import {
+  attributionKey,
+  defaultNodeSocketFactory,
+  startStreamingTtsSession,
+  type AttributionKey,
+  type StreamingTtsSession,
+  type WireEvent,
+  type WireProtocol,
+} from "@kuralle-syrinx/tts-core";
+import type { SocketData, SocketFactory } from "@kuralle-syrinx/ws";
+
+const KEEP_ALIVE_INTERVAL_MS = 10_000;
+// A premade voice in the default set — accessible to free API accounts. (Library voices like
+// Rachel 21m00Tcm4TlvDq8ikWAM require a paid plan: "cannot use library voices via the API".)
+const DEFAULT_VOICE_ID = "EXAVITQu4vr4xnSDxMaL";
+const DEFAULT_MODEL_ID = "eleven_flash_v2_5";
+const DEFAULT_VOICE_SETTINGS: Record<string, unknown> = { stability: 0.5, similarity_boost: 0.75 };
+
+interface ElevenLabsWireConfig {
+  readonly modelId: string;
+  readonly audioFormat: AudioFormat;
+  readonly voiceSettings: Record<string, unknown>;
+  readonly generationConfig?: Record<string, unknown>;
+}
+
+/** Exported for unit tests that exercise encode/decode without a live socket. */
+export class ElevenLabsWireProtocol implements WireProtocol {
+  private readonly charactersByKey = new Map<AttributionKey, number>();
+  private readonly initializedKeys = new Set<AttributionKey>();
+  private readonly billedKeys = new Set<AttributionKey>();
+
+  constructor(private readonly cfg: ElevenLabsWireConfig) {}
+
+  attributionFor(contextId: string): { key: AttributionKey; contextId: string } {
+    return { key: attributionKey(contextId), contextId };
+  }
+
+  encodeText(key: AttributionKey, text: string): SocketData[] {
+    this.charactersByKey.set(key, (this.charactersByKey.get(key) ?? 0) + text.length);
+    const frames: SocketData[] = [];
+    // Multi-stream requires initializing a context (voice_settings) before its first text —
+    // without it ElevenLabs accepts the text but generates NO audio (a final with no audio frames).
+    if (!this.initializedKeys.has(key)) {
+      this.initializedKeys.add(key);
+      const init: Record<string, unknown> = { text: " ", context_id: key, voice_settings: this.cfg.voiceSettings };
+      if (this.cfg.generationConfig) init["generation_config"] = this.cfg.generationConfig;
+      frames.push(JSON.stringify(init));
+    }
+    frames.push(JSON.stringify({ text, context_id: key }));
+    return frames;
+  }
+
+  encodeFinish(contextId: string, _activeKeys: readonly AttributionKey[]): SocketData[] {
+    return [JSON.stringify({ context_id: contextId, flush: true })];
+  }
+
+  encodeCancel(key: AttributionKey, _contextId: string): SocketData[] {
+    this.charactersByKey.delete(key);
+    this.initializedKeys.delete(key);
+    this.billedKeys.delete(key);
+    return [JSON.stringify({ context_id: key, close_context: true })];
+  }
+
+  encodeClose(): SocketData[] {
+    return [JSON.stringify({ close_socket: true })];
+  }
+
+  decode(data: SocketData, _isBinary: boolean): readonly WireEvent[] {
+    if (typeof data !== "string") return [];
+    const msg = JSON.parse(data) as Record<string, unknown>;
+    const contextId = readContextId(msg);
+    const key = attributionKey(contextId || "");
+
+    if (isErrorFrame(msg)) {
+      return [{ type: "error", key: contextId ? key : null, error: elevenLabsProviderError(msg), endsContext: isFinalFlag(msg) }];
+    }
+
+    const events: WireEvent[] = [];
+    const audioB64 = typeof msg["audio"] === "string" ? msg["audio"] : "";
+    if (audioB64.length > 0) {
+      if (!contextId) {
+        events.push({ type: "error", key: null, error: new Error("ElevenLabs TTS audio frame missing context_id") });
+      } else {
+        try {
+          const bytes = new Uint8Array(decodeStrictBase64(audioB64, "ElevenLabs TTS provider audio"));
+          assertAudioPayload(this.cfg.audioFormat, bytes);
+          events.push({ type: "audio", key, pcm: bytes });
+          // Bill on real audio, once per context — NOT on isFinal. EL streams audio with
+          // isFinal:null and may not send a separate isFinal:true final (the socket close is the
+          // real end), and a rejected generation returns an empty final with no audio that must
+          // NOT be billed. Audio-received is the correct "synthesis happened" signal.
+          const characters = this.charactersByKey.get(key) ?? 0;
+          if (!this.billedKeys.has(key) && characters > 0) {
+            this.billedKeys.add(key);
+            const modelId = this.cfg.modelId;
+            events.push({
+              type: "sideband",
+              key,
+              route: Route.Background,
+              build: (ctxId, timestampMs) => ({
+                kind: "usage.recorded",
+                contextId: ctxId,
+                timestampMs,
+                stage: "tts" as const,
+                provider: "elevenlabs",
+                model: modelId,
+                characters,
+              }),
+            });
+          }
+        } catch (err) {
+          events.push({ type: "error", key, error: err instanceof Error ? err : new Error(String(err)) });
+        }
+      }
+    }
+
+    if (isFinalFlag(msg) && contextId) {
+      events.push({ type: "context_end", key });
+      this.charactersByKey.delete(key);
+      this.billedKeys.delete(key);
+      this.initializedKeys.delete(key);
+    }
+    return events;
+  }
+}
+
+export class ElevenLabsTTSPlugin implements VoicePlugin {
+  constructor(private readonly socketFactory?: SocketFactory) {}
+
+  private session: StreamingTtsSession | null = null;
+
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    const apiKey = requireStringConfig(config, "api_key");
+    const voiceId = optionalStringConfig(config, "voice_id") ?? DEFAULT_VOICE_ID;
+    const modelId = optionalStringConfig(config, "model_id") ?? DEFAULT_MODEL_ID;
+    const sampleRate = (config["sample_rate"] as number) ?? 16000;
+    const voiceSettings = (config["voice_settings"] as Record<string, unknown> | undefined) ?? DEFAULT_VOICE_SETTINGS;
+    const languageCode = optionalStringConfig(config, "language_code") ?? optionalStringConfig(config, "language");
+    const baseUrl =
+      optionalStringConfig(config, "endpoint_url") ??
+      `wss://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voiceId)}/multi-stream-input`;
+    const audioFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: sampleRate, channels: 1 };
+    assertAudioFormat(audioFormat);
+    // Derive a sensible default from sample_rate, but let the dev override (mp3, ulaw_8000 for
+    // telephony, etc.) — never hard-pin the provider's own format knob.
+    const outputFormat = optionalStringConfig(config, "output_format") ?? pcmOutputFormat(sampleRate);
+    // Optional provider-specific passthrough for the multi-stream context-init frame.
+    const generationConfig = config["generation_config"] as Record<string, unknown> | undefined;
+
+    this.session = await startStreamingTtsSession(bus, {
+      protocol: new ElevenLabsWireProtocol({ modelId, audioFormat, voiceSettings, generationConfig }),
+      provider: { name: "elevenlabs", model: modelId, region: "global" },
+      format: audioFormat,
+      sampleRateHz: sampleRate,
+      url: () => {
+        const params = new URLSearchParams({
+          model_id: modelId,
+          output_format: outputFormat,
+        });
+        if (languageCode) params.set("language_code", languageCode);
+        const separator = baseUrl.includes("?") ? "&" : "?";
+        return `${baseUrl}${separator}${params.toString()}`;
+      },
+      headers: { "xi-api-key": apiKey },
+      retry: readProviderRetryConfig(config),
+      finishTimeoutMs: readNonNegativeInteger(config["finish_timeout_ms"], 2000),
+      metricPrefix: "tts.elevenlabs",
+      socketFactory: this.socketFactory ?? (await defaultNodeSocketFactory()),
+      replayBufferSize: (config["replay_buffer_size"] as number) ?? 32,
+      keepAliveIntervalMs: KEEP_ALIVE_INTERVAL_MS,
+    });
+  }
+
+  async close(): Promise<void> {
+    await this.session?.dispose();
+    this.session = null;
+  }
+}
+
+function pcmOutputFormat(sampleRate: number): string {
+  switch (sampleRate) {
+    case 8000:
+      return "pcm_8000";
+    case 16000:
+      return "pcm_16000";
+    case 22050:
+      return "pcm_22050";
+    case 24000:
+      return "pcm_24000";
+    case 44100:
+      return "pcm_44100";
+    default:
+      return `pcm_${sampleRate}`;
+  }
+}
+
+function readContextId(msg: Record<string, unknown>): string {
+  if (typeof msg["context_id"] === "string") return msg["context_id"];
+  if (typeof msg["contextId"] === "string") return msg["contextId"];
+  return "";
+}
+
+function isFinalFlag(msg: Record<string, unknown>): boolean {
+  return msg["is_final"] === true || msg["isFinal"] === true;
+}
+
+function isErrorFrame(msg: Record<string, unknown>): boolean {
+  const type = typeof msg["type"] === "string" ? msg["type"].toLowerCase() : "";
+  const messageType = typeof msg["message_type"] === "string" ? msg["message_type"].toLowerCase() : "";
+  return type === "error" || messageType === "error" || typeof msg["error"] === "string";
+}
+
+function elevenLabsProviderError(msg: Record<string, unknown>): Error {
+  const err =
+    typeof msg["error"] === "string"
+      ? msg["error"]
+      : typeof msg["message"] === "string"
+        ? msg["message"]
+        : "ElevenLabs TTS provider error";
+  return new Error(err);
+}
+
+function decodeStrictBase64(value: string, name: string): Buffer {
+  const normalized = value.replace(/\s+/g, "");
+  if (normalized.length === 0 || normalized.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+    throw new Error(`${name} must be valid base64`);
+  }
+  const decoded = Buffer.from(normalized, "base64");
+  if (decoded.toString("base64") !== normalized) {
+    throw new Error(`${name} must be valid base64`);
+  }
+  return decoded;
+}
+
+function readNonNegativeInteger(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const integer = Math.floor(value);
+  return integer >= 0 ? integer : fallback;
+}