@effect-uai/elevenlabs 0.4.0

package/dist/realtimeTts.mjs.map

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@effect-uai/elevenlabs",
+  "version": "0.4.0",
+  "description": "ElevenLabs speech-to-text and text-to-speech provider for @effect-uai/core.",
+  "keywords": [
+    "ai",
+    "effect",
+    "elevenlabs",
+    "speech",
+    "stt",
+    "transcription",
+    "tts"
+  ],
+  "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/providers/elevenlabs",
+  "bugs": {
+    "url": "https://github.com/betalyra/effect-uai/issues"
+  },
+  "license": "MIT",
+  "author": "Betalyra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/betalyra/effect-uai",
+    "directory": "packages/providers/elevenlabs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./ElevenLabsSynthesizer": {
+      "types": "./dist/ElevenLabsSynthesizer.d.mts",
+      "import": "./dist/ElevenLabsSynthesizer.mjs"
+    },
+    "./ElevenLabsTranscriber": {
+      "types": "./dist/ElevenLabsTranscriber.d.mts",
+      "import": "./dist/ElevenLabsTranscriber.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "effect": "4.0.0-beta.57",
+    "typescript": "^6.0.3",
+    "@effect-uai/core": "0.4.0"
+  },
+  "peerDependencies": {
+    "@effect-uai/core": ">=0.2.0 <1",
+    "effect": "4.0.0-beta.57"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/ElevenLabsSynthesizer.test.ts

@@ -0,0 +1,49 @@
+import { Effect, Layer, Redacted, Stream } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import * as Socket from "effect/unstable/socket/Socket"
+import { describe, expect, expectTypeOf, it } from "vitest"
+import type * as AiError from "@effect-uai/core/AiError"
+import type { AudioBlob } from "@effect-uai/core/Audio"
+import * as SpeechSynthesizer from "@effect-uai/core/SpeechSynthesizer"
+import * as ElevenLabsSynthesizer from "./ElevenLabsSynthesizer.js"
+
+const cfg: ElevenLabsSynthesizer.Config = { apiKey: Redacted.make("test-key") }
+// FetchHttpClient + globalThis.WebSocket are required for `make`, but these
+// tests only exercise the codec and compile-time gating — no real network
+// call is made.
+const live = ElevenLabsSynthesizer.layer(cfg).pipe(
+  Layer.provide(FetchHttpClient.layer),
+  Layer.provide(Socket.layerWebSocketConstructorGlobal),
+)
+
+describe("ElevenLabsSynthesizer Layer (compile-time)", () => {
+  it("registers `TtsIncrementalText` — `streamSynthesisFrom` clears R to never", () => {
+    const tokens: Stream.Stream<string> = Stream.fromIterable(["hello ", "world"])
+    const audio = tokens.pipe(
+      SpeechSynthesizer.streamSynthesisFrom({
+        model: "eleven_flash_v2_5",
+        voiceId: "JBFqnCBsd6RMkjVDRZzb",
+      }),
+    )
+    const program = Stream.runDrain(audio).pipe(Effect.provide(live))
+    expectTypeOf(program).toEqualTypeOf<Effect.Effect<void, AiError.AiError, never>>()
+  })
+
+  it("sync `synthesize` and chunked `streamSynthesis` require no marker", () => {
+    const synth = SpeechSynthesizer.synthesize({
+      text: "hi",
+      model: "eleven_multilingual_v2",
+      voiceId: "JBFqnCBsd6RMkjVDRZzb",
+    }).pipe(Effect.provide(live))
+    expectTypeOf(synth).toEqualTypeOf<Effect.Effect<AudioBlob, AiError.AiError, never>>()
+
+    const _stream = Stream.runCollect(
+      SpeechSynthesizer.streamSynthesis({
+        text: "hi",
+        model: "eleven_multilingual_v2",
+        voiceId: "JBFqnCBsd6RMkjVDRZzb",
+      }),
+    ).pipe(Effect.provide(live))
+    expect(_stream).toBeDefined()
+  })
+})

package/src/ElevenLabsSynthesizer.ts

@@ -0,0 +1,165 @@
+import { Context, Effect, Layer, Redacted, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as Socket from "effect/unstable/socket/Socket"
+import type * as AiError from "@effect-uai/core/AiError"
+import type { AudioBlob, AudioChunk } from "@effect-uai/core/Audio"
+import {
+  type CommonStreamSynthesizeRequest,
+  type CommonSynthesizeRequest,
+  SpeechSynthesizer,
+  type SpeechSynthesizerService,
+  TtsIncrementalText,
+} from "@effect-uai/core/SpeechSynthesizer"
+import {
+  defaultFormat,
+  formatToOutputSlug,
+  httpStatusError,
+  transportFailure,
+  type VoiceSettings,
+  wireVoiceSettings,
+} from "./codec.js"
+import type { ElevenLabsTtsModel, ElevenLabsVoiceId } from "./models.js"
+import { streamSynthesis as realtimeStream } from "./realtimeTts.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * ElevenLabs-typed synthesize request. `voiceSettings` exposes the
+ * provider's prosody/timbre controls; `seed` makes generation
+ * deterministic; `previousText` / `nextText` thread context across
+ * sequential calls for natural prosody.
+ */
+export type ElevenLabsSynthesizeRequest = Omit<CommonSynthesizeRequest, "model" | "voiceId"> & {
+  readonly model: ElevenLabsTtsModel
+  readonly voiceId: ElevenLabsVoiceId
+  readonly voiceSettings?: VoiceSettings
+  readonly seed?: number
+  readonly previousText?: string
+  readonly nextText?: string
+}
+
+export type ElevenLabsSynthesizerService = {
+  readonly synthesize: (r: ElevenLabsSynthesizeRequest) => Effect.Effect<AudioBlob, AiError.AiError>
+  readonly streamSynthesis: (
+    r: ElevenLabsSynthesizeRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  readonly streamSynthesisFrom: SpeechSynthesizerService["streamSynthesisFrom"]
+}
+
+export class ElevenLabsSynthesizer extends Context.Service<
+  ElevenLabsSynthesizer,
+  ElevenLabsSynthesizerService
+>()("@betalyra/effect-uai/providers/elevenlabs/ElevenLabsSynthesizer") {}
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+// ---------------------------------------------------------------------------
+// Codec — request → JSON body
+// ---------------------------------------------------------------------------
+
+const buildBody = (r: ElevenLabsSynthesizeRequest) => ({
+  text: r.text,
+  model_id: r.model,
+  ...(r.languageCode !== undefined && { language_code: r.languageCode }),
+  ...(r.seed !== undefined && { seed: r.seed }),
+  ...(r.previousText !== undefined && { previous_text: r.previousText }),
+  ...(r.nextText !== undefined && { next_text: r.nextText }),
+  ...(r.voiceSettings !== undefined && { voice_settings: wireVoiceSettings(r.voiceSettings) }),
+})
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing (sync + chunked-HTTP streaming)
+// ---------------------------------------------------------------------------
+
+const baseUrl = (cfg: Config) => cfg.baseUrl ?? "https://api.elevenlabs.io/v1"
+
+const buildHttpRequest = (cfg: Config, r: ElevenLabsSynthesizeRequest, path: "" | "/stream") =>
+  Effect.gen(function* () {
+    const format = r.outputFormat ?? defaultFormat
+    const slug = yield* formatToOutputSlug(format)
+    const url = `${baseUrl(cfg)}/text-to-speech/${r.voiceId}${path}?output_format=${slug}`
+    const httpRequest = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(buildBody(r)),
+    )
+    return { httpRequest, format }
+  })
+
+const synthesizeImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const { httpRequest, format } = yield* buildHttpRequest(cfg, request, "")
+    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 bytes = yield* response.arrayBuffer.pipe(Effect.mapError(transportFailure))
+    return { format, bytes: new Uint8Array(bytes) } satisfies AudioBlob
+  })
+
+const streamSynthesisImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const { httpRequest } = yield* buildHttpRequest(cfg, request, "/stream")
+      const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return Stream.fail(httpStatusError(response.status, text))
+      }
+      return response.stream.pipe(
+        Stream.mapError(transportFailure),
+        Stream.map((bytes): AudioChunk => ({ bytes })),
+      )
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (cfg: Config) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const ctor = yield* Socket.WebSocketConstructor
+    return {
+      synthesize: (r) =>
+        synthesizeImpl(cfg)(r).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+      streamSynthesis: (r) =>
+        streamSynthesisImpl(cfg)(r).pipe(Stream.provideService(HttpClient.HttpClient, client)),
+      streamSynthesisFrom: (textIn, request) =>
+        realtimeStream(cfg)(textIn, request as ElevenLabsSynthesizeRequest).pipe(
+          Stream.provideService(Socket.WebSocketConstructor, ctor),
+        ),
+    } satisfies ElevenLabsSynthesizerService
+  })
+
+/**
+ * Layer registers `ElevenLabsSynthesizer`, the generic
+ * `SpeechSynthesizer`, **and `TtsIncrementalText`** — incremental
+ * text-in is wired to the realtime `/stream-input` WebSocket. Provide
+ * `Socket.layerWebSocketConstructorGlobal` and an `HttpClient` Layer at
+ * the call site.
+ */
+export const layer = (cfg: Config) =>
+  Layer.mergeAll(
+    Layer.effect(ElevenLabsSynthesizer, make(cfg)),
+    Layer.effect(
+      SpeechSynthesizer,
+      Effect.map(
+        make(cfg),
+        (s): SpeechSynthesizerService => ({
+          synthesize: (req: CommonSynthesizeRequest) =>
+            s.synthesize(req as ElevenLabsSynthesizeRequest),
+          streamSynthesis: (req: CommonSynthesizeRequest) =>
+            s.streamSynthesis(req as ElevenLabsSynthesizeRequest),
+          streamSynthesisFrom: (textIn, req: CommonStreamSynthesizeRequest) =>
+            s.streamSynthesisFrom(textIn, req),
+        }),
+      ),
+    ),
+    Layer.succeed(TtsIncrementalText, undefined),
+  )

package/src/ElevenLabsTranscriber.test.ts

@@ -0,0 +1,63 @@
+import { Effect, Layer, Redacted, Stream } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import * as Socket from "effect/unstable/socket/Socket"
+import { describe, expect, expectTypeOf, it } from "vitest"
+import type * as AiError from "@effect-uai/core/AiError"
+import type { TranscriptResult } from "@effect-uai/core/Transcript"
+import * as Transcriber from "@effect-uai/core/Transcriber"
+import * as ElevenLabsTranscriber from "./ElevenLabsTranscriber.js"
+
+const cfg: ElevenLabsTranscriber.Config = { apiKey: Redacted.make("test-key") }
+// FetchHttpClient + globalThis.WebSocket are required for `make`, but these
+// tests only exercise the codec + compile-time / runtime branches — no real
+// HTTP or WS connection is opened.
+const live = ElevenLabsTranscriber.layer(cfg).pipe(
+  Layer.provide(FetchHttpClient.layer),
+  Layer.provide(Socket.layerWebSocketConstructorGlobal),
+)
+
+const dummyAudio = {
+  _tag: "bytes" as const,
+  bytes: new Uint8Array([0, 1, 2, 3]),
+  mimeType: "audio/wav" as const,
+}
+
+describe("ElevenLabsTranscriber input format guard (runtime)", () => {
+  it("fails Unsupported for unsupported raw encodings", async () => {
+    const program = ElevenLabsTranscriber.ElevenLabsTranscriber.use((s) =>
+      Stream.runDrain(
+        s.streamTranscriptionFrom(Stream.fromIterable([new Uint8Array([0])]), {
+          model: "scribe_v2_realtime",
+          inputFormat: { container: "mp3", encoding: "mp3", sampleRate: 44100 },
+        }),
+      ),
+    )
+    const exit = await Effect.runPromiseExit(program.pipe(Effect.provide(live)))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      expect(JSON.stringify(exit.cause)).toContain("Unsupported")
+      expect(JSON.stringify(exit.cause)).toContain("inputFormat")
+    }
+  })
+})
+
+describe("ElevenLabsTranscriber Layer (compile-time)", () => {
+  it("registers `SttStreaming` — `streamTranscriptionFrom` clears R to never", () => {
+    const audio: Stream.Stream<Uint8Array> = Stream.fromIterable([new Uint8Array([0])])
+    const events = audio.pipe(
+      Transcriber.streamTranscriptionFrom({
+        model: "scribe_v2_realtime",
+        inputFormat: { container: "raw", encoding: "pcm_s16le", sampleRate: 16000 },
+      }),
+    )
+    const provided = Stream.runDrain(events).pipe(Effect.provide(live))
+    expectTypeOf(provided).toEqualTypeOf<Effect.Effect<void, AiError.AiError, never>>()
+  })
+
+  it("sync `transcribe` requires no marker", () => {
+    const t = Transcriber.transcribe({ audio: dummyAudio, model: "scribe_v2" }).pipe(
+      Effect.provide(live),
+    )
+    expectTypeOf(t).toEqualTypeOf<Effect.Effect<TranscriptResult, AiError.AiError, never>>()
+  })
+})

package/src/ElevenLabsTranscriber.ts

@@ -0,0 +1,179 @@
+import { Context, Effect, Layer, 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 { TranscriptResult, WordTimestamp } from "@effect-uai/core/Transcript"
+import {
+  type CommonTranscribeRequest,
+  SttStreaming,
+  Transcriber,
+  type TranscriberService,
+} from "@effect-uai/core/Transcriber"
+import { audioToBlob, defaultFileName, httpStatusError, transportFailure } from "./codec.js"
+import type { ElevenLabsSttModel } from "./models.js"
+import { streamTranscription } from "./realtimeStt.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * ElevenLabs-typed transcribe request. `model` narrows to
+ * `ElevenLabsSttModel`. `numSpeakers` hints diarization. `audioEvents`
+ * surfaces `(laughter)` / `(music)` tags inline in `text` (provider
+ * default: true). `fileName` overrides the multipart upload's
+ * `filename`; ElevenLabs uses the extension to detect format.
+ */
+export type ElevenLabsTranscribeRequest = Omit<CommonTranscribeRequest, "model"> & {
+  readonly model: ElevenLabsSttModel
+  readonly numSpeakers?: number
+  readonly audioEvents?: boolean
+  readonly fileName?: string
+}
+
+export type ElevenLabsTranscriberService = {
+  readonly transcribe: (
+    r: ElevenLabsTranscribeRequest,
+  ) => Effect.Effect<TranscriptResult, AiError.AiError>
+  readonly streamTranscriptionFrom: TranscriberService["streamTranscriptionFrom"]
+}
+
+export class ElevenLabsTranscriber extends Context.Service<
+  ElevenLabsTranscriber,
+  ElevenLabsTranscriberService
+>()("@betalyra/effect-uai/providers/elevenlabs/ElevenLabsTranscriber") {}
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+// ---------------------------------------------------------------------------
+// Response schema
+// ---------------------------------------------------------------------------
+
+const Word = Schema.Struct({
+  text: Schema.String,
+  start: Schema.optional(Schema.Number),
+  end: Schema.optional(Schema.Number),
+  type: Schema.optional(Schema.String),
+  speaker_id: Schema.optional(Schema.String),
+  logprob: Schema.optional(Schema.Number),
+})
+
+const Wire = Schema.Struct({
+  text: Schema.String,
+  language_code: Schema.optional(Schema.String),
+  language_probability: Schema.optional(Schema.Number),
+  words: Schema.optional(Schema.Array(Word)),
+  transcription_id: Schema.optional(Schema.String),
+})
+const decodeWire = Schema.decodeUnknownEffect(Wire)
+
+const toWordTimestamp = (w: typeof Word.Type): WordTimestamp | undefined =>
+  w.start === undefined || w.end === undefined
+    ? undefined
+    : {
+        text: w.text,
+        startSeconds: w.start,
+        endSeconds: w.end,
+        ...(w.logprob !== undefined && { confidence: Math.exp(w.logprob) }),
+        ...(w.speaker_id !== undefined && { speakerId: w.speaker_id }),
+      }
+
+// ---------------------------------------------------------------------------
+// Multipart body
+// ---------------------------------------------------------------------------
+
+const buildForm = (request: ElevenLabsTranscribeRequest) =>
+  Effect.gen(function* () {
+    const blob = yield* audioToBlob(request.audio)
+    const fileName = request.fileName ?? defaultFileName(request.audio.mimeType ?? "")
+    const form = new FormData()
+    form.set("model_id", request.model)
+    form.set("file", blob, fileName)
+    if (request.language !== undefined) form.set("language_code", request.language)
+    if (request.diarization !== undefined)
+      form.set("diarize", request.diarization ? "true" : "false")
+    if (request.wordTimestamps === true) form.set("timestamps_granularity", "word")
+    if (request.numSpeakers !== undefined) form.set("num_speakers", String(request.numSpeakers))
+    if (request.audioEvents !== undefined)
+      form.set("tag_audio_events", request.audioEvents ? "true" : "false")
+    return form
+  })
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing
+// ---------------------------------------------------------------------------
+
+const baseUrl = (cfg: Config) => cfg.baseUrl ?? "https://api.elevenlabs.io/v1"
+
+const transcribeImpl = (cfg: Config) => (request: ElevenLabsTranscribeRequest) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const form = yield* buildForm(request)
+    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/speech-to-text`).pipe(
+      HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyFormData(form),
+    )
+    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* decodeWire(json).pipe(
+      Effect.mapError(
+        (cause) => new AiError.GenerationFailed({ provider: "elevenlabs", raw: cause }),
+      ),
+    )
+    const words = wire.words
+      ?.map(toWordTimestamp)
+      .filter((w): w is WordTimestamp => w !== undefined)
+    return {
+      text: wire.text,
+      ...(wire.language_code !== undefined && { languageCode: wire.language_code }),
+      ...(words !== undefined && words.length > 0 && { words }),
+      raw: json,
+    } satisfies TranscriptResult
+  })
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (cfg: Config) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const ctor = yield* Socket.WebSocketConstructor
+    return {
+      transcribe: (r) =>
+        transcribeImpl(cfg)(r).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+      streamTranscriptionFrom: (audioIn, request) =>
+        streamTranscription(cfg)(audioIn, request).pipe(
+          Stream.provideService(HttpClient.HttpClient, client),
+          Stream.provideService(Socket.WebSocketConstructor, ctor),
+        ),
+    } satisfies ElevenLabsTranscriberService
+  })
+
+/**
+ * Layer registers `ElevenLabsTranscriber`, the generic `Transcriber`,
+ * **and the `SttStreaming` capability marker** — `streamTranscriptionFrom`
+ * is wired to the realtime WebSocket. Provide
+ * `Socket.layerWebSocketConstructorGlobal` (or a custom constructor) +
+ * an `HttpClient` Layer at the call site.
+ */
+export const layer = (cfg: Config) =>
+  Layer.mergeAll(
+    Layer.effect(ElevenLabsTranscriber, make(cfg)),
+    Layer.effect(
+      Transcriber,
+      Effect.map(
+        make(cfg),
+        (s): TranscriberService => ({
+          transcribe: (req: CommonTranscribeRequest) =>
+            s.transcribe(req as ElevenLabsTranscribeRequest),
+          streamTranscriptionFrom: s.streamTranscriptionFrom,
+        }),
+      ),
+    ),
+    Layer.succeed(SttStreaming, undefined),
+  )

package/src/codec.test.ts

@@ -0,0 +1,128 @@
+import { Effect, Encoding } from "effect"
+import { describe, expect, it } from "vitest"
+import type { AudioSource } from "@effect-uai/core/Audio"
+import { audioToBlob, defaultFileName, formatToOutputSlug, httpStatusError } from "./codec.js"
+
+describe("formatToOutputSlug", () => {
+  it("encodes mp3 with default bitrate when omitted", async () => {
+    const slug = await Effect.runPromise(
+      formatToOutputSlug({ container: "mp3", encoding: "mp3", sampleRate: 44100 }),
+    )
+    expect(slug).toBe("mp3_44100_128")
+  })
+
+  it("honours an explicit mp3 bitrate", async () => {
+    const slug = await Effect.runPromise(
+      formatToOutputSlug({ container: "mp3", encoding: "mp3", sampleRate: 22050, bitRate: 32 }),
+    )
+    expect(slug).toBe("mp3_22050_32")
+  })
+
+  it("encodes raw pcm_s16le as `pcm_<sampleRate>`", async () => {
+    const slug = await Effect.runPromise(
+      formatToOutputSlug({ container: "raw", encoding: "pcm_s16le", sampleRate: 16000 }),
+    )
+    expect(slug).toBe("pcm_16000")
+  })
+
+  it("encodes mu-law as `ulaw_<sampleRate>`", async () => {
+    const slug = await Effect.runPromise(
+      formatToOutputSlug({ container: "raw", encoding: "pcm_mulaw", sampleRate: 8000 }),
+    )
+    expect(slug).toBe("ulaw_8000")
+  })
+
+  it("encodes opus with default bitrate", async () => {
+    const slug = await Effect.runPromise(
+      formatToOutputSlug({ container: "opus", encoding: "opus", sampleRate: 48000 }),
+    )
+    expect(slug).toBe("opus_48000_128")
+  })
+
+  it("encodes wav as `wav_<sampleRate>`", async () => {
+    const slug = await Effect.runPromise(
+      formatToOutputSlug({ container: "wav", encoding: "pcm_s16le", sampleRate: 48000 }),
+    )
+    expect(slug).toBe("wav_48000")
+  })
+
+  it("fails Unsupported for flac / aac / webm / ogg", async () => {
+    const exit = await Effect.runPromiseExit(
+      formatToOutputSlug({ container: "flac", encoding: "flac", sampleRate: 44100 }),
+    )
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      expect(JSON.stringify(exit.cause)).toContain("Unsupported")
+      expect(JSON.stringify(exit.cause)).toContain("outputFormat")
+    }
+  })
+})
+
+describe("audioToBlob", () => {
+  it("wraps bytes into a Blob with the right MIME type", async () => {
+    const source: AudioSource = {
+      _tag: "bytes",
+      bytes: new Uint8Array([1, 2, 3, 4]),
+      mimeType: "audio/wav",
+    }
+    const blob = await Effect.runPromise(audioToBlob(source))
+    expect(blob.type).toBe("audio/wav")
+    expect(blob.size).toBe(4)
+  })
+
+  it("decodes a base64 source into bytes", async () => {
+    const original = new Uint8Array([0xde, 0xad, 0xbe, 0xef])
+    const source: AudioSource = {
+      _tag: "base64",
+      base64: Encoding.encodeBase64(original),
+      mimeType: "audio/mpeg",
+    }
+    const blob = await Effect.runPromise(audioToBlob(source))
+    expect(blob.type).toBe("audio/mpeg")
+    expect(blob.size).toBe(4)
+  })
+
+  it("fails InvalidRequest for url sources", async () => {
+    const source: AudioSource = { _tag: "url", url: "https://x/y.mp3", mimeType: "audio/mpeg" }
+    const exit = await Effect.runPromiseExit(audioToBlob(source))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      expect(JSON.stringify(exit.cause)).toContain("InvalidRequest")
+      expect(JSON.stringify(exit.cause)).toContain("cloud_storage_url")
+    }
+  })
+})
+
+describe("defaultFileName", () => {
+  it("maps audio/mpeg → audio.mp3", () => {
+    expect(defaultFileName("audio/mpeg")).toBe("audio.mp3")
+  })
+  it("maps audio/wav → audio.wav", () => {
+    expect(defaultFileName("audio/wav")).toBe("audio.wav")
+  })
+  it("falls back to audio (no extension) for unknown MIME", () => {
+    expect(defaultFileName("application/octet-stream")).toBe("audio")
+  })
+})
+
+describe("httpStatusError", () => {
+  const tags = (status: number) => JSON.parse(JSON.stringify(httpStatusError(status, "body")))._tag
+  it("maps 429 to RateLimited", () => expect(tags(429)).toBe("RateLimited"))
+  it("maps 408/504 to Timeout", () => {
+    expect(tags(408)).toBe("Timeout")
+    expect(tags(504)).toBe("Timeout")
+  })
+  it("maps 401/402/403 to AuthFailed", () => {
+    expect(tags(401)).toBe("AuthFailed")
+    expect(tags(402)).toBe("AuthFailed")
+    expect(tags(403)).toBe("AuthFailed")
+  })
+  it("maps 5xx to Unavailable", () => {
+    expect(tags(500)).toBe("Unavailable")
+    expect(tags(503)).toBe("Unavailable")
+  })
+  it("maps other 4xx to InvalidRequest", () => {
+    expect(tags(400)).toBe("InvalidRequest")
+    expect(tags(404)).toBe("InvalidRequest")
+  })
+})