@speech-sdk/core 0.5.2 → 0.6.1

package/README.md

@@ -42,6 +42,23 @@ result.audio.base64;      // string (lazy-computed)
 result.audio.mediaType;   // "audio/mpeg"
 ```
 
+### Volume normalization
+
+Pass `volumeDbfs` to RMS-normalize the output to an absolute target loudness (must be ≤ 0; lower is quieter; -20 is the broadcast/podcast voice convention with ~20 dB of peak headroom):
+
+```ts
+const result = await generateSpeech({
+  model: 'openai/gpt-4o-mini-tts',
+  text: 'Hello from speech-sdk!',
+  voice: 'alloy',
+  volumeDbfs: -20,
+});
+
+result.audio.mediaType;   // "audio/wav" — re-encoded after normalization
+```
+
+When `volumeDbfs` is set the SDK transparently asks the provider for its decodable PCM/WAV mode, normalizes the samples, and returns 16-bit mono WAV — so the response `mediaType` switches to `audio/wav` regardless of the provider's native default. Throws `VolumeAdjustmentUnsupportedError` if the provider has no decodable output mode.
+
 ## Streaming
 
 Use `streamSpeech()` instead of `generateSpeech()` to receive audio bytes incrementally as the provider produces them. The result's `audio` field is a standard `ReadableStream<Uint8Array>` that works in Node, Edge runtimes, and browsers.
@@ -117,6 +134,93 @@ Calling `streamSpeech()` on a model that doesn't declare the `"streaming"` featu
 
 Retries apply only to the initial request, until response headers arrive. Once bytes start flowing, mid-stream errors propagate to the `ReadableStream` consumer as a stream error and are not retried. Pass `maxRetries` (default `2`) and an `abortSignal` the same way as `generateSpeech()`.
 
+## Conversations
+
+`generateConversation()` produces a single multi-voice audio clip from an ordered array of turns. It picks the best path automatically:
+
+- **Native dialogue** — when every turn shares one model and that provider has a real multi-speaker dialogue endpoint, the SDK makes a single API call and returns the provider's natural mix. Works with **ElevenLabs v3**, **Google Gemini TTS** (exactly 2 voices), **Hume Octave**, **Fish Audio S2-Pro**, and **fal Dia**.
+- **Stitch fallback** — when turns span multiple providers, or the chosen model has no native dialogue endpoint, the SDK calls `generateSpeech()` per turn in parallel, normalizes each result to PCM, RMS-levels them so quieter providers don't get drowned out, inserts a configurable silence between turns, and returns a single WAV.
+
+```ts
+import { generateConversation } from "@speech-sdk/core/conversation";
+
+const result = await generateConversation({
+  turns: [
+    { model: "openai/tts-1", voice: "nova", text: "Hi, I'm hosted by OpenAI." },
+    { model: "elevenlabs/eleven_multilingual_v2", voice: "JBFqnCBsd6RMkjVDRZzb", text: "And I'm hosted by ElevenLabs." },
+    { model: "google/gemini-3.1-flash-tts-preview", voice: "Kore", text: "I'm Gemini three-point-one flash TTS." },
+    { model: "hume/octave-2", voice: "Kora", text: "And I'm Hume Octave. Thanks for listening." },
+  ],
+});
+
+result.audio.uint8Array;  // Uint8Array of one combined WAV
+result.audio.mediaType;   // "audio/wav"
+```
+
+The return type is the standard `SpeechResult`, so it composes with everything else in the SDK.
+
+### Conversation options
+
+```ts
+generateConversation({
+  model?: string | ResolvedModel,                 // default model for all turns
+  turns: ConversationTurn[],                      // 1..N turns; up to 4 unique voices
+  gapMs?: number,                                 // silence between turns (stitch path), default 300
+  normalizeVolume?: boolean,                      // RMS-level the output, default true
+  volumeDbfs?: number,                            // RMS target loudness in dBFS (≤0), default -20
+  maxConcurrency?: number,                        // cap parallel generateSpeech calls, default 6
+  maxRetries?: number,                            // per-turn retries, default 2
+  apiKey?: string,
+  providerOptions?: Record<string, unknown>,      // forwarded to every provider; per-turn override available
+  abortSignal?: AbortSignal,
+  headers?: Record<string, string>,
+});
+
+interface ConversationTurn {
+  voice: Voice;                                   // required
+  text: string;                                   // required, non-empty
+  model?: string | ResolvedModel;                 // per-turn override of the top-level model
+  providerOptions?: Record<string, unknown>,
+}
+```
+
+### Volume normalization
+
+`normalizeVolume: true` (the default) RMS-normalizes the output to an absolute target loudness — broadcast/podcast voice convention — so two `generateConversation` calls produce comparable levels regardless of provider mix or content. The target defaults to **−20 dBFS** (~20 dB of peak headroom), and is configurable via `volumeDbfs` (must be ≤ 0; lower is quieter).
+
+```ts
+await generateConversation({
+  turns: [...],
+  volumeDbfs: -16,           // a touch louder than the default
+});
+```
+
+Normalization runs on **both paths** — stitched multi-provider conversations and single-provider native dialogue. On the native path the SDK transparently asks the provider for its decodable PCM/WAV mode (via `getStitchOptions`), levels the result, and re-encodes as 16-bit mono WAV — so the response `mediaType` becomes `audio/wav` whenever normalization runs. If a native dialogue provider can't emit decodable audio, the request still succeeds but a `warning` is appended explaining that volume normalization was skipped.
+
+Pass `normalizeVolume: false` to skip normalization entirely (zero work) and keep the raw provider audio bytes and `mediaType` untouched.
+
+### Errors
+
+Conversation-specific errors (importable from `@speech-sdk/core/conversation/errors`):
+
+| Error | When |
+|---|---|
+| `ConversationInputError` | Validation failure — empty turns, blank text, more than 4 unique voices, or a turn missing a model |
+| `DialogueConstraintError` | A native-dialogue provider was selected but the conversation violates its constraints (e.g. 3 voices on Gemini, which requires exactly 2) |
+| `StitchUnsupportedError` | The stitch path was selected but a chosen provider/model can't emit PCM/WAV |
+
+### Native dialogue caps
+
+| Provider | Native dialogue model | Voice constraints |
+|---|---|---|
+| ElevenLabs | `eleven_v3` | 1–10 voices, ≤ 2,000 total chars |
+| Google | `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`, `gemini-3.1-flash-tts-preview` | **Exactly 2 voices** (API requirement) |
+| Hume | `octave-1`, `octave-2` | 1–4 voices |
+| Fish Audio | `s2-pro` | 1–4 voices |
+| fal | `dia-tts` | 1–2 voices |
+
+Across the SDK, conversations are capped at **4 unique voices** total regardless of provider.
+
 ## Supported Providers
 
 Use `provider/model` strings. Passing just the provider name uses its default model.
@@ -131,7 +235,6 @@ Use `provider/model` strings. Passing just the provider name uses its default mo
 | [Inworld](https://docs.inworld.ai/tts) | `inworld` | `inworld-tts-1.5-max` | `INWORLD_API_KEY` | [API Reference](https://docs.inworld.ai/tts/api-reference) |
 | [Google (Gemini TTS)](https://docs.cloud.google.com/text-to-speech/docs/gemini-tts) | `google` | `gemini-2.5-flash-preview-tts` | `GOOGLE_API_KEY` | [API Reference](https://ai.google.dev/gemini-api/docs/text-generation) |
 | [Fish Audio](https://docs.fish.audio) | `fish-audio` | `s2-pro` | `FISH_AUDIO_API_KEY` | [API Reference](https://docs.fish.audio/developer-guide/core-features/text-to-speech) |
-| [Unreal Speech](https://docs.v8.unrealspeech.com) | `unreal-speech` | `default` | `UNREAL_SPEECH_API_KEY` | [API Reference](https://docs.v8.unrealspeech.com) |
 | [Murf](https://murf.ai/api/docs) | `murf` | `GEN2` | `MURF_API_KEY` | [API Reference](https://murf.ai/api/docs/api-reference/text-to-speech/generate) |
 | [Resemble](https://docs.resemble.ai) | `resemble` | `default` | `RESEMBLE_API_KEY` | [API Reference](https://docs.resemble.ai/api-reference/text-to-speech/synthesize) |
 | [fal](https://fal.ai/models) | `fal-ai` | *(user-specified)* | `FAL_API_KEY` | [API Reference](https://fal.ai/models) |
@@ -304,6 +407,12 @@ pnpm run typecheck              # type-check without emitting
 
 E2E tests hit real provider APIs. Set the relevant API key environment variables in a `.env` file or export them in your shell.
 
+Set `SPEECH_SDK_E2E_OUTPUT_DIR` to have the conversation e2e tests write their generated audio to disk (useful for sampling/comparing provider output):
+
+```bash
+SPEECH_SDK_E2E_OUTPUT_DIR=~/Downloads/convos pnpm run test:e2e
+```
+
 ## License
 
 MIT

package/dist/__tests__/e2e/_save-audio.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Write a test-generated audio file to `SPEECH_SDK_E2E_OUTPUT_DIR` if the env
+ * var is set. No-op otherwise, so normal CI runs don't produce artifacts.
+ * Intended to let conversation e2e tests double as a way to sample provider
+ * output (e.g. `SPEECH_SDK_E2E_OUTPUT_DIR=~/Downloads/convos pnpm test:e2e`).
+ */
+export declare function maybeSaveAudio(name: string, audio: {
+    uint8Array: Uint8Array;
+    mediaType: string;
+}): Promise<void>;
+//# sourceMappingURL=_save-audio.d.ts.map

package/dist/__tests__/e2e/_save-audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_save-audio.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/_save-audio.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/__tests__/e2e/_save-audio.js

@@ -0,0 +1,43 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+function extFor(mediaType) {
+    if (mediaType.includes("wav")) {
+        return "wav";
+    }
+    if (mediaType.includes("mpeg") || mediaType.includes("mp3")) {
+        return "mp3";
+    }
+    if (mediaType.includes("ogg")) {
+        return "ogg";
+    }
+    if (mediaType.includes("flac")) {
+        return "flac";
+    }
+    if (mediaType.includes("opus")) {
+        return "opus";
+    }
+    if (mediaType.includes("pcm")) {
+        return "pcm";
+    }
+    return "bin";
+}
+/**
+ * Write a test-generated audio file to `SPEECH_SDK_E2E_OUTPUT_DIR` if the env
+ * var is set. No-op otherwise, so normal CI runs don't produce artifacts.
+ * Intended to let conversation e2e tests double as a way to sample provider
+ * output (e.g. `SPEECH_SDK_E2E_OUTPUT_DIR=~/Downloads/convos pnpm test:e2e`).
+ */
+export async function maybeSaveAudio(name, audio) {
+    const dir = process.env.SPEECH_SDK_E2E_OUTPUT_DIR;
+    if (!dir) {
+        return;
+    }
+    const expanded = dir.startsWith("~")
+        ? join(process.env.HOME ?? "", dir.slice(1))
+        : dir;
+    await mkdir(expanded, { recursive: true });
+    const file = join(expanded, `${name}.${extFor(audio.mediaType)}`);
+    await writeFile(file, audio.uint8Array);
+    console.log(`[maybeSaveAudio] wrote ${file}`);
+}
+//# sourceMappingURL=_save-audio.js.map

package/dist/__tests__/e2e/_save-audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_save-audio.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/_save-audio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,SAAS,MAAM,CAAC,SAAiB;IAC/B,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,KAAoD;IAEpD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAClD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAClC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,GAAG,CAAC;IACR,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/audio-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse a numeric parameter from a mediaType string (e.g. "audio/pcm;rate=24000").
+ * Returns undefined if missing or non-positive.
+ */
+export declare function parseMediaTypeParam(mediaType: string, name: string): number | undefined;
+/**
+ * Wrap raw 16-bit little-endian mono PCM bytes in a WAV container.
+ * Cross-platform (browser, Node, edge) via mediabunny's container ops —
+ * does not require the WebCodecs encoder.
+ */
+export declare function wrapPcm16Mono(pcm: Uint8Array, sampleRate: number): Promise<Uint8Array>;
+//# sourceMappingURL=audio-utils.d.ts.map

package/dist/audio-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-utils.d.ts","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAcpB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CA2BrB"}

package/dist/audio-utils.js

@@ -0,0 +1,53 @@
+import { BufferTarget, EncodedAudioPacketSource, EncodedPacket, Output, WavOutputFormat, } from "mediabunny";
+const PARAM_REGEX_CACHE = new Map();
+/**
+ * Parse a numeric parameter from a mediaType string (e.g. "audio/pcm;rate=24000").
+ * Returns undefined if missing or non-positive.
+ */
+export function parseMediaTypeParam(mediaType, name) {
+    let re = PARAM_REGEX_CACHE.get(name);
+    if (!re) {
+        // End boundary required: digits must be followed by ;, whitespace, or
+        // end-of-string. Rejects values like "rate=24000x".
+        re = new RegExp(`(?:^|;)\\s*${name}=(\\d+)(?=$|;|\\s)`, "i");
+        PARAM_REGEX_CACHE.set(name, re);
+    }
+    const match = mediaType.match(re);
+    if (!match) {
+        return undefined;
+    }
+    const value = Number(match[1]);
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/**
+ * Wrap raw 16-bit little-endian mono PCM bytes in a WAV container.
+ * Cross-platform (browser, Node, edge) via mediabunny's container ops —
+ * does not require the WebCodecs encoder.
+ */
+export async function wrapPcm16Mono(pcm, sampleRate) {
+    const output = new Output({
+        format: new WavOutputFormat(),
+        target: new BufferTarget(),
+    });
+    const source = new EncodedAudioPacketSource("pcm-s16");
+    output.addAudioTrack(source);
+    await output.start();
+    // 2 bytes per sample, mono.
+    const numSamples = pcm.length / 2;
+    const durationSeconds = numSamples / sampleRate;
+    const packet = new EncodedPacket(pcm, "key", 0, durationSeconds, 0);
+    await source.add(packet, {
+        decoderConfig: {
+            codec: "pcm-s16",
+            numberOfChannels: 1,
+            sampleRate,
+        },
+    });
+    await output.finalize();
+    const buffer = output.target.buffer;
+    if (!buffer) {
+        throw new Error("audio-utils: WavOutputFormat produced no buffer");
+    }
+    return new Uint8Array(buffer);
+}
+//# sourceMappingURL=audio-utils.js.map

package/dist/audio-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-utils.js","sourceRoot":"","sources":["../src/audio-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,aAAa,EACb,MAAM,EACN,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,IAAY;IAEZ,IAAI,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,sEAAsE;QACtE,oDAAoD;QACpD,EAAE,GAAG,IAAI,MAAM,CAAC,cAAc,IAAI,oBAAoB,EAAE,GAAG,CAAC,CAAC;QAC7D,iBAAiB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAe,EACf,UAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,MAAM,EAAE,IAAI,eAAe,EAAE;QAC7B,MAAM,EAAE,IAAI,YAAY,EAAE;KAC3B,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,4BAA4B;IAC5B,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,MAAM,eAAe,GAAG,UAAU,GAAG,UAAU,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE;QACvB,aAAa,EAAE;YACb,KAAK,EAAE,SAAS;YAChB,gBAAgB,EAAE,CAAC;YACnB,UAAU;SACX;KACF,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC"}

package/dist/conversation/dispatch.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedModel, Voice } from "../speech-provider.js";
+import type { ConversationTurn } from "./types.js";
+export type ConversationPath = {
+    kind: "native";
+    resolved: ResolvedModel<Voice>;
+} | {
+    kind: "stitch";
+    stitchOptionsPerTurn: readonly {
+        providerOptions: Record<string, unknown>;
+        mediaType: string;
+    }[];
+};
+export declare function chooseConversationPath(input: {
+    resolvedPerTurn: readonly ResolvedModel<Voice>[];
+    turns: readonly ConversationTurn<Voice>[];
+}): ConversationPath;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/conversation/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/conversation/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAAE,GAClD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,oBAAoB,EAAE,SAAS;QAC7B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC;KACnB,EAAE,CAAC;CACL,CAAC;AAEN,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,eAAe,EAAE,SAAS,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IACjD,KAAK,EAAE,SAAS,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;CAC3C,GAAG,gBAAgB,CAkCnB"}

package/dist/conversation/dispatch.js

@@ -0,0 +1,60 @@
+import { DialogueConstraintError, StitchUnsupportedError } from "./errors.js";
+import { newVoiceKeyContext, voiceKey } from "./validate.js";
+export function chooseConversationPath(input) {
+    const { resolvedPerTurn, turns } = input;
+    // Compare by provider instance reference, not just provider id, so two
+    // factories of the same provider with different apiKey/baseURL/fetch
+    // configs are not silently merged into one.
+    const first = resolvedPerTurn[0];
+    const allSame = resolvedPerTurn.every((r) => r.provider === first.provider && r.modelId === first.modelId);
+    if (allSame) {
+        const { provider, modelId } = first;
+        if (provider.generateDialogue && provider.dialogueCapabilities) {
+            const caps = provider.dialogueCapabilities(modelId);
+            if (caps) {
+                assertNativeConstraints({ provider, modelId, caps, turns });
+                return { kind: "native", resolved: first };
+            }
+        }
+    }
+    // Stitch path — every resolved (provider, modelId) must support getStitchOptions.
+    const stitchOptionsPerTurn = resolvedPerTurn.map((r) => {
+        const opts = r.provider.getStitchOptions?.(r.modelId);
+        if (!opts) {
+            throw new StitchUnsupportedError({
+                provider: r.provider.id,
+                model: r.modelId,
+            });
+        }
+        return opts;
+    });
+    return { kind: "stitch", stitchOptionsPerTurn };
+}
+function assertNativeConstraints(args) {
+    const { provider, modelId, caps, turns } = args;
+    const ctx = newVoiceKeyContext();
+    const unique = new Set(turns.map((t) => voiceKey(t.voice, ctx.refIds, ctx.refCounter))).size;
+    if (unique < caps.minVoices || unique > caps.maxVoices) {
+        const rule = caps.minVoices === caps.maxVoices
+            ? `exactly ${caps.minVoices} unique voices`
+            : `between ${caps.minVoices} and ${caps.maxVoices} unique voices`;
+        throw new DialogueConstraintError({
+            provider: provider.id,
+            model: modelId,
+            rule,
+            observed: `${unique} unique voices`,
+        });
+    }
+    if (caps.maxTotalChars != null) {
+        const total = turns.reduce((n, t) => n + t.text.length, 0);
+        if (total > caps.maxTotalChars) {
+            throw new DialogueConstraintError({
+                provider: provider.id,
+                model: modelId,
+                rule: `total characters <= ${caps.maxTotalChars}`,
+                observed: `${total} characters`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/conversation/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/conversation/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/conversation/errors.d.ts

@@ -0,0 +1,23 @@
+import { SpeechSDKError } from "../errors.js";
+export declare class ConversationInputError extends SpeechSDKError {
+    constructor(message: string);
+}
+export declare class DialogueConstraintError extends SpeechSDKError {
+    readonly provider: string;
+    readonly model: string;
+    constructor(options: {
+        provider: string;
+        model: string;
+        rule: string;
+        observed: string;
+    });
+}
+export declare class StitchUnsupportedError extends SpeechSDKError {
+    readonly provider: string;
+    readonly model: string;
+    constructor(options: {
+        provider: string;
+        model: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/conversation/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/conversation/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,uBAAwB,SAAQ,cAAc;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB;CAQF;AAED,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAQzD"}

package/dist/conversation/errors.js

@@ -0,0 +1,28 @@
+import { SpeechSDKError } from "../errors.js";
+export class ConversationInputError extends SpeechSDKError {
+    constructor(message) {
+        super(message);
+        this.name = "ConversationInputError";
+    }
+}
+export class DialogueConstraintError extends SpeechSDKError {
+    provider;
+    model;
+    constructor(options) {
+        super(`${options.provider}/${options.model} native dialogue requires ${options.rule}; got ${options.observed}.`);
+        this.name = "DialogueConstraintError";
+        this.provider = options.provider;
+        this.model = options.model;
+    }
+}
+export class StitchUnsupportedError extends SpeechSDKError {
+    provider;
+    model;
+    constructor(options) {
+        super(`${options.provider}/${options.model} cannot be used in a stitched conversation: provider does not support PCM/WAV output for this model.`);
+        this.name = "StitchUnsupportedError";
+        this.provider = options.provider;
+        this.model = options.model;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/conversation/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/conversation/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IAChD,QAAQ,CAAS;IACjB,KAAK,CAAS;IAEvB,YAAY,OAKX;QACC,KAAK,CACH,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,6BAA6B,OAAO,CAAC,IAAI,SAAS,OAAO,CAAC,QAAQ,GAAG,CAC1G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IAC/C,QAAQ,CAAS;IACjB,KAAK,CAAS;IAEvB,YAAY,OAA4C;QACtD,KAAK,CACH,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,sGAAsG,CAC3I,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;CACF"}

package/dist/conversation/pcm-concat.d.ts

@@ -0,0 +1,37 @@
+export interface Pcm16Segment {
+    readonly channels: number;
+    readonly pcm: Int16Array;
+    readonly sampleRate: number;
+}
+/** Decode a provider response to mono 16-bit PCM + its native sample rate. */
+export declare function decodeToPcm16(data: Uint8Array, mediaType: string): Pcm16Segment;
+/**
+ * Default RMS target: −20 dBFS — broadcast/podcast voice loudness convention
+ * with ~20 dB peak headroom. Comfortable to listen to and leaves room for
+ * typical TTS peaks not to clip.
+ */
+export declare const DEFAULT_VOLUME_DBFS = -20;
+/** Convert a dBFS level (≤ 0) to the equivalent int16 RMS amplitude. */
+export declare function dbfsToInt16Rms(dbfs: number): number;
+/**
+ * RMS-normalize each segment to an absolute target amplitude. Each segment
+ * is processed independently — no cross-segment dependency — so:
+ *   - The output level is the same across runs regardless of input mix.
+ *   - Two `generateConversation` calls produce comparable loudness even
+ *     with completely different content.
+ *
+ * Silent segments pass through unchanged. Output is clamped to int16
+ * range, so a quiet segment with rare peaks may clip slightly when
+ * boosted; the default target leaves ~20 dB headroom to make this rare
+ * for typical TTS content.
+ */
+export declare function normalizeRms(segments: readonly Pcm16Segment[], targetRmsAmplitude?: number): Pcm16Segment[];
+/**
+ * Resample each segment to `targetSampleRate` mono, interleave with `gapMs`
+ * silence, and mux the result as a WAV file via mediabunny.
+ */
+export declare function concatPcmToWav(segments: readonly Pcm16Segment[], options: {
+    gapMs: number;
+    targetSampleRate: number;
+}): Promise<Uint8Array>;
+//# sourceMappingURL=pcm-concat.d.ts.map

package/dist/conversation/pcm-concat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pcm-concat.d.ts","sourceRoot":"","sources":["../../src/conversation/pcm-concat.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAwED,8EAA8E;AAC9E,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,GAChB,YAAY,CAqCd;AAkHD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,kBAAkB,SAA2B,GAC5C,YAAY,EAAE,CAQhB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,UAAU,CAAC,CA8BrB"}