@effect-uai/elevenlabs 0.4.0

package/src/codec.ts

@@ -0,0 +1,185 @@
+import { Array as Arr, Effect, Encoding, Match, Option, Result } from "effect"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioFormat, AudioSource } from "@effect-uai/core/Audio"
+
+// ---------------------------------------------------------------------------
+// Shared TTS voice-settings shape (sync + streaming use the same fields)
+// ---------------------------------------------------------------------------
+
+export type VoiceSettings = {
+  readonly stability?: number
+  readonly similarityBoost?: number
+  readonly style?: number
+  readonly useSpeakerBoost?: boolean
+  readonly speed?: number
+}
+
+export const wireVoiceSettings = (v: VoiceSettings | undefined) =>
+  v === undefined
+    ? undefined
+    : {
+        ...(v.stability !== undefined && { stability: v.stability }),
+        ...(v.similarityBoost !== undefined && { similarity_boost: v.similarityBoost }),
+        ...(v.style !== undefined && { style: v.style }),
+        ...(v.useSpeakerBoost !== undefined && { use_speaker_boost: v.useSpeakerBoost }),
+        ...(v.speed !== undefined && { speed: v.speed }),
+      }
+
+// ---------------------------------------------------------------------------
+// AudioFormat → ElevenLabs `output_format` query value
+// ---------------------------------------------------------------------------
+
+/**
+ * ElevenLabs encodes container + sample rate + bitrate in a single
+ * dot-less slug (`mp3_44100_128`, `pcm_16000`, `wav_48000`, `ulaw_8000`,
+ * `opus_48000_128`, etc.). This helper inverts the common cases of our
+ * `AudioFormat` shape into that slug.
+ *
+ * Only the formats that map cleanly are produced. Anything we can't
+ * encode (mismatched bitrate, unsupported sample rate combination)
+ * fails `Unsupported` with the requested format echoed so the user can
+ * fix it.
+ */
+export const formatToOutputSlug: (format: AudioFormat) => Effect.Effect<string, AiError.AiError> = (
+  format,
+) =>
+  Match.value(format).pipe(
+    Match.when({ container: "mp3" }, (f) =>
+      Effect.succeed(`mp3_${f.sampleRate}_${f.bitRate ?? 128}`),
+    ),
+    Match.when({ container: "opus" }, (f) =>
+      Effect.succeed(`opus_${f.sampleRate}_${f.bitRate ?? 128}`),
+    ),
+    Match.when({ container: "wav" }, (f) => Effect.succeed(`wav_${f.sampleRate}`)),
+    Match.when({ container: "raw", encoding: "pcm_s16le" }, (f) =>
+      Effect.succeed(`pcm_${f.sampleRate}`),
+    ),
+    Match.when({ container: "raw", encoding: "pcm_mulaw" }, (f) =>
+      Effect.succeed(`ulaw_${f.sampleRate}`),
+    ),
+    Match.when({ container: "raw", encoding: "pcm_alaw" }, (f) =>
+      Effect.succeed(`alaw_${f.sampleRate}`),
+    ),
+    Match.orElse((f) =>
+      Effect.fail(
+        new AiError.Unsupported({
+          provider: "elevenlabs",
+          capability: "outputFormat",
+          reason: `Cannot encode ${JSON.stringify(f)} as ElevenLabs output_format. Supported: mp3 + (22050|44100), opus 48000, wav 48000, pcm/ulaw/alaw at any sample rate.`,
+        }),
+      ),
+    ),
+  )
+
+/** Default output: 128 kbps MP3 at 44.1 kHz. */
+export const defaultFormat: AudioFormat = {
+  container: "mp3",
+  encoding: "mp3",
+  sampleRate: 44100,
+  bitRate: 128,
+}
+
+// ---------------------------------------------------------------------------
+// AudioSource → Blob (STT multipart upload)
+// ---------------------------------------------------------------------------
+
+const urlNotSupported: AiError.AiError = new AiError.InvalidRequest({
+  provider: "elevenlabs",
+  param: "audio",
+  raw: 'ElevenLabs accepts URLs via the `cloud_storage_url` field, not the `file` field. Fetch the URL yourself and pass `{ _tag: "bytes", bytes, mimeType }` to use the inline path.',
+})
+
+const decodeBase64ToBytes = (b64: string): Effect.Effect<Uint8Array, AiError.AiError> =>
+  Result.match(Encoding.decodeBase64(b64), {
+    onSuccess: Effect.succeed,
+    onFailure: (cause) =>
+      Effect.fail(
+        new AiError.InvalidRequest({ provider: "elevenlabs", param: "audio", raw: cause }),
+      ),
+  })
+
+const bytesToBlob = (bytes: Uint8Array, mimeType: string): Blob =>
+  new Blob([bytes as Uint8Array<ArrayBuffer>], { type: mimeType })
+
+export const audioToBlob: (audio: AudioSource) => Effect.Effect<Blob, AiError.AiError> =
+  Match.type<AudioSource>().pipe(
+    Match.tag("bytes", (a) => Effect.succeed(bytesToBlob(a.bytes, a.mimeType))),
+    Match.tag("base64", (a) =>
+      decodeBase64ToBytes(a.base64).pipe(Effect.map((bytes) => bytesToBlob(bytes, a.mimeType))),
+    ),
+    Match.tag("url", () => Effect.fail(urlNotSupported)),
+    Match.exhaustive,
+  )
+
+// ---------------------------------------------------------------------------
+// MIME → file extension (for the multipart `filename` field)
+// ---------------------------------------------------------------------------
+
+const EXTENSION_BY_MIME: ReadonlyArray<readonly [string, string]> = [
+  ["mpeg", "mp3"],
+  ["mp3", "mp3"],
+  ["wav", "wav"],
+  ["ogg", "ogg"],
+  ["opus", "ogg"],
+  ["flac", "flac"],
+  ["aac", "aac"],
+  ["mp4", "m4a"],
+  ["m4a", "m4a"],
+  ["webm", "webm"],
+]
+
+export const defaultFileName = (mimeType: string): string =>
+  Arr.findFirst(EXTENSION_BY_MIME, ([pattern]) => mimeType.includes(pattern)).pipe(
+    Option.match({
+      onNone: () => "audio",
+      onSome: ([, ext]) => `audio.${ext}`,
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// HTTP errors
+// ---------------------------------------------------------------------------
+
+export const httpStatusError: (status: number, body: string) => AiError.AiError = (status, body) =>
+  Match.value(status).pipe(
+    Match.when(
+      429,
+      (): AiError.AiError => new AiError.RateLimited({ provider: "elevenlabs", raw: body }),
+    ),
+    Match.whenOr(
+      408,
+      504,
+      (): AiError.AiError => new AiError.Timeout({ provider: "elevenlabs", raw: body }),
+    ),
+    Match.when(
+      401,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "elevenlabs", subtype: "auth", raw: body }),
+    ),
+    Match.when(
+      403,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "elevenlabs", subtype: "permission", raw: body }),
+    ),
+    Match.when(
+      402,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "elevenlabs", subtype: "billing", raw: body }),
+    ),
+    Match.when(
+      413,
+      (): AiError.AiError =>
+        new AiError.ContextLengthExceeded({ provider: "elevenlabs", raw: body }),
+    ),
+    Match.when(
+      (n) => n >= 500,
+      (n): AiError.AiError =>
+        new AiError.Unavailable({ provider: "elevenlabs", status: n, raw: body }),
+    ),
+    Match.orElse(
+      (): AiError.AiError => new AiError.InvalidRequest({ provider: "elevenlabs", raw: body }),
+    ),
+  )
+
+export const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "elevenlabs", raw: cause })

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as ElevenLabsSynthesizer from "./ElevenLabsSynthesizer.js"
+export * as ElevenLabsTranscriber from "./ElevenLabsTranscriber.js"
+export * as codec from "./codec.js"
+export * from "./models.js"

package/src/models.ts

@@ -0,0 +1,46 @@
+/**
+ * Known ElevenLabs TTS model identifiers (as of mid-2026). The
+ * `(string & {})` tail keeps autocomplete on the literals while still
+ * accepting any string, so newly-released models work without an SDK
+ * update.
+ *
+ * - `eleven_v3` — most expressive; supports inline audio-tag emotion
+ *   directives (`<laugh>`, `<whisper>`, etc.). 70+ languages.
+ * - `eleven_multilingual_v2` — production-grade multilingual. 29
+ *   languages. Default for the API.
+ * - `eleven_turbo_v2_5` — low latency, 32 languages.
+ * - `eleven_flash_v2_5` — sub-100 ms first-byte, 32 languages.
+ *
+ * Reference: https://elevenlabs.io/docs/overview/models
+ */
+export type ElevenLabsTtsModel =
+  | "eleven_v3"
+  | "eleven_multilingual_v2"
+  | "eleven_turbo_v2_5"
+  | "eleven_flash_v2_5"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/**
+ * Known ElevenLabs STT model identifiers.
+ *
+ * - `scribe_v2` — current generation, recommended.
+ * - `scribe_v1` — legacy.
+ * - `scribe_v2_realtime` — WebSocket streaming variant (Phase 2b).
+ *
+ * Reference: https://elevenlabs.io/docs/api-reference/speech-to-text
+ */
+export type ElevenLabsSttModel =
+  | "scribe_v2"
+  | "scribe_v1"
+  | "scribe_v2_realtime"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/**
+ * ElevenLabs voice IDs are 20-character alphanumeric strings (e.g.
+ * `JBFqnCBsd6RMkjVDRZzb`). Both stock and cloned voices use the same
+ * opaque format, so there's no useful literal narrowing here — the
+ * full catalog is fetched dynamically via `GET /v1/voices`.
+ */
+export type ElevenLabsVoiceId = string

package/src/realtimeStt.ts

@@ -0,0 +1,273 @@
+import { Cause, Effect, Encoding, Match, Queue, Redacted, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as Socket from "effect/unstable/socket/Socket"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioFormat } from "@effect-uai/core/Audio"
+import * as JSONL from "@effect-uai/core/JSONL"
+import type { TranscriptEvent, WordTimestamp } from "@effect-uai/core/Transcript"
+import type { CommonStreamTranscribeRequest } from "@effect-uai/core/Transcriber"
+import { httpStatusError, transportFailure } from "./codec.js"
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+// ---------------------------------------------------------------------------
+// AudioFormat → audio_format slug
+// ---------------------------------------------------------------------------
+
+const unsupportedInputFormat = (format: AudioFormat) =>
+  new AiError.Unsupported({
+    provider: "elevenlabs",
+    capability: "inputFormat",
+    reason: `ElevenLabs realtime STT accepts pcm_<rate> or ulaw_8000 only. Got ${JSON.stringify(format)}.`,
+  })
+
+export const inputFormatToSlug: (format: AudioFormat) => Effect.Effect<string, AiError.AiError> =
+  Match.type<AudioFormat>().pipe(
+    Match.when({ container: "raw", encoding: "pcm_s16le" }, (f) =>
+      Effect.succeed(`pcm_${f.sampleRate}`),
+    ),
+    Match.when({ container: "raw", encoding: "pcm_mulaw", sampleRate: 8000 }, () =>
+      Effect.succeed("ulaw_8000"),
+    ),
+    Match.orElse((f) => Effect.fail(unsupportedInputFormat(f))),
+  )
+
+// ---------------------------------------------------------------------------
+// Single-use token — auth rides on a query param so any
+// `globalThis.WebSocket` works (browser, Node 22+, Bun, Deno).
+// ---------------------------------------------------------------------------
+
+const TokenWire = Schema.Struct({ token: Schema.String })
+const decodeToken = Schema.decodeUnknownEffect(TokenWire)
+
+export const fetchSingleUseToken = (cfg: Config) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const url = `${cfg.baseUrl ?? "https://api.elevenlabs.io/v1"}/single-use-token/realtime_scribe`
+    const httpRequest = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* Effect.fail(httpStatusError(response.status, text))
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    const wire = yield* decodeToken(json).pipe(
+      Effect.mapError(
+        (cause) =>
+          new AiError.GenerationFailed({
+            provider: "elevenlabs",
+            raw: { message: "single-use-token response missing `token` field", cause, json },
+          }),
+      ),
+    )
+    return wire.token
+  })
+
+// ---------------------------------------------------------------------------
+// Wire schemas (server → client)
+// ---------------------------------------------------------------------------
+
+const RealtimeWord = Schema.Struct({
+  text: Schema.String,
+  start: Schema.Number,
+  end: Schema.Number,
+  type: Schema.optional(Schema.String),
+  speaker_id: Schema.optional(Schema.NullOr(Schema.String)),
+  logprob: Schema.optional(Schema.Number),
+})
+
+const ServerMessage = Schema.Union([
+  Schema.Struct({
+    message_type: Schema.Literal("session_started"),
+    session_id: Schema.optional(Schema.String),
+  }),
+  Schema.Struct({
+    message_type: Schema.Literal("partial_transcript"),
+    text: Schema.String,
+  }),
+  Schema.Struct({
+    message_type: Schema.Literal("committed_transcript"),
+    text: Schema.String,
+  }),
+  Schema.Struct({
+    message_type: Schema.Literal("committed_transcript_with_timestamps"),
+    text: Schema.String,
+    language_code: Schema.optional(Schema.NullOr(Schema.String)),
+    words: Schema.optional(Schema.NullOr(Schema.Array(RealtimeWord))),
+  }),
+  Schema.Struct({
+    message_type: Schema.Literals(["error", "auth_error", "rate_limited", "quota_exceeded"]),
+    error: Schema.optional(Schema.Unknown),
+  }),
+])
+const decodeServerMessage = Schema.decodeUnknownEffect(ServerMessage)
+
+const wireToWordTimestamp = (w: typeof RealtimeWord.Type): WordTimestamp => ({
+  text: w.text,
+  startSeconds: w.start,
+  endSeconds: w.end,
+  ...(w.speaker_id != null && { speakerId: w.speaker_id }),
+  ...(w.logprob !== undefined && { confidence: Math.exp(w.logprob) }),
+})
+
+/**
+ * Map a server frame to a `TranscriptEvent`. The two `committed_*` variants
+ * need disambiguation:
+ *
+ *   - When `include_timestamps=true` on the URL, the server emits BOTH
+ *     `committed_transcript` and `committed_transcript_with_timestamps` for
+ *     each segment — same text, the latter is a strict superset. The bare
+ *     variant must be suppressed or callers see two finals per utterance.
+ *   - When `include_timestamps=false`, the server emits ONLY
+ *     `committed_transcript`. Suppressing it loses every final.
+ *
+ * So suppression must be conditional on `includeTimestamps`, which is what
+ * `wordTimestamps` resolves to on the URL.
+ */
+export const wireToEvent =
+  (includeTimestamps: boolean) =>
+  (msg: typeof ServerMessage.Type): TranscriptEvent | undefined =>
+    Match.value(msg).pipe(
+      Match.when({ message_type: "session_started" }, () => undefined),
+      Match.when(
+        { message_type: "partial_transcript" },
+        (m): TranscriptEvent => ({ _tag: "partial", text: m.text }),
+      ),
+      Match.when({ message_type: "committed_transcript" }, (m): TranscriptEvent | undefined =>
+        includeTimestamps
+          ? undefined // superseded by the `_with_timestamps` variant
+          : { _tag: "final", text: m.text },
+      ),
+      Match.when({ message_type: "committed_transcript_with_timestamps" }, (m): TranscriptEvent => {
+        const words = m.words == null ? undefined : m.words.map(wireToWordTimestamp)
+        return {
+          _tag: "final",
+          text: m.text,
+          ...(m.language_code != null && { languageCode: m.language_code }),
+          ...(words !== undefined && words.length > 0 && { words }),
+        }
+      }),
+      Match.orElse(
+        (m): TranscriptEvent => ({
+          _tag: "error",
+          code: m.message_type,
+          message:
+            typeof m.error === "string"
+              ? m.error
+              : JSON.stringify(m.error ?? `ElevenLabs ${m.message_type}`),
+        }),
+      ),
+    )
+
+// ---------------------------------------------------------------------------
+// URL + frame builders
+// ---------------------------------------------------------------------------
+
+export type RealtimeOptions = {
+  readonly model?: string
+  readonly languageCode?: string
+  readonly includeTimestamps?: boolean
+  readonly commitStrategy?: "manual" | "vad"
+}
+
+export const buildWsUrl = (
+  cfg: Config,
+  token: string,
+  audioFormat: string,
+  opts: RealtimeOptions,
+) => {
+  const wsBase = (cfg.baseUrl ?? "https://api.elevenlabs.io/v1").replace(/^http/, "ws")
+  const params = new URLSearchParams({
+    token,
+    audio_format: audioFormat,
+    commit_strategy: opts.commitStrategy ?? "vad",
+    ...(opts.model !== undefined && { model_id: opts.model }),
+    ...(opts.languageCode !== undefined && { language_code: opts.languageCode }),
+    ...(opts.includeTimestamps === true && { include_timestamps: "true" }),
+  })
+  return `${wsBase}/speech-to-text/realtime?${params.toString()}`
+}
+
+export const encodeAudioFrame = (bytes: Uint8Array, sampleRate: number) =>
+  JSON.stringify({
+    message_type: "input_audio_chunk",
+    audio_base_64: Encoding.encodeBase64(bytes),
+    sample_rate: sampleRate,
+  })
+
+// ---------------------------------------------------------------------------
+// Parse one server message and emit to the queue if it maps to a
+// TranscriptEvent. Invalid JSON / unknown shapes are silently dropped —
+// the connection stays open and we keep streaming subsequent messages.
+// ---------------------------------------------------------------------------
+
+const handleServerMessage =
+  (
+    queue: Queue.Queue<TranscriptEvent, Cause.Done>,
+    mapEvent: (msg: typeof ServerMessage.Type) => TranscriptEvent | undefined,
+  ) =>
+  (raw: string) =>
+    Effect.gen(function* () {
+      const json = yield* JSONL.parseSafe(raw)
+      if (json === undefined) return
+      const decoded = yield* decodeServerMessage(json).pipe(Effect.option)
+      if (decoded._tag === "None") return
+      const event = mapEvent(decoded.value)
+      if (event !== undefined) yield* Queue.offer(queue, event)
+    })
+
+// ---------------------------------------------------------------------------
+// Stream<Uint8Array> → Stream<TranscriptEvent>
+//
+// Requires `HttpClient` (single-use token fetch) and
+// `Socket.WebSocketConstructor` (any `globalThis.WebSocket` works) in
+// context — `Socket.layerWebSocketConstructorGlobal` covers every
+// modern runtime.
+// ---------------------------------------------------------------------------
+
+export const streamTranscription =
+  (cfg: Config) =>
+  <E, R>(
+    audioIn: Stream.Stream<Uint8Array, E, R>,
+    request: CommonStreamTranscribeRequest,
+  ): Stream.Stream<
+    TranscriptEvent,
+    AiError.AiError | E,
+    R | HttpClient.HttpClient | Socket.WebSocketConstructor
+  > =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const slug = yield* inputFormatToSlug(request.inputFormat)
+        const token = yield* fetchSingleUseToken(cfg)
+        const includeTimestamps = request.wordTimestamps === true
+        const url = buildWsUrl(cfg, token, slug, {
+          ...(request.model !== undefined && { model: request.model }),
+          ...(request.language !== undefined && { languageCode: request.language }),
+          includeTimestamps,
+        })
+        const socket = yield* Socket.makeWebSocket(url, {
+          // Effect's Socket treats all close codes as errors by default — that
+          // surfaces a clean server-side close as a stream failure. Whitelist
+          // standard clean-close codes (1000 / 1001 / 1005).
+          closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
+        })
+        const queue = yield* Queue.bounded<TranscriptEvent, Cause.Done>(64)
+        const sampleRate = request.inputFormat.sampleRate
+
+        const write = yield* socket.writer
+        yield* Stream.runForEach(audioIn, (bytes) =>
+          write(encodeAudioFrame(bytes, sampleRate)),
+        ).pipe(Effect.ignore, Effect.forkScoped)
+
+        // `Queue.end` flushes pending events then fails the next take with
+        // `Done` — clean stream end. `Queue.shutdown` would CLEAR queued
+        // items and interrupt pending takes (wrong for graceful teardown).
+        yield* socket
+          .runString(handleServerMessage(queue, wireToEvent(includeTimestamps)))
+          .pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped)
+
+        return Stream.fromQueue(queue)
+      }),
+    )

package/src/realtimeTts.ts

@@ -0,0 +1,147 @@
+import { Cause, Effect, Encoding, Queue, Redacted, Result, Schema, Stream } from "effect"
+import * as Socket from "effect/unstable/socket/Socket"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioChunk, AudioFormat } from "@effect-uai/core/Audio"
+import * as JSONL from "@effect-uai/core/JSONL"
+import {
+  defaultFormat,
+  formatToOutputSlug,
+  type VoiceSettings,
+  wireVoiceSettings,
+} from "./codec.js"
+import type { ElevenLabsTtsModel, ElevenLabsVoiceId } from "./models.js"
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+export type { VoiceSettings } from "./codec.js"
+
+/**
+ * Incremental-text-in request for `/stream-input`. `voiceSettings`
+ * applies only on the BOS frame — mid-stream voice changes are
+ * rejected. `autoMode: true` (default) lets the model pick flush
+ * boundaries, which is what you want for LLM-token streams.
+ */
+export type StreamSynthesizeRequest = {
+  readonly model?: ElevenLabsTtsModel
+  readonly voiceId: ElevenLabsVoiceId
+  readonly outputFormat?: AudioFormat
+  readonly languageCode?: string
+  readonly voiceSettings?: VoiceSettings
+  readonly autoMode?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// URL + frame builders
+// ---------------------------------------------------------------------------
+
+export const buildWsUrl = (cfg: Config, request: StreamSynthesizeRequest, outputFormat: string) => {
+  const wsBase = (cfg.baseUrl ?? "https://api.elevenlabs.io/v1").replace(/^http/, "ws")
+  const params = new URLSearchParams({
+    output_format: outputFormat,
+    auto_mode: String(request.autoMode ?? true),
+    ...(request.model !== undefined && { model_id: request.model }),
+    ...(request.languageCode !== undefined && { language_code: request.languageCode }),
+  })
+  return `${wsBase}/text-to-speech/${request.voiceId}/stream-input?${params.toString()}`
+}
+
+const bosFrame = (cfg: Config, request: StreamSynthesizeRequest) => {
+  const vs = wireVoiceSettings(request.voiceSettings)
+  return JSON.stringify({
+    text: " ",
+    "xi-api-key": Redacted.value(cfg.apiKey),
+    ...(vs !== undefined && { voice_settings: vs }),
+  })
+}
+
+const textFrame = (text: string) => JSON.stringify({ text: text.endsWith(" ") ? text : `${text} ` })
+const eosFrame = JSON.stringify({ text: "" })
+
+// ---------------------------------------------------------------------------
+// Wire schema (server → client) + helpers
+// ---------------------------------------------------------------------------
+
+const ServerFrame = Schema.Struct({
+  audio: Schema.optional(Schema.NullOr(Schema.String)),
+  isFinal: Schema.optional(Schema.NullOr(Schema.Boolean)),
+  error: Schema.optional(Schema.Unknown),
+  message: Schema.optional(Schema.String),
+})
+const decodeServerFrame = Schema.decodeUnknownEffect(ServerFrame)
+
+const decodeAudio = (b64: string): Effect.Effect<Uint8Array, AiError.AiError> =>
+  Result.match(Encoding.decodeBase64(b64), {
+    onSuccess: Effect.succeed,
+    onFailure: (cause) =>
+      Effect.fail(
+        new AiError.GenerationFailed({
+          provider: "elevenlabs",
+          raw: { message: "failed to decode audio frame", cause },
+        }),
+      ),
+  })
+
+const handleServerFrame = (queue: Queue.Queue<AudioChunk, Cause.Done>) => (raw: string) =>
+  Effect.gen(function* () {
+    const json = yield* JSONL.parseSafe(raw)
+    if (json === undefined) return
+    const decoded = yield* decodeServerFrame(json).pipe(Effect.option)
+    if (decoded._tag === "None") return
+    const frame = decoded.value
+    if (frame.error !== undefined) {
+      yield* Effect.logWarning("[elevenlabs-tts] server error frame", {
+        error: frame.error,
+        message: frame.message,
+      })
+      return
+    }
+    if (frame.audio == null || frame.audio === "") return
+    const bytes = yield* decodeAudio(frame.audio).pipe(Effect.option)
+    if (bytes._tag === "Some") yield* Queue.offer(queue, { bytes: bytes.value })
+  })
+
+// ---------------------------------------------------------------------------
+// Stream<string> → Stream<AudioChunk>. Requires `Socket.WebSocketConstructor`.
+// ---------------------------------------------------------------------------
+
+export const streamSynthesis =
+  (cfg: Config) =>
+  <E, R>(
+    textIn: Stream.Stream<string, E, R>,
+    request: StreamSynthesizeRequest,
+  ): Stream.Stream<AudioChunk, AiError.AiError | E, R | Socket.WebSocketConstructor> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const slug = yield* formatToOutputSlug(request.outputFormat ?? defaultFormat)
+        // ElevenLabs closes `/stream-input` with code 1000 after delivering the
+        // final audio chunk. Effect's default treats all close codes as errors,
+        // which would surface as a stream failure right after the last audio
+        // arrives. Whitelist standard clean-close codes.
+        const socket = yield* Socket.makeWebSocket(buildWsUrl(cfg, request, slug), {
+          closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
+        })
+        const queue = yield* Queue.bounded<AudioChunk, Cause.Done>(64)
+        const write = yield* socket.writer
+
+        // Writer fiber: BOS → drain text stream → EOS. Socket-side failures
+        // end this fiber; the reader still surfaces a clean stream end via
+        // `Queue.end` (in the ensuring below) when the upstream WS closes.
+        yield* Effect.gen(function* () {
+          yield* write(bosFrame(cfg, request))
+          yield* Stream.runForEach(textIn, (text) =>
+            text.length === 0 ? Effect.void : write(textFrame(text)),
+          )
+          yield* write(eosFrame)
+        }).pipe(Effect.ignore, Effect.forkScoped)
+
+        // Reader fiber. `ensuring(Queue.end)` flushes pending chunks then
+        // fails the next take with `Done`, which `Stream.fromQueue` treats
+        // as a clean end. (`Queue.shutdown` would CLEAR queued items and
+        // interrupt pending takes — wrong for graceful teardown.)
+        yield* socket
+          .runString(handleServerFrame(queue))
+          .pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped)
+
+        return Stream.fromQueue(queue)
+      }),
+    )