@effect-uai/elevenlabs 0.5.2 → 0.7.0

package/src/index.ts

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

package/src/models.ts

@@ -44,3 +44,20 @@ export type ElevenLabsSttModel =
  * full catalog is fetched dynamically via `GET /v1/voices`.
  */
 export type ElevenLabsVoiceId = string
+
+/**
+ * Known ElevenLabs music model identifiers.
+ *
+ * - `music_v1` — current API default (as of May 2026). General-purpose
+ *   music composition.
+ * - `music_v2` — UI default; API plumbing in progress per the
+ *   May 26 2026 v2 launch blog. Include in the literal union so
+ *   callers can opt in when it ships.
+ *
+ * Reference: https://elevenlabs.io/docs/api-reference/music/compose
+ */
+export type ElevenLabsMusicModel =
+  | "music_v1"
+  | "music_v2"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})

package/src/musicCodec.ts

@@ -0,0 +1,86 @@
+import { Duration, Effect } from "effect"
+import { warnDroppedWhen } from "@effect-uai/core/Capabilities"
+import type { CommonGenerateMusicRequest } from "@effect-uai/core/Music"
+
+// ---------------------------------------------------------------------------
+// Composition plan (camelCase; snake-cased at the wire boundary)
+// ---------------------------------------------------------------------------
+
+/**
+ * Composition plan accepted by `POST /v1/music` (and returned by
+ * `POST /v1/music/plan`). Mirrors the wire `MusicPrompt` schema with
+ * camelCase fields. Validation lives server-side (3 s to 10 min total,
+ * up to 30 sections, 3 s to 2 min per section, ≤200 chars per lyric
+ * line); we pass the body through and surface 422 errors via the
+ * HTTP-status mapping.
+ *
+ * Reference: https://elevenlabs.io/docs/api-reference/music/compose
+ */
+export type ElevenLabsCompositionPlan = {
+  readonly positiveGlobalStyles: ReadonlyArray<string>
+  readonly negativeGlobalStyles: ReadonlyArray<string>
+  readonly sections: ReadonlyArray<ElevenLabsSongSection>
+}
+
+export type ElevenLabsSongSection = {
+  readonly sectionName: string
+  readonly positiveLocalStyles: ReadonlyArray<string>
+  readonly negativeLocalStyles: ReadonlyArray<string>
+  readonly duration: Duration.Duration
+  readonly lines: ReadonlyArray<string>
+}
+
+export const wireCompositionPlan = (plan: ElevenLabsCompositionPlan) => ({
+  positive_global_styles: plan.positiveGlobalStyles,
+  negative_global_styles: plan.negativeGlobalStyles,
+  sections: plan.sections.map((s) => ({
+    section_name: s.sectionName,
+    positive_local_styles: s.positiveLocalStyles,
+    negative_local_styles: s.negativeLocalStyles,
+    duration_ms: Duration.toMillis(s.duration),
+    lines: s.lines,
+  })),
+})
+
+export const decodeCompositionPlan = (raw: unknown): ElevenLabsCompositionPlan => {
+  const r = raw as {
+    positive_global_styles?: ReadonlyArray<string>
+    negative_global_styles?: ReadonlyArray<string>
+    sections?: ReadonlyArray<{
+      section_name: string
+      positive_local_styles?: ReadonlyArray<string>
+      negative_local_styles?: ReadonlyArray<string>
+      duration_ms: number
+      lines?: ReadonlyArray<string>
+    }>
+  }
+  return {
+    positiveGlobalStyles: r.positive_global_styles ?? [],
+    negativeGlobalStyles: r.negative_global_styles ?? [],
+    sections: (r.sections ?? []).map((s) => ({
+      sectionName: s.section_name,
+      positiveLocalStyles: s.positive_local_styles ?? [],
+      negativeLocalStyles: s.negative_local_styles ?? [],
+      duration: Duration.millis(s.duration_ms),
+      lines: s.lines ?? [],
+    })),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bucket-2 warn-and-drop for Common fields ElevenLabs can't honor
+// in prompt mode. No prompt construction; prompts always come from
+// the caller verbatim. Migrate to `dropUnsupported` when capabilities
+// Phase 0 lands.
+// ---------------------------------------------------------------------------
+
+export const warnDroppedPromptModeHints = (
+  request: CommonGenerateMusicRequest,
+): Effect.Effect<void> =>
+  warnDroppedWhen(request.lyrics, {
+    provider: "elevenlabs-music",
+    capability: "lyrics",
+    field: "lyrics",
+    reason:
+      "Prompt mode has no lyrics field. Use `compositionPlan` with per-section `lines` to provide lyrics.",
+  })

package/src/realtimeStt.ts

@@ -3,12 +3,18 @@ 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 Capabilities from "@effect-uai/core/Capabilities"
 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"
+import { type ElevenLabsRegion, resolveHost } from "./region.js"
 
-export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}
 
 // ---------------------------------------------------------------------------
 // AudioFormat → audio_format slug
@@ -43,7 +49,7 @@ 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 url = `${resolveHost(cfg)}/single-use-token/realtime_scribe`
     const httpRequest = HttpClientRequest.post(url).pipe(
       HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
     )
@@ -170,6 +176,7 @@ export type RealtimeOptions = {
   readonly languageCode?: string
   readonly includeTimestamps?: boolean
   readonly commitStrategy?: "manual" | "vad"
+  readonly keyterms?: ReadonlyArray<string>
 }
 
 export const buildWsUrl = (
@@ -178,7 +185,7 @@ export const buildWsUrl = (
   audioFormat: string,
   opts: RealtimeOptions,
 ) => {
-  const wsBase = (cfg.baseUrl ?? "https://api.elevenlabs.io/v1").replace(/^http/, "ws")
+  const wsBase = resolveHost(cfg).replace(/^http/, "ws")
   const params = new URLSearchParams({
     token,
     audio_format: audioFormat,
@@ -187,6 +194,8 @@ export const buildWsUrl = (
     ...(opts.languageCode !== undefined && { language_code: opts.languageCode }),
     ...(opts.includeTimestamps === true && { include_timestamps: "true" }),
   })
+  // Vocab biasing — repeated `keyterms` param (≤50 on realtime).
+  for (const term of opts.keyterms ?? []) params.append("keyterms", term)
   return `${wsBase}/speech-to-text/realtime?${params.toString()}`
 }
 
@@ -242,9 +251,16 @@ export const streamTranscription =
         const slug = yield* inputFormatToSlug(request.inputFormat)
         const token = yield* fetchSingleUseToken(cfg)
         const includeTimestamps = request.wordTimestamps === true
+        yield* Capabilities.warnDroppedWhen(request.prompt, {
+          provider: "elevenlabs",
+          capability: "prompt",
+          field: "prompt",
+          reason: "ElevenLabs Scribe has no free-form prompt field; bias via `biasingTerms`.",
+        })
         const url = buildWsUrl(cfg, token, slug, {
           ...(request.model !== undefined && { model: request.model }),
           ...(request.language !== undefined && { languageCode: request.language }),
+          ...(request.biasingTerms !== undefined && { keyterms: request.biasingTerms }),
           includeTimestamps,
         })
         const socket = yield* Socket.makeWebSocket(url, {

package/src/realtimeTts.ts

@@ -3,15 +3,24 @@ 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 type { CustomPronunciation } from "@effect-uai/core/SpeechSynthesizer"
 import {
   defaultFormat,
   formatToOutputSlug,
+  type PronunciationDictionaryLocator,
+  rejectInlinePronunciations,
   type VoiceSettings,
+  wirePronunciationLocators,
   wireVoiceSettings,
 } from "./codec.js"
 import type { ElevenLabsTtsModel, ElevenLabsVoiceId } from "./models.js"
+import { type ElevenLabsRegion, resolveHost } from "./region.js"
 
-export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}
 
 export type { VoiceSettings } from "./codec.js"
 
@@ -28,6 +37,11 @@ export type StreamSynthesizeRequest = {
   readonly languageCode?: string
   readonly voiceSettings?: VoiceSettings
   readonly autoMode?: boolean
+  /** Pre-provisioned pronunciation dictionaries, sent on the BOS frame. */
+  readonly pronunciationDictionaryLocators?: ReadonlyArray<PronunciationDictionaryLocator>
+  /** Carried from the Common request so the WS path can reject inline
+   *  pronunciations (ElevenLabs has no stateless inline IPA path). */
+  readonly pronunciations?: ReadonlyArray<CustomPronunciation>
 }
 
 // ---------------------------------------------------------------------------
@@ -35,7 +49,7 @@ export type StreamSynthesizeRequest = {
 // ---------------------------------------------------------------------------
 
 export const buildWsUrl = (cfg: Config, request: StreamSynthesizeRequest, outputFormat: string) => {
-  const wsBase = (cfg.baseUrl ?? "https://api.elevenlabs.io/v1").replace(/^http/, "ws")
+  const wsBase = resolveHost(cfg).replace(/^http/, "ws")
   const params = new URLSearchParams({
     output_format: outputFormat,
     auto_mode: String(request.autoMode ?? true),
@@ -51,6 +65,7 @@ const bosFrame = (cfg: Config, request: StreamSynthesizeRequest) => {
     text: " ",
     "xi-api-key": Redacted.value(cfg.apiKey),
     ...(vs !== undefined && { voice_settings: vs }),
+    ...wirePronunciationLocators(request.pronunciationDictionaryLocators),
   })
 }
 
@@ -112,6 +127,7 @@ export const streamSynthesis =
   ): Stream.Stream<AudioChunk, AiError.AiError | E, R | Socket.WebSocketConstructor> =>
     Stream.unwrap(
       Effect.gen(function* () {
+        yield* rejectInlinePronunciations(request.pronunciations)
         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,

package/src/region.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest"
+import { resolveHost } from "./region.js"
+
+describe("elevenlabs/region.resolveHost", () => {
+  it("returns default host when no region or baseUrl", () => {
+    expect(resolveHost({})).toBe("https://api.elevenlabs.io/v1")
+  })
+
+  it("returns default host for region 'default'", () => {
+    expect(resolveHost({ region: "default" })).toBe("https://api.elevenlabs.io/v1")
+  })
+
+  it("computes EU residency host for region 'eu'", () => {
+    expect(resolveHost({ region: "eu" })).toBe("https://api.eu.residency.elevenlabs.io/v1")
+  })
+
+  it("computes IN residency host for region 'in'", () => {
+    expect(resolveHost({ region: "in" })).toBe("https://api.in.residency.elevenlabs.io/v1")
+  })
+
+  it("passes unknown region through as residency host", () => {
+    expect(resolveHost({ region: "ap" })).toBe("https://api.ap.residency.elevenlabs.io/v1")
+  })
+
+  it("baseUrl wins over region", () => {
+    expect(resolveHost({ baseUrl: "http://localhost:8080/v1", region: "eu" })).toBe(
+      "http://localhost:8080/v1",
+    )
+  })
+})

package/src/region.ts

@@ -0,0 +1,34 @@
+/**
+ * ElevenLabs regional residency endpoints. The default workspace runs
+ * against `api.elevenlabs.io`; EU- and IN-residency workspaces run
+ * against `api.{eu,in}.residency.elevenlabs.io` (REST + WSS).
+ *
+ * API keys are workspace-bound — a key minted in an EU workspace must
+ * be used against the EU host (and vice versa). Mixing key/host
+ * surfaces as `401 PERMISSION_DENIED`.
+ *
+ * Reference: https://elevenlabs.io/docs/overview/administration/data-residency
+ */
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type ElevenLabsRegion = "default" | "eu" | "in" | (string & {})
+
+const DEFAULT_HOST = "https://api.elevenlabs.io/v1"
+
+/**
+ * Resolve the HTTP base URL from a Config. `baseUrl` wins when set;
+ * otherwise the host is computed from `region`. Unknown region strings
+ * pass through as `api.{region}.residency.elevenlabs.io/v1` for forward
+ * compat.
+ *
+ * WS code derives its `wss://` URL by substituting `http→ws` on the
+ * resolved host.
+ */
+export const resolveHost = (cfg: {
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}): string => {
+  if (cfg.baseUrl !== undefined) return cfg.baseUrl
+  if (cfg.region === undefined || cfg.region === "default") return DEFAULT_HOST
+  return `https://api.${cfg.region}.residency.elevenlabs.io/v1`
+}

package/dist/ElevenLabsSynthesizer.test.mjs

@@ -1,32 +0,0 @@
-import { i as it, n as globalExpect, r as describe, t as import_dist } from "./dist-DMsg8YLb.mjs";
-import { layer } from "./ElevenLabsSynthesizer.mjs";
-import { Effect, Layer, Redacted, Stream } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-import * as Socket from "effect/unstable/socket/Socket";
-import * as SpeechSynthesizer$1 from "@effect-uai/core/SpeechSynthesizer";
-const live = layer({ apiKey: Redacted.make("test-key") }).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(Socket.layerWebSocketConstructorGlobal));
-describe("ElevenLabsSynthesizer Layer (compile-time)", () => {
-	it("registers `TtsIncrementalText` — `streamSynthesisFrom` clears R to never", () => {
-		const audio = Stream.fromIterable(["hello ", "world"]).pipe(SpeechSynthesizer$1.streamSynthesisFrom({
-			model: "eleven_flash_v2_5",
-			voiceId: "JBFqnCBsd6RMkjVDRZzb"
-		}));
-		(0, import_dist.expectTypeOf)(Stream.runDrain(audio).pipe(Effect.provide(live))).toEqualTypeOf();
-	});
-	it("sync `synthesize` and chunked `streamSynthesis` require no marker", () => {
-		(0, import_dist.expectTypeOf)(SpeechSynthesizer$1.synthesize({
-			text: "hi",
-			model: "eleven_multilingual_v2",
-			voiceId: "JBFqnCBsd6RMkjVDRZzb"
-		}).pipe(Effect.provide(live))).toEqualTypeOf();
-		globalExpect(Stream.runCollect(SpeechSynthesizer$1.streamSynthesis({
-			text: "hi",
-			model: "eleven_multilingual_v2",
-			voiceId: "JBFqnCBsd6RMkjVDRZzb"
-		})).pipe(Effect.provide(live))).toBeDefined();
-	});
-});
-//#endregion
-export {};
-
-//# sourceMappingURL=ElevenLabsSynthesizer.test.mjs.map

package/dist/ElevenLabsSynthesizer.test.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"ElevenLabsSynthesizer.test.mjs","names":["ElevenLabsSynthesizer.layer","SpeechSynthesizer"],"sources":["../src/ElevenLabsSynthesizer.test.ts"],"sourcesContent":["import { Effect, Layer, Redacted, Stream } from \"effect\"\nimport { FetchHttpClient } from \"effect/unstable/http\"\nimport * as Socket from \"effect/unstable/socket/Socket\"\nimport { describe, expect, expectTypeOf, it } from \"vitest\"\nimport type * as AiError from \"@effect-uai/core/AiError\"\nimport type { AudioBlob } from \"@effect-uai/core/Audio\"\nimport * as SpeechSynthesizer from \"@effect-uai/core/SpeechSynthesizer\"\nimport * as ElevenLabsSynthesizer from \"./ElevenLabsSynthesizer.js\"\n\nconst cfg: ElevenLabsSynthesizer.Config = { apiKey: Redacted.make(\"test-key\") }\n// FetchHttpClient + globalThis.WebSocket are required for `make`, but these\n// tests only exercise the codec and compile-time gating — no real network\n// call is made.\nconst live = ElevenLabsSynthesizer.layer(cfg).pipe(\n  Layer.provide(FetchHttpClient.layer),\n  Layer.provide(Socket.layerWebSocketConstructorGlobal),\n)\n\ndescribe(\"ElevenLabsSynthesizer Layer (compile-time)\", () => {\n  it(\"registers `TtsIncrementalText` — `streamSynthesisFrom` clears R to never\", () => {\n    const tokens: Stream.Stream<string> = Stream.fromIterable([\"hello \", \"world\"])\n    const audio = tokens.pipe(\n      SpeechSynthesizer.streamSynthesisFrom({\n        model: \"eleven_flash_v2_5\",\n        voiceId: \"JBFqnCBsd6RMkjVDRZzb\",\n      }),\n    )\n    const program = Stream.runDrain(audio).pipe(Effect.provide(live))\n    expectTypeOf(program).toEqualTypeOf<Effect.Effect<void, AiError.AiError, never>>()\n  })\n\n  it(\"sync `synthesize` and chunked `streamSynthesis` require no marker\", () => {\n    const synth = SpeechSynthesizer.synthesize({\n      text: \"hi\",\n      model: \"eleven_multilingual_v2\",\n      voiceId: \"JBFqnCBsd6RMkjVDRZzb\",\n    }).pipe(Effect.provide(live))\n    expectTypeOf(synth).toEqualTypeOf<Effect.Effect<AudioBlob, AiError.AiError, never>>()\n\n    const _stream = Stream.runCollect(\n      SpeechSynthesizer.streamSynthesis({\n        text: \"hi\",\n        model: \"eleven_multilingual_v2\",\n        voiceId: \"JBFqnCBsd6RMkjVDRZzb\",\n      }),\n    ).pipe(Effect.provide(live))\n    expect(_stream).toBeDefined()\n  })\n})\n"],"mappings":";;;;;;AAaA,MAAM,OAAOA,MAA4B,EAJG,QAAQ,SAAS,KAAK,WAAW,EAIpC,CAAI,CAAC,KAC5C,MAAM,QAAQ,gBAAgB,MAAM,EACpC,MAAM,QAAQ,OAAO,gCAAgC,CACtD;AAED,SAAS,oDAAoD;AAC3D,IAAG,kFAAkF;EAEnF,MAAM,QADgC,OAAO,aAAa,CAAC,UAAU,QAAQ,CACzD,CAAC,KACnBC,oBAAkB,oBAAoB;GACpC,OAAO;GACP,SAAS;GACV,CAAC,CACH;AAED,GAAA,GAAA,YAAA,cADgB,OAAO,SAAS,MAAM,CAAC,KAAK,OAAO,QAAQ,KAAK,CAC5C,CAAC,CAAC,eAA4D;GAClF;AAEF,IAAG,2EAA2E;AAM5E,GAAA,GAAA,YAAA,cALcA,oBAAkB,WAAW;GACzC,MAAM;GACN,OAAO;GACP,SAAS;GACV,CAAC,CAAC,KAAK,OAAO,QAAQ,KAAK,CACV,CAAC,CAAC,eAAiE;AASrF,eAPgB,OAAO,WACrBA,oBAAkB,gBAAgB;GAChC,MAAM;GACN,OAAO;GACP,SAAS;GACV,CAAC,CACH,CAAC,KAAK,OAAO,QAAQ,KAAK,CACb,CAAC,CAAC,aAAa;GAC7B;EACF"}

package/src/ElevenLabsSynthesizer.test.ts

@@ -1,49 +0,0 @@
-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()
-  })
-})