@effect-uai/elevenlabs 0.6.0 → 0.8.0

package/src/ElevenLabsMusicGenerator.ts

@@ -0,0 +1,353 @@
+import { Context, Duration, Effect, Layer, Redacted, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioChunk, AudioFormat } from "@effect-uai/core/Audio"
+import type {
+  CommonGenerateMusicRequest,
+  CommonStreamGenerateMusicRequest,
+  GenerateResult,
+  MusicResult,
+  MusicSessionInput,
+  MusicStreamEvent,
+} from "@effect-uai/core/Music"
+import { singleVariant } from "@effect-uai/core/Music"
+import { MusicGenerator, type MusicGeneratorService } from "@effect-uai/core/MusicGenerator"
+import { defaultFormat, formatToOutputSlug } from "./codec.js"
+import type { ElevenLabsMusicModel } from "./models.js"
+import {
+  decodeCompositionPlan,
+  type ElevenLabsCompositionPlan,
+  warnDroppedPromptModeHints,
+  wireCompositionPlan,
+} from "./musicCodec.js"
+import { type ElevenLabsRegion, resolveHost } from "./region.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * ElevenLabs-typed music request. Narrows `model` to
+ * `ElevenLabsMusicModel` and adds provider-specific extras:
+ *
+ * - `compositionPlan` — switch from prompt mode to plan mode. Mutually
+ *   exclusive with `prompt` on the wire.
+ * - `forceInstrumental` — skip vocals. ElevenLabs has no `instrumental`
+ *   on the cross-provider Common request (the field was removed in
+ *   v0.7 because it has wildly different semantics per provider); the
+ *   typed surface restores it.
+ * - `signWithC2pa` — opt-in C2PA Content Credentials, MP3 output only.
+ * - `respectSectionsDurations` — composition-plan mode only. False
+ *   trades section-duration accuracy for quality + latency.
+ *
+ * Setting `compositionPlan` with a non-empty `prompt`, or with
+ * `duration`, fails `InvalidRequest` at the codec layer.
+ */
+export type ElevenLabsMusicGenerateRequest = Omit<CommonGenerateMusicRequest, "model"> & {
+  readonly model?: ElevenLabsMusicModel
+  readonly compositionPlan?: ElevenLabsCompositionPlan
+  readonly forceInstrumental?: boolean
+  readonly signWithC2pa?: boolean
+  readonly respectSectionsDurations?: boolean
+}
+
+export type CreateCompositionPlanRequest = {
+  readonly prompt: string
+  readonly duration?: Duration.Duration
+  readonly sourceCompositionPlan?: ElevenLabsCompositionPlan
+  readonly model?: ElevenLabsMusicModel
+}
+
+export type ElevenLabsMusicGeneratorService = {
+  readonly generate: (
+    request: ElevenLabsMusicGenerateRequest,
+  ) => Effect.Effect<GenerateResult, AiError.AiError>
+  readonly streamGeneration: (
+    request: ElevenLabsMusicGenerateRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  readonly streamGenerationFrom: <E, R>(
+    input: Stream.Stream<MusicSessionInput, E, R>,
+    request: CommonStreamGenerateMusicRequest,
+  ) => Stream.Stream<MusicStreamEvent, AiError.AiError | E, R>
+  /**
+   * Free endpoint (rate-limited, no credit cost): turn a prompt into a
+   * structured `MusicPrompt` plan. Feed the result back into
+   * `generate` / `streamGeneration` via `compositionPlan`.
+   */
+  readonly createCompositionPlan: (
+    request: CreateCompositionPlanRequest,
+  ) => Effect.Effect<ElevenLabsCompositionPlan, AiError.AiError>
+}
+
+export class ElevenLabsMusicGenerator extends Context.Service<
+  ElevenLabsMusicGenerator,
+  ElevenLabsMusicGeneratorService
+>()("@betalyra/effect-uai/providers/elevenlabs/ElevenLabsMusicGenerator") {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}
+
+const DEFAULT_MODEL: ElevenLabsMusicModel = "music_v1"
+
+// ---------------------------------------------------------------------------
+// HTTP errors (music namespace; reuses the same status taxonomy)
+// ---------------------------------------------------------------------------
+
+const musicTransportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "elevenlabs-music", raw: cause })
+
+const musicHttpStatusError = (status: number, body: string): AiError.AiError => {
+  if (status === 429) return new AiError.RateLimited({ provider: "elevenlabs-music", raw: body })
+  if (status === 408 || status === 504)
+    return new AiError.Timeout({ provider: "elevenlabs-music", raw: body })
+  if (status === 401)
+    return new AiError.AuthFailed({ provider: "elevenlabs-music", subtype: "auth", raw: body })
+  if (status === 403)
+    return new AiError.AuthFailed({
+      provider: "elevenlabs-music",
+      subtype: "permission",
+      raw: body,
+    })
+  if (status === 402)
+    return new AiError.AuthFailed({
+      provider: "elevenlabs-music",
+      subtype: "billing",
+      raw: body,
+    })
+  if (status >= 500)
+    return new AiError.Unavailable({ provider: "elevenlabs-music", status, raw: body })
+  return new AiError.InvalidRequest({ provider: "elevenlabs-music", raw: body })
+}
+
+// ---------------------------------------------------------------------------
+// Wire body
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the JSON body for `/v1/music` (sync + stream share the body).
+ *
+ * Mutual exclusion: `compositionPlan` and prompt-mode fields cannot
+ * coexist. When `compositionPlan` is set, `prompt` must be empty and
+ * `duration` must be unset (section durations live on the plan).
+ */
+const buildBody = (request: ElevenLabsMusicGenerateRequest) =>
+  Effect.gen(function* () {
+    const model = request.model ?? DEFAULT_MODEL
+    if (request.compositionPlan !== undefined) {
+      if (request.prompt.length > 0) {
+        return yield* Effect.fail(
+          new AiError.InvalidRequest({
+            provider: "elevenlabs-music",
+            param: "prompt",
+            raw: "`prompt` and `compositionPlan` are mutually exclusive. Pass one or the other (compositionPlan carries its own per-section lyrics and styles).",
+          }),
+        )
+      }
+      if (request.duration !== undefined) {
+        return yield* Effect.fail(
+          new AiError.InvalidRequest({
+            provider: "elevenlabs-music",
+            param: "duration",
+            raw: "`duration` is ignored when `compositionPlan` is set; section durations live on the plan. Remove `duration`.",
+          }),
+        )
+      }
+      return {
+        composition_plan: wireCompositionPlan(request.compositionPlan),
+        model_id: model,
+        ...(request.seed !== undefined && { seed: request.seed }),
+        ...(request.forceInstrumental !== undefined && {
+          force_instrumental: request.forceInstrumental,
+        }),
+        ...(request.respectSectionsDurations !== undefined && {
+          respect_sections_durations: request.respectSectionsDurations,
+        }),
+        ...(request.signWithC2pa !== undefined && { sign_with_c2pa: request.signWithC2pa }),
+      }
+    }
+    yield* warnDroppedPromptModeHints(request as CommonGenerateMusicRequest)
+    return {
+      prompt: request.prompt,
+      model_id: model,
+      ...(request.duration !== undefined && {
+        music_length_ms: Duration.toMillis(request.duration),
+      }),
+      ...(request.seed !== undefined && { seed: request.seed }),
+      ...(request.forceInstrumental !== undefined && {
+        force_instrumental: request.forceInstrumental,
+      }),
+      ...(request.signWithC2pa !== undefined && { sign_with_c2pa: request.signWithC2pa }),
+    }
+  })
+
+const buildMusicHttpRequest = (
+  cfg: Config,
+  request: ElevenLabsMusicGenerateRequest,
+  path: "" | "/stream",
+) =>
+  Effect.gen(function* () {
+    const format: AudioFormat = request.outputFormat ?? defaultFormat
+    const slug = yield* formatToOutputSlug(format)
+    const body = yield* buildBody(request)
+    const url = `${resolveHost(cfg)}/music${path}?output_format=${slug}`
+    const httpRequest = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(body),
+    )
+    return { httpRequest, format }
+  })
+
+// ---------------------------------------------------------------------------
+// Service implementation
+// ---------------------------------------------------------------------------
+
+const generateImpl =
+  (cfg: Config) =>
+  (
+    request: ElevenLabsMusicGenerateRequest,
+  ): Effect.Effect<GenerateResult, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const { httpRequest, format } = yield* buildMusicHttpRequest(cfg, request, "")
+      const response = yield* client
+        .execute(httpRequest)
+        .pipe(Effect.mapError(musicTransportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return yield* Effect.fail(musicHttpStatusError(response.status, text))
+      }
+      const buffer = yield* response.arrayBuffer.pipe(Effect.mapError(musicTransportFailure))
+      const bytes = new Uint8Array(buffer)
+      const songId = response.headers["song_id"] ?? response.headers["x-song-id"]
+      const result: MusicResult = {
+        audio: { format, bytes },
+        provider: "elevenlabs-music",
+        ...(typeof songId === "string" && { songId }),
+        ...(request.signWithC2pa === true && { watermark: "c2pa" as const }),
+      }
+      return singleVariant(result)
+    })
+
+const streamGenerationImpl =
+  (cfg: Config) =>
+  (
+    request: ElevenLabsMusicGenerateRequest,
+  ): Stream.Stream<AudioChunk, AiError.AiError, HttpClient.HttpClient> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient
+        const { httpRequest } = yield* buildMusicHttpRequest(cfg, request, "/stream")
+        const response = yield* client
+          .execute(httpRequest)
+          .pipe(Effect.mapError(musicTransportFailure))
+        if (response.status >= 400) {
+          const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+          return Stream.fail(musicHttpStatusError(response.status, text))
+        }
+        return response.stream.pipe(
+          Stream.mapError(musicTransportFailure),
+          Stream.map((bytes): AudioChunk => ({ bytes })),
+        )
+      }),
+    )
+
+/**
+ * ElevenLabs music has no bidirectional session at the wire level.
+ * Layer does not register `MusicInteractiveSession`, so callers using
+ * `MusicGenerator.streamGenerationFrom` get a compile-time error
+ * before this runtime fallback fires.
+ */
+const streamGenerationFromUnsupported = <E, R>(
+  _input: Stream.Stream<MusicSessionInput, E, R>,
+  _request: CommonStreamGenerateMusicRequest,
+): Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> =>
+  Stream.fail(
+    new AiError.Unsupported({
+      provider: "elevenlabs-music",
+      capability: "streamGenerationFrom",
+      reason:
+        "ElevenLabs music has no bidirectional session. Use `streamGeneration` for chunked output, or `createCompositionPlan` + `generate` for structured plans.",
+    }),
+  )
+
+const createCompositionPlanImpl =
+  (cfg: Config) =>
+  (
+    request: CreateCompositionPlanRequest,
+  ): Effect.Effect<ElevenLabsCompositionPlan, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const body = {
+        prompt: request.prompt,
+        model_id: request.model ?? DEFAULT_MODEL,
+        ...(request.duration !== undefined && {
+          music_length_ms: Duration.toMillis(request.duration),
+        }),
+        ...(request.sourceCompositionPlan !== undefined && {
+          source_composition_plan: wireCompositionPlan(request.sourceCompositionPlan),
+        }),
+      }
+      const httpRequest = HttpClientRequest.post(`${resolveHost(cfg)}/music/plan`).pipe(
+        HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+        HttpClientRequest.bodyJsonUnsafe(body),
+      )
+      const response = yield* client
+        .execute(httpRequest)
+        .pipe(Effect.mapError(musicTransportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return yield* Effect.fail(musicHttpStatusError(response.status, text))
+      }
+      const json = yield* response.json.pipe(Effect.mapError(musicTransportFailure))
+      return decodeCompositionPlan(json)
+    })
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (
+  cfg: Config,
+): Effect.Effect<ElevenLabsMusicGeneratorService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    generate: (request) =>
+      generateImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    streamGeneration: (request) =>
+      streamGenerationImpl(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client)),
+    streamGenerationFrom: streamGenerationFromUnsupported,
+    createCompositionPlan: (request) =>
+      createCompositionPlanImpl(cfg)(request).pipe(
+        Effect.provideService(HttpClient.HttpClient, client),
+      ),
+  }))
+
+/**
+ * Layer that registers the provider-specific `ElevenLabsMusicGenerator`
+ * tag and the generic `MusicGenerator` tag.
+ *
+ * Does NOT register `MusicInteractiveSession`. ElevenLabs music has no
+ * bidirectional wire endpoint; `streamGenerationFrom` against this
+ * Layer alone fails to typecheck.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<ElevenLabsMusicGenerator | MusicGenerator, never, HttpClient.HttpClient> =>
+  Layer.merge(
+    Layer.effect(ElevenLabsMusicGenerator, make(cfg)),
+    Layer.effect(
+      MusicGenerator,
+      Effect.map(
+        make(cfg),
+        (s): MusicGeneratorService => ({
+          generate: (req: CommonGenerateMusicRequest) =>
+            s.generate({ ...req, model: req.model as ElevenLabsMusicModel }),
+          streamGeneration: (req: CommonStreamGenerateMusicRequest) =>
+            s.streamGeneration({ ...req, model: req.model as ElevenLabsMusicModel }),
+          streamGenerationFrom: s.streamGenerationFrom,
+        }),
+      ),
+    ),
+  )

package/src/ElevenLabsSynthesizer.ts

@@ -1,4 +1,4 @@
-import { Array as Arr, Context, Effect, Layer, Redacted, Stream } from "effect"
+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"
@@ -7,7 +7,6 @@ import {
   type CommonStreamSynthesizeRequest,
   type CommonSynthesizeDialogueRequest,
   type CommonSynthesizeRequest,
-  type CustomPronunciation,
   MultiSpeakerTts,
   SpeechSynthesizer,
   type SpeechSynthesizerService,
@@ -17,8 +16,11 @@ import {
   defaultFormat,
   formatToOutputSlug,
   httpStatusError,
+  type PronunciationDictionaryLocator,
+  rejectInlinePronunciations,
   transportFailure,
   type VoiceSettings,
+  wirePronunciationLocators,
   wireVoiceSettings,
 } from "./codec.js"
 import type { ElevenLabsTtsModel, ElevenLabsVoiceId } from "./models.js"
@@ -34,6 +36,11 @@ import { type ElevenLabsRegion, resolveHost } from "./region.js"
  * provider's prosody/timbre controls; `seed` makes generation
  * deterministic; `previousText` / `nextText` thread context across
  * sequential calls for natural prosody.
+ *
+ * `pronunciationDictionaryLocators` references pre-provisioned
+ * pronunciation dictionaries by ID. Inline `pronunciations` (IPA) on
+ * the Common request are not supported by ElevenLabs and fail
+ * `Unsupported`; use a dictionary for phonetic control.
  */
 export type ElevenLabsSynthesizeRequest = Omit<CommonSynthesizeRequest, "model" | "voiceId"> & {
   readonly model: ElevenLabsTtsModel
@@ -42,6 +49,7 @@ export type ElevenLabsSynthesizeRequest = Omit<CommonSynthesizeRequest, "model"
   readonly seed?: number
   readonly previousText?: string
   readonly nextText?: string
+  readonly pronunciationDictionaryLocators?: ReadonlyArray<PronunciationDictionaryLocator>
 }
 
 export type ElevenLabsSynthesizerService = {
@@ -65,64 +73,18 @@ export type Config = {
   readonly region?: ElevenLabsRegion
 }
 
-// ---------------------------------------------------------------------------
-// Pronunciations — SSML <phoneme> rewrite (gated to legacy models)
-// ---------------------------------------------------------------------------
-
-/**
- * Models that honor inline `<phoneme>` SSML tags. Other models silently
- * drop the tags server-side, so we don't bother rewriting the text for
- * them — the pronunciation overrides are silently ignored.
- *
- * Reference: https://elevenlabs.io/docs/best-practices/prompting/controls
- */
-const PHONEME_SUPPORTED_MODELS: ReadonlySet<string> = new Set([
-  "eleven_flash_v2",
-  "eleven_english_v1",
-  "eleven_monolingual_v1",
-])
-
-const wireAlphabet = (encoding: CustomPronunciation["encoding"]): string | undefined =>
-  encoding === "ipa" ? "ipa" : encoding === "cmu-arpabet" ? "cmu-arpabet" : undefined
-
-const phonemeTag = (phrase: string, pronunciation: string, alphabet: string): string =>
-  `<phoneme alphabet="${alphabet}" ph="${pronunciation}">${phrase}</phoneme>`
-
-const escapeForRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-
-/**
- * Apply pronunciation overrides to a text string. Only applies for
- * phoneme-supported models; only IPA and CMU Arpabet are honored
- * (x-sampa is silently dropped). Whole-word, case-insensitive
- * replacement.
- */
-const applyPronunciations = (
-  text: string,
-  model: string,
-  pronunciations: ReadonlyArray<CustomPronunciation> | undefined,
-): string => {
-  if (pronunciations === undefined || !PHONEME_SUPPORTED_MODELS.has(model)) return text
-  return Arr.reduce(pronunciations, text, (acc, p) => {
-    const alphabet = wireAlphabet(p.encoding)
-    if (alphabet === undefined) return acc
-    return acc.replace(
-      new RegExp(`\\b${escapeForRegex(p.phrase)}\\b`, "i"),
-      phonemeTag(p.phrase, p.pronunciation, alphabet),
-    )
-  })
-}
-
 // ---------------------------------------------------------------------------
 // Codec — request → JSON body
 // ---------------------------------------------------------------------------
 
 const buildBody = (r: ElevenLabsSynthesizeRequest) => ({
-  text: applyPronunciations(r.text, r.model, r.pronunciations),
+  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 }),
+  ...wirePronunciationLocators(r.pronunciationDictionaryLocators),
   ...(r.voiceSettings !== undefined && { voice_settings: wireVoiceSettings(r.voiceSettings) }),
 })
 
@@ -135,7 +97,7 @@ const DEFAULT_DIALOGUE_MODEL = "eleven_v3"
 const buildDialogueBody = (r: CommonSynthesizeDialogueRequest) => ({
   inputs: r.turns.map((t) => ({
     voice_id: t.voiceId,
-    text: applyPronunciations(t.text, r.model, r.pronunciations),
+    text: t.text,
   })),
   model_id: r.model ?? DEFAULT_DIALOGUE_MODEL,
   ...(r.languageCode !== undefined && { language_code: r.languageCode }),
@@ -159,6 +121,7 @@ const buildDialogueHttpRequest = (
 
 const synthesizeDialogueImpl = (cfg: Config) => (request: CommonSynthesizeDialogueRequest) =>
   Effect.gen(function* () {
+    yield* rejectInlinePronunciations(request.pronunciations)
     const client = yield* HttpClient.HttpClient
     const { httpRequest, format } = yield* buildDialogueHttpRequest(cfg, request, "")
     const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
@@ -173,6 +136,7 @@ const synthesizeDialogueImpl = (cfg: Config) => (request: CommonSynthesizeDialog
 const streamSynthesizeDialogueImpl = (cfg: Config) => (request: CommonSynthesizeDialogueRequest) =>
   Stream.unwrap(
     Effect.gen(function* () {
+      yield* rejectInlinePronunciations(request.pronunciations)
       const client = yield* HttpClient.HttpClient
       const { httpRequest } = yield* buildDialogueHttpRequest(cfg, request, "/stream")
       const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
@@ -205,6 +169,7 @@ const buildHttpRequest = (cfg: Config, r: ElevenLabsSynthesizeRequest, path: ""
 
 const synthesizeImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =>
   Effect.gen(function* () {
+    yield* rejectInlinePronunciations(request.pronunciations)
     const client = yield* HttpClient.HttpClient
     const { httpRequest, format } = yield* buildHttpRequest(cfg, request, "")
     const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
@@ -219,6 +184,7 @@ const synthesizeImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =
 const streamSynthesisImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =>
   Stream.unwrap(
     Effect.gen(function* () {
+      yield* rejectInlinePronunciations(request.pronunciations)
       const client = yield* HttpClient.HttpClient
       const { httpRequest } = yield* buildHttpRequest(cfg, request, "/stream")
       const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))

package/src/ElevenLabsTranscriber.ts

@@ -2,6 +2,7 @@ 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 * as Capabilities from "@effect-uai/core/Capabilities"
 import type { TranscriptResult, WordTimestamp } from "@effect-uai/core/Transcript"
 import {
   type CommonTranscribeRequest,
@@ -101,6 +102,16 @@ const buildForm = (request: ElevenLabsTranscribeRequest) =>
     if (request.numSpeakers !== undefined) form.set("num_speakers", String(request.numSpeakers))
     if (request.audioEvents !== undefined)
       form.set("tag_audio_events", request.audioEvents ? "true" : "false")
+    // Vocab biasing → Scribe `keyterms` (≤1000 terms, ≤50 chars). Each
+    // term is a repeated form field (`keyterms=a&keyterms=b`), matching
+    // the ElevenLabs SDK. Scribe has no free-form prompt field.
+    for (const term of request.biasingTerms ?? []) form.append("keyterms", term)
+    yield* Capabilities.warnDroppedWhen(request.prompt, {
+      provider: "elevenlabs",
+      capability: "prompt",
+      field: "prompt",
+      reason: "ElevenLabs Scribe has no free-form prompt field; bias via `biasingTerms`.",
+    })
     return form
   })
 

package/src/codec.ts

@@ -1,6 +1,7 @@
 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"
+import type { CustomPronunciation } from "@effect-uai/core/SpeechSynthesizer"
 
 // ---------------------------------------------------------------------------
 // Shared TTS voice-settings shape (sync + streaming use the same fields)
@@ -25,6 +26,52 @@ export const wireVoiceSettings = (v: VoiceSettings | undefined) =>
         ...(v.speed !== undefined && { speed: v.speed }),
       }
 
+// ---------------------------------------------------------------------------
+// Pronunciation: dictionary locators (supported) vs inline IPA (rejected)
+// ---------------------------------------------------------------------------
+
+/**
+ * Reference to a pre-provisioned ElevenLabs pronunciation dictionary.
+ * The caller provisions and versions the dictionary out-of-band
+ * (dashboard or the pronunciation-dictionary API); we only reference it.
+ */
+export type PronunciationDictionaryLocator = {
+  readonly dictionaryId: string
+  readonly versionId: string
+}
+
+export const wirePronunciationLocators = (
+  locators: ReadonlyArray<PronunciationDictionaryLocator> | undefined,
+) =>
+  locators === undefined || locators.length === 0
+    ? undefined
+    : {
+        pronunciation_dictionary_locators: locators.map((l) => ({
+          pronunciation_dictionary_id: l.dictionaryId,
+          version_id: l.versionId,
+        })),
+      }
+
+/**
+ * ElevenLabs has no stateless inline IPA path (legacy `<phoneme>` SSML
+ * is dropped; modern phonetics live in pre-uploaded dictionaries).
+ * Inline `pronunciations` are load-bearing (bucket 1), so reject rather
+ * than silently mispronounce. Use `pronunciationDictionaryLocators`.
+ */
+export const rejectInlinePronunciations = (
+  pronunciations: ReadonlyArray<CustomPronunciation> | undefined,
+): Effect.Effect<void, AiError.AiError> =>
+  pronunciations !== undefined && pronunciations.length > 0
+    ? Effect.fail(
+        new AiError.Unsupported({
+          provider: "elevenlabs",
+          capability: "pronunciations",
+          reason:
+            "ElevenLabs has no stateless inline IPA path. Provision a pronunciation dictionary and pass `pronunciationDictionaryLocators`, or use a provider with inline phonemes (Inworld, Google).",
+        }),
+      )
+    : Effect.void
+
 // ---------------------------------------------------------------------------
 // AudioFormat → ElevenLabs `output_format` query value
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -1,3 +1,4 @@
+export * as ElevenLabsMusicGenerator from "./ElevenLabsMusicGenerator.js"
 export * as ElevenLabsSynthesizer from "./ElevenLabsSynthesizer.js"
 export * as ElevenLabsTranscriber from "./ElevenLabsTranscriber.js"
 export * as codec from "./codec.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 & {})