@effect-uai/core 0.6.0 → 0.7.0

package/src/music-generator/MusicGenerator.test.ts

@@ -1,8 +1,16 @@
-import { Effect, Stream } from "effect"
+import { Duration, Effect, Stream } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as AiError from "../domain/AiError.js"
 import type { AudioChunk, AudioFormat } from "../domain/Audio.js"
-import { configInput, promptsInput, type MusicResult } from "../domain/Music.js"
+import {
+  audioEvent,
+  controlInput,
+  type GenerateResult,
+  type MusicResult,
+  type MusicStreamEvent,
+  promptsInput,
+  singleVariant,
+} from "../domain/Music.js"
 import * as MockMusicGenerator from "../testing/MockMusicGenerator.js"
 import * as MusicGenerator from "./MusicGenerator.js"
 
@@ -13,50 +21,69 @@ const mp3Format: AudioFormat = {
   channels: 2,
 }
 
-const result: MusicResult = {
-  format: mp3Format,
-  bytes: new Uint8Array([0xff, 0xfb, 0x90, 0x00]),
-  durationSeconds: 30,
+const oneResult: MusicResult = {
+  audio: {
+    format: mp3Format,
+    bytes: new Uint8Array([0xff, 0xfb, 0x90, 0x00]),
+    duration: Duration.seconds(30),
+  },
+  provider: "mock-music",
   lyrics: "[Verse]\nhello\n",
-  watermark: { kind: "synthid" },
+  watermark: "synthid",
 }
 
+const oneVariant: GenerateResult = singleVariant(oneResult)
+
 const chunk = (n: number): AudioChunk => ({ bytes: new Uint8Array([n]) })
 
 describe("MusicGenerator.generate", () => {
-  it("returns the scripted MusicResult", async () => {
-    const mock = MockMusicGenerator.layer({ results: [result] })
+  it("returns the scripted GenerateResult", async () => {
+    const mock = MockMusicGenerator.layer({ results: [oneVariant] })
     const program = MusicGenerator.generate({
       model: "mock-music",
-      prompts: "upbeat indie pop",
+      prompt: "upbeat indie pop",
     })
     const out = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
-    expect(out.bytes).toEqual(result.bytes)
-    expect(out.durationSeconds).toBe(30)
-    expect(out.watermark?.kind).toBe("synthid")
-    expect(out.lyrics).toContain("[Verse]")
+    expect(out.primary.audio.bytes).toEqual(oneResult.audio.bytes)
+    expect(out.primary.audio.duration).toEqual(Duration.seconds(30))
+    expect(out.primary.watermark).toBe("synthid")
+    expect(out.primary.lyrics).toContain("[Verse]")
+    expect(out.variants).toHaveLength(1)
+    expect(out.variants[0]).toBe(out.primary)
+  })
+
+  it("exposes multiple variants when the provider returned more than one", async () => {
+    const secondTrack: MusicResult = {
+      ...oneResult,
+      audio: { ...oneResult.audio, bytes: new Uint8Array([0xff, 0xfb, 0xa0, 0x00]) },
+    }
+    const twoVariants: GenerateResult = {
+      primary: oneResult,
+      variants: [oneResult, secondTrack],
+    }
+    const mock = MockMusicGenerator.layer({ results: [twoVariants] })
+    const program = MusicGenerator.generate({ model: "m", prompt: "house" })
+    const out = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
+    expect(out.variants).toHaveLength(2)
+    expect(out.variants[1]!.audio.bytes).toEqual(secondTrack.audio.bytes)
   })
 
   it("records the request shape on the recorder", async () => {
-    const mock = MockMusicGenerator.layer({ results: [result, result] })
+    const mock = MockMusicGenerator.layer({ results: [oneVariant, oneVariant] })
     const program = Effect.gen(function* () {
-      yield* MusicGenerator.generate({ model: "m", prompts: "techno" })
+      yield* MusicGenerator.generate({ model: "m", prompt: "techno" })
       yield* MusicGenerator.generate({
         model: "m",
-        prompts: [
-          { text: "synthwave", weight: 1.0 },
-          { text: "80s movie OST", weight: 0.4 },
-        ],
-        bpm: 120,
-        instrumental: true,
+        prompt: "synthwave",
+        duration: Duration.seconds(45),
+        seed: 42,
       })
       return yield* mock.recorder
     })
     const rec = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
     expect(rec.generateCalls.length).toBe(2)
-    expect(rec.generateCalls[1]!.bpm).toBe(120)
-    expect(rec.generateCalls[1]!.instrumental).toBe(true)
-    expect(Array.isArray(rec.generateCalls[1]!.prompts)).toBe(true)
+    expect(rec.generateCalls[1]!.duration).toEqual(Duration.seconds(45))
+    expect(rec.generateCalls[1]!.seed).toBe(42)
   })
 })
 
@@ -66,7 +93,7 @@ describe("MusicGenerator.streamGeneration", () => {
       streamGenerationChunks: [[chunk(1), chunk(2), chunk(3)]],
     })
     const program = Stream.runCollect(
-      MusicGenerator.streamGeneration({ model: "m", prompts: "ambient" }),
+      MusicGenerator.streamGeneration({ model: "m", prompt: "ambient" }),
     )
     const out = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
     expect(out.map((c) => Array.from(c.bytes))).toEqual([[1], [2], [3]])
@@ -76,15 +103,15 @@ describe("MusicGenerator.streamGeneration", () => {
 describe("MusicGenerator capability marker (compile-time)", () => {
   const sgfReq: MusicGenerator.CommonStreamGenerateMusicRequest = {
     model: "m",
-    prompts: "",
+    prompt: "",
   }
 
   it("requires `MusicInteractiveSession` on the R channel of streamGenerationFrom", () => {
     const inputs = Stream.fromIterable([promptsInput([{ text: "techno" }])])
-    const audio = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
-    expectTypeOf(audio).toEqualTypeOf<
+    const events = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
+    expectTypeOf(events).toEqualTypeOf<
       Stream.Stream<
-        AudioChunk,
+        MusicStreamEvent,
         AiError.AiError,
         MusicGenerator.MusicGenerator | MusicGenerator.MusicInteractiveSession
       >
@@ -92,14 +119,14 @@ describe("MusicGenerator capability marker (compile-time)", () => {
   })
 
   it("does NOT require `MusicInteractiveSession` for sync `generate`", () => {
-    const eff = MusicGenerator.generate({ model: "m", prompts: "ambient" })
+    const eff = MusicGenerator.generate({ model: "m", prompt: "ambient" })
     expectTypeOf(eff).toEqualTypeOf<
-      Effect.Effect<MusicResult, AiError.AiError, MusicGenerator.MusicGenerator>
+      Effect.Effect<GenerateResult, AiError.AiError, MusicGenerator.MusicGenerator>
     >()
   })
 
   it("does NOT require `MusicInteractiveSession` for `streamGeneration`", () => {
-    const audio = MusicGenerator.streamGeneration({ model: "m", prompts: "ambient" })
+    const audio = MusicGenerator.streamGeneration({ model: "m", prompt: "ambient" })
     expectTypeOf(audio).toEqualTypeOf<
       Stream.Stream<AudioChunk, AiError.AiError, MusicGenerator.MusicGenerator>
     >()
@@ -108,8 +135,8 @@ describe("MusicGenerator capability marker (compile-time)", () => {
   it("a layer without the marker leaves `MusicInteractiveSession` unsatisfied in R", () => {
     const noMarker = MockMusicGenerator.layerWithoutInteractive({})
     const inputs = Stream.fromIterable([promptsInput([{ text: "techno" }])])
-    const audio = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
-    const program = Stream.runDrain(audio).pipe(Effect.provide(noMarker.layer))
+    const events = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
+    const program = Stream.runDrain(events).pipe(Effect.provide(noMarker.layer))
     expectTypeOf(program).toEqualTypeOf<
       Effect.Effect<void, AiError.AiError, MusicGenerator.MusicInteractiveSession>
     >()
@@ -117,53 +144,51 @@ describe("MusicGenerator capability marker (compile-time)", () => {
 
   it("a full layer (with marker) clears R to never", () => {
     const fullMock = MockMusicGenerator.layer({
-      streamGenerationFromChunks: [[]],
+      streamGenerationFromEvents: [[]],
     })
     const inputs = Stream.fromIterable([promptsInput([{ text: "techno" }])])
-    const audio = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
-    const program = Stream.runDrain(audio).pipe(Effect.provide(fullMock.layer))
+    const events = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
+    const program = Stream.runDrain(events).pipe(Effect.provide(fullMock.layer))
     expectTypeOf(program).toEqualTypeOf<Effect.Effect<void, AiError.AiError, never>>()
   })
 })
 
 describe("MusicGenerator.streamGenerationFrom", () => {
   const sgfReq: MusicGenerator.CommonStreamGenerateMusicRequest = {
-    model: "lyria-realtime-001",
-    prompts: "",
+    model: "lyria-realtime-exp",
+    prompt: "",
   }
 
-  it("drains a session-input stream and emits scripted audio", async () => {
+  it("drains a session-input stream and emits scripted events", async () => {
     const mock = MockMusicGenerator.layer({
-      streamGenerationFromChunks: [[chunk(10), chunk(20)]],
+      streamGenerationFromEvents: [[audioEvent(chunk(10)), audioEvent(chunk(20))]],
     })
     const inputs = Stream.fromIterable([
       promptsInput([{ text: "minimal techno", weight: 1.0 }]),
-      configInput({ bpm: 124 }),
+      controlInput("play"),
       promptsInput([
         { text: "minimal techno", weight: 1.0 },
         { text: "1980s synthwave", weight: 0.3 },
       ]),
     ])
-    const audio = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
-    const out = await Effect.runPromise(Stream.runCollect(audio).pipe(Effect.provide(mock.layer)))
-    expect(out.map((c) => Array.from(c.bytes))).toEqual([[10], [20]])
+    const events = inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq))
+    const out = await Effect.runPromise(Stream.runCollect(events).pipe(Effect.provide(mock.layer)))
+    const audioChunks = out.flatMap((e) => (e._tag === "audio" ? [e.chunk] : []))
+    expect(audioChunks.map((c) => Array.from(c.bytes))).toEqual([[10], [20]])
   })
 
   it("records the request on the streamGenerationFrom call channel", async () => {
     const mock = MockMusicGenerator.layer({
-      streamGenerationFromChunks: [[chunk(42)]],
+      streamGenerationFromEvents: [[audioEvent(chunk(42))]],
     })
     const program = Effect.gen(function* () {
-      yield* Stream.runDrain(
-        Stream.fromIterable([promptsInput([{ text: "x" }])]).pipe(
-          MusicGenerator.streamGenerationFrom(sgfReq),
-        ),
-      )
+      const inputs = Stream.fromIterable([promptsInput([{ text: "x" }])])
+      yield* Stream.runDrain(inputs.pipe(MusicGenerator.streamGenerationFrom(sgfReq)))
       return yield* mock.recorder
     })
     const rec = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
     expect(rec.streamGenerationFromCalls.length).toBe(1)
-    expect(rec.streamGenerationFromCalls[0]!.model).toBe("lyria-realtime-001")
+    expect(rec.streamGenerationFromCalls[0]!.model).toBe("lyria-realtime-exp")
     expect(rec.generateCalls.length).toBe(0)
     expect(rec.streamGenerationCalls.length).toBe(0)
   })

package/src/music-generator/MusicGenerator.ts

@@ -1,18 +1,24 @@
 import { Context, Effect, Function, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
-import type { AudioChunk } from "../domain/Audio.js"
 import type {
   CommonGenerateMusicRequest,
   CommonStreamGenerateMusicRequest,
-  MusicResult,
+  GenerateResult,
   MusicSessionInput,
+  MusicStreamEvent,
 } from "../domain/Music.js"
+import type { AudioChunk } from "../domain/Audio.js"
 
 export type {
   CommonGenerateMusicRequest,
   CommonStreamGenerateMusicRequest,
+  GenerateResult,
   MusicResult,
+  MusicSection,
+  MusicSessionControl,
   MusicSessionInput,
+  MusicStreamEvent,
+  Watermark,
   WeightedPrompt,
 } from "../domain/Music.js"
 
@@ -20,35 +26,50 @@ export type MusicGeneratorService = {
   /**
    * One-shot. Prompt in, full audio bytes out. Universally supported.
    * Async/poll-based providers (Suno, Mureka) hide their poll loop
-   * inside the adapter — caller still sees a single `Effect`.
+   * inside the adapter, caller still sees a single `Effect`.
+   *
+   * Returns `GenerateResult` with `primary` plus a `variants` array.
+   * Suno and Mureka always return 2 tracks; every other provider
+   * returns 1 (and `primary === variants[0]`).
    */
   readonly generate: (
     request: CommonGenerateMusicRequest,
-  ) => Effect.Effect<MusicResult, AiError.AiError>
+  ) => Effect.Effect<GenerateResult, AiError.AiError>
   /**
    * Prompt in, audio chunks streamed out. Providers without a native
    * chunked-output endpoint (Lyria 3 sync, Mureka, MiniMax, Stable
    * Audio) emulate this by calling `generate` and emitting a single
-   * `AudioChunk` — first-class, no `Unsupported`.
+   * `AudioChunk`, first-class, no `Unsupported`.
    */
   readonly streamGeneration: (
     request: CommonStreamGenerateMusicRequest,
   ) => Stream.Stream<AudioChunk, AiError.AiError>
   /**
-   * Bidirectional session: a `Stream` of prompt-or-config updates flows
-   * in, a `Stream` of audio chunks flows out. The session WS / RPC is
-   * acquired on first pull and released when the output stream is
-   * finalized via `Stream.scoped`.
+   * Bidirectional session: a `Stream` of `MusicSessionInput` (prompts
+   * + playback control) flows in, a `Stream` of `MusicStreamEvent`
+   * flows out. The session WS / RPC is acquired on first pull and
+   * released when the output stream is finalized via `Stream.scoped`.
+   *
+   * Cross-provider callers send `prompts` (steer the active
+   * generation) and `control` (play / pause / stop / reset) — the two
+   * actions that converge across interactive-media protocols.
+   * Provider-specific model knobs (Lyria RealTime's density /
+   * brightness / mute-stems / BPM / scale, etc.) live on the
+   * provider-typed service (`LyriaRealtimeGenerator.streamGenerationFrom`),
+   * which extends this union with its own `config` variant.
+   *
+   * Output is `MusicStreamEvent`: `audio` chunks alongside in-band
+   * `warning` and `filteredPrompt` events the model emits server-side.
    *
    * Gated by the `MusicInteractiveSession` capability marker on the
-   * top-level helper — providers without bidirectional support don't
+   * top-level helper. Providers without bidirectional support don't
    * ship the marker, so calls fail at `Effect.provide` with a type
    * error.
    */
   readonly streamGenerationFrom: <E, R>(
     input: Stream.Stream<MusicSessionInput, E, R>,
     request: CommonStreamGenerateMusicRequest,
-  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+  ) => Stream.Stream<MusicStreamEvent, AiError.AiError | E, R>
 }
 
 export class MusicGenerator extends Context.Service<MusicGenerator, MusicGeneratorService>()(
@@ -56,23 +77,23 @@ export class MusicGenerator extends Context.Service<MusicGenerator, MusicGenerat
 ) {}
 
 /**
- * Capability marker — provided by provider layers whose
+ * Capability marker, provided by provider layers whose
  * `streamGenerationFrom` is wired up at the wire level. Currently only
  * Lyria RealTime (via the BidiGenerateMusic WebSocket) ships it.
  * Calling `streamGenerationFrom` while only a non-interactive Layer is
  * in scope fails at `Effect.provide` with a type error.
  *
- * Phantom — the value is `void`; providers register with
+ * Phantom: the value is `void`; providers register with
  * `Layer.succeed(MusicInteractiveSession, undefined)`.
  */
 export class MusicInteractiveSession extends Context.Service<MusicInteractiveSession, void>()(
   "@betalyra/effect-uai/capability/MusicInteractiveSession",
 ) {}
 
-/** One-shot generation. */
+/** One-shot generation. Returns the full `GenerateResult`. */
 export const generate = (
   request: CommonGenerateMusicRequest,
-): Effect.Effect<MusicResult, AiError.AiError, MusicGenerator> =>
+): Effect.Effect<GenerateResult, AiError.AiError, MusicGenerator> =>
   Effect.flatMap(MusicGenerator.asEffect(), (s) => s.generate(request))
 
 /** Prompt in, audio chunks out. */
@@ -83,17 +104,25 @@ export const streamGeneration = (
 
 /**
  * Bidirectional generation. Dual-arity: pipeable (data-last) and
- * direct (data-first). Requires `MusicInteractiveSession` in R —
+ * direct (data-first). Requires `MusicInteractiveSession` in R,
  * providers without bidirectional support are a type error at provide
  * time.
  *
+ * On the cross-provider surface, `input` is `Stream<unknown>` and
+ * output is `Stream<MusicStreamEvent>`. Use the provider-typed
+ * service (`LyriaRealtimeGenerator`) when you want to construct
+ * typed session messages.
+ *
  * @example
  * ```ts
- * const audio = Stream.fromIterable([
- *   Music.promptsInput([{ text: "minimal techno", weight: 1.0 }]),
- *   Music.configInput({ bpm: 124 }),
- * ]).pipe(
- *   MusicGenerator.streamGenerationFrom({ model: "lyria-realtime-001", prompts: "" }),
+ * // Generic surface (opaque input):
+ * const audio = inputs.pipe(
+ *   MusicGenerator.streamGenerationFrom({ model: "lyria-realtime-exp", prompt: "" }),
+ * )
+ *
+ * // Lyria-typed surface (full config knobs):
+ * const audio = inputs.pipe(
+ *   LyriaRealtimeGenerator.streamGenerationFrom({ model: "lyria-realtime-exp", prompt: "" }),
  * )
  * ```
  */
@@ -102,17 +131,29 @@ export const streamGenerationFrom: {
     request: CommonStreamGenerateMusicRequest,
   ): <E, R>(
     input: Stream.Stream<MusicSessionInput, E, R>,
-  ) => Stream.Stream<AudioChunk, AiError.AiError | E, R | MusicGenerator | MusicInteractiveSession>
+  ) => Stream.Stream<
+    MusicStreamEvent,
+    AiError.AiError | E,
+    R | MusicGenerator | MusicInteractiveSession
+  >
   <E, R>(
     input: Stream.Stream<MusicSessionInput, E, R>,
     request: CommonStreamGenerateMusicRequest,
-  ): Stream.Stream<AudioChunk, AiError.AiError | E, R | MusicGenerator | MusicInteractiveSession>
+  ): Stream.Stream<
+    MusicStreamEvent,
+    AiError.AiError | E,
+    R | MusicGenerator | MusicInteractiveSession
+  >
 } = Function.dual(
   2,
   <E, R>(
     input: Stream.Stream<MusicSessionInput, E, R>,
     request: CommonStreamGenerateMusicRequest,
-  ) =>
+  ): Stream.Stream<
+    MusicStreamEvent,
+    AiError.AiError | E,
+    R | MusicGenerator | MusicInteractiveSession
+  > =>
     Stream.unwrap(
       Effect.gen(function* () {
         const s = yield* MusicGenerator.asEffect()

package/src/speech-synthesizer/SpeechSynthesizer.test.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream } from "effect"
+import { Duration, Effect, Stream } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as AiError from "../domain/AiError.js"
 import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
@@ -14,7 +14,7 @@ const pcmFormat: AudioFormat = {
 const blob: AudioBlob = {
   format: pcmFormat,
   bytes: new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
-  durationSeconds: 0.5,
+  duration: Duration.millis(500),
 }
 
 const chunk = (n: number): AudioChunk => ({ bytes: new Uint8Array([n]) })
@@ -29,7 +29,7 @@ describe("SpeechSynthesizer.synthesize", () => {
     })
     const result = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
     expect(result.bytes).toEqual(blob.bytes)
-    expect(result.durationSeconds).toBe(0.5)
+    expect(result.duration).toEqual(Duration.millis(500))
   })
 })
 

package/src/speech-synthesizer/SpeechSynthesizer.ts

@@ -3,31 +3,20 @@ import * as AiError from "../domain/AiError.js"
 import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
 
 /**
- * Phonetic alphabets accepted by `CustomPronunciation`. Not every
- * provider supports every alphabet — adapters translate or warn+drop
- * unsupported entries.
+ * Per-phrase pronunciation override. `pronunciation` is always IPA, the
+ * universal phonetic interchange format. Adapters translate to the
+ * provider's wire form (inline `/ipa/` token, SSML `<phoneme>`, or a
+ * structured field), converting IPA to X-SAMPA internally where the wire
+ * requires it (Google, Azure).
  *
- * - `ipa` — universal lowest common denominator (Google, ElevenLabs,
- *   Inworld, Deepgram, Cartesia, MiniMax).
- * - `x-sampa` — Google Cloud TTS.
- * - `cmu-arpabet` — ElevenLabs `eleven_flash_v2` / `eleven_english_v1`.
- */
-export type PhoneticEncoding = "ipa" | "x-sampa" | "cmu-arpabet"
-
-/**
- * Per-phrase pronunciation override. The same shape unifies the
- * structured-field providers (Google) and the inline-markup providers
- * (ElevenLabs SSML, Inworld `/ipa/`, Deepgram, Cartesia, MiniMax) — the
- * adapter does the wire translation.
- *
- * Unsupported alphabets are dropped at the adapter with a structured
- * `logWarning` (one per call). The audio still renders, just without
- * the override.
+ * Pronunciations are load-bearing (the configured word is mispronounced
+ * if dropped), so a provider with no stateless IPA path fails the call
+ * with `AiError.Unsupported` rather than silently degrading.
  */
 export type CustomPronunciation = {
   readonly phrase: string
+  /** IPA notation, e.g. `"ænˈθrɒpɪk"`. */
   readonly pronunciation: string
-  readonly encoding: PhoneticEncoding
 }
 
 /**
@@ -52,11 +41,10 @@ export type CommonSynthesizeRequest = {
   readonly speed?: number
   readonly languageCode?: string
   /**
-   * Phoneme overrides for specific phrases. 7 of 9 TTS providers
-   * support some form of this; adapters either translate to a
-   * structured field, rewrite `text` inline, or `warn+drop` per-entry
-   * for alphabets they don't accept. OpenAI rejects non-empty arrays
-   * with `Unsupported`.
+   * IPA phoneme overrides for specific phrases. Adapters render them to
+   * the provider's wire form (inline token, SSML `<phoneme>`, structured
+   * field). Load-bearing: a provider with no stateless IPA path fails
+   * the call with `AiError.Unsupported` rather than mispronouncing.
    */
   readonly pronunciations?: ReadonlyArray<CustomPronunciation>
 }
@@ -73,18 +61,15 @@ export type CommonSynthesizeRequest = {
 export type CommonStreamSynthesizeRequest = Omit<CommonSynthesizeRequest, "text">
 
 /**
- * One turn in a multi-speaker dialogue.
- *
- * `styleDescription` and `speed` are honored by providers that expose
- * per-turn knobs (Hume Octave-2) and silently ignored by others
- * (ElevenLabs `/v1/text-to-dialogue` accepts `{voice_id, text}` only;
- * Google Gemini TTS multi-speaker has no per-turn styling).
+ * One turn in a multi-speaker dialogue. Just a voice and its line; the
+ * only in-tree dialogue endpoint (ElevenLabs `/v1/text-to-dialogue`)
+ * accepts `{ voice_id, text }` per turn. Per-turn styling knobs
+ * (Hume Octave-2 `styleDescription` / `speed`) are provider-specific
+ * and belong on a provider-typed turn extension, not here.
  */
 export type DialogueTurn = {
   readonly voiceId: string
   readonly text: string
-  readonly styleDescription?: string
-  readonly speed?: number
 }
 
 /**

package/src/testing/MockMusicGenerator.ts

@@ -1,11 +1,13 @@
 import { Effect, Layer, Ref, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
 import type { AudioChunk } from "../domain/Audio.js"
-import type {
-  CommonGenerateMusicRequest,
-  CommonStreamGenerateMusicRequest,
-  MusicResult,
-  MusicSessionInput,
+import {
+  audioEvent,
+  type CommonGenerateMusicRequest,
+  type CommonStreamGenerateMusicRequest,
+  type GenerateResult,
+  type MusicSessionInput,
+  type MusicStreamEvent,
 } from "../domain/Music.js"
 import {
   MusicGenerator,
@@ -21,11 +23,15 @@ export type MockMusicGeneratorRecorder = {
 
 export type MockMusicGeneratorScript = {
   /** One result per `generate` call, consumed in order. */
-  readonly results?: ReadonlyArray<MusicResult>
+  readonly results?: ReadonlyArray<GenerateResult>
   /** One chunk-list per `streamGeneration` call, consumed in order. */
   readonly streamGenerationChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
-  /** One chunk-list per `streamGenerationFrom` call, consumed in order. */
-  readonly streamGenerationFromChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
+  /**
+   * One event-list per `streamGenerationFrom` call, consumed in order.
+   * If a list contains only `AudioChunk`s for ergonomics, wrap them in
+   * `audioEvent(chunk)` first.
+   */
+  readonly streamGenerationFromEvents?: ReadonlyArray<ReadonlyArray<MusicStreamEvent>>
 }
 
 const makeService = (
@@ -74,22 +80,23 @@ const makeService = (
       streamGenerationFrom: <E, R>(
         input: Stream.Stream<MusicSessionInput, E, R>,
         request: CommonStreamGenerateMusicRequest,
-      ): Stream.Stream<AudioChunk, AiError.AiError | E, R> =>
+      ): Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> =>
         Stream.unwrap(
           Effect.gen(function* () {
             yield* record.streamGenerationFrom(request)
             const i = yield* Ref.getAndUpdate(sgfCursor, (n) => n + 1)
-            const scripted = script.streamGenerationFromChunks ?? []
+            const scripted = script.streamGenerationFromEvents ?? []
             if (i >= scripted.length) {
-              const exhausted: Stream.Stream<AudioChunk, AiError.AiError | E, R> = Stream.fail(
-                new AiError.InvalidRequest({
-                  provider: "mock",
-                  raw: `MockMusicGenerator exhausted: ${scripted.length} streamGenerationFrom lists scripted, but call ${i + 1} was made`,
-                }),
-              )
+              const exhausted: Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> =
+                Stream.fail(
+                  new AiError.InvalidRequest({
+                    provider: "mock",
+                    raw: `MockMusicGenerator exhausted: ${scripted.length} streamGenerationFrom lists scripted, but call ${i + 1} was made`,
+                  }),
+                )
               return exhausted
             }
-            // Drain the input fully before emitting scripted audio chunks,
+            // Drain the input fully before emitting scripted events,
             // so consumers can assert on what session messages were pushed.
             return Stream.drain(input).pipe(Stream.concat(Stream.fromIterable(scripted[i]!)))
           }),
@@ -133,7 +140,7 @@ export const layer = (
 }
 
 /**
- * Variant that omits the `MusicInteractiveSession` marker — simulates a
+ * Variant that omits the `MusicInteractiveSession` marker, simulates a
  * provider without bidirectional support (Lyria 3 sync, ElevenLabs,
  * Mureka, MiniMax, Stable Audio, Suno). Calls to
  * `streamGenerationFrom` in code under test should be a compile-time
@@ -166,3 +173,6 @@ export const layerWithoutInteractive = (
     }),
   }
 }
+
+// Re-export the event constructor for test-script ergonomics.
+export { audioEvent }

package/src/transcriber/Transcriber.test.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream } from "effect"
+import { Duration, Effect, Stream } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as AiError from "../domain/AiError.js"
 import type { TranscriptEvent, TranscriptResult } from "../domain/Transcript.js"
@@ -8,7 +8,7 @@ import * as Transcriber from "./Transcriber.js"
 describe("Transcriber.transcribe", () => {
   it("returns the scripted TranscriptResult", async () => {
     const mock = MockTranscriber.layer({
-      transcripts: [{ text: "hello world", durationSeconds: 1.23 }],
+      transcripts: [{ text: "hello world", duration: Duration.seconds(1.23) }],
     })
     const program = Transcriber.transcribe({
       audio: { _tag: "bytes", bytes: new Uint8Array([0]), mimeType: "audio/wav" },
@@ -16,7 +16,7 @@ describe("Transcriber.transcribe", () => {
     })
     const result = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
     expect(result.text).toBe("hello world")
-    expect(result.durationSeconds).toBe(1.23)
+    expect(result.duration).toStrictEqual(Duration.seconds(1.23))
   })
 
   it("records each transcribe call", async () => {