@effect-uai/elevenlabs 0.6.0 → 0.7.0

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,6 +3,7 @@ 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"
@@ -175,6 +176,7 @@ export type RealtimeOptions = {
   readonly languageCode?: string
   readonly includeTimestamps?: boolean
   readonly commitStrategy?: "manual" | "vad"
+  readonly keyterms?: ReadonlyArray<string>
 }
 
 export const buildWsUrl = (
@@ -192,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()}`
 }
 
@@ -247,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,10 +3,14 @@ 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"
@@ -33,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>
 }
 
 // ---------------------------------------------------------------------------
@@ -56,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),
   })
 }
 
@@ -117,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/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()
-  })
-})