ssml-builder-js 2.14.0 → 2.15.0

package/dist/elements.mjs

@@ -33,12 +33,12 @@ import {
   registerSsmlCompletionProvider,
   resolveExpressAsStyles,
   updateEditableText
-} from "./chunk-UZSCXPC5.mjs";
+} from "./chunk-BDY2Q2JL.mjs";
 import {
   buildSsml,
   parseSsml,
   validateAzureSsml
-} from "./chunk-QFIBPCO4.mjs";
+} from "./chunk-WXFLUCLR.mjs";
 import "./chunk-6S5ODO6A.mjs";
 
 // packages/ssml-editor-react/src/ssmlInsertions.ts

package/dist/{index.d-CUXRwSw0.d.mts → index.d-8BvkB9gz.d.mts}

@@ -150,6 +150,23 @@ interface SsmlDocument {
     content?: string;
     attributes?: SsmlAttributes;
 }
+interface SsmlSourceTextSegment {
+    text: string;
+    range: {
+        start: number;
+        end: number;
+    };
+    sourceNodePath: string[];
+}
+interface SsmlSourceMarker {
+    kind: "mark" | "bookmark";
+    name: string;
+    originalTextRange: {
+        start: number;
+        end: number;
+    };
+    sourceNodePath: string[];
+}
 
 interface SsmlTextRange {
     start: number;
@@ -186,6 +203,8 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     /** Host-side validation hook for URL-bearing SSML attributes. */
     urlValidator?: AzureUrlValidator;
+    /** Source path associated with a chunk being validated. */
+    sourceNodePath?: readonly string[];
     /** Alias for urlValidator retained for applications that use the longer name. */
     customUrlValidator?: AzureUrlValidator;
     /** Controls deduplication, caching, cancellation, and concurrency for URL checks. */
@@ -221,7 +240,8 @@ type AzureUrlValidationResult = boolean | {
 type AzureUrlValidator = (url: string, context: {
     tag: string;
     attribute: string;
-}) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
+    sourceNodePath?: readonly string[];
+}, signal: AbortSignal) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
 interface AzureUrlValidationRunnerOptions {
     concurrency?: number;
     cache?: Map<string, AzureUrlValidationResult>;
@@ -229,4 +249,4 @@ interface AzureUrlValidationRunnerOptions {
     timeoutMs?: number;
 }
 
-export type { AzureValidationOptions as A, SsmlTextRange as S, SsmlDiagnostic as a, SsmlDocument as b, SsmlElement as c };
+export type { AzureValidationOptions as A, SsmlTextRange as S, SsmlSourceTextSegment as a, SsmlSourceMarker as b, SsmlDiagnostic as c, SsmlDocument as d, SsmlElement as e };

package/dist/{index.d-CUXRwSw0.d.ts → index.d-8BvkB9gz.d.ts}

@@ -150,6 +150,23 @@ interface SsmlDocument {
     content?: string;
     attributes?: SsmlAttributes;
 }
+interface SsmlSourceTextSegment {
+    text: string;
+    range: {
+        start: number;
+        end: number;
+    };
+    sourceNodePath: string[];
+}
+interface SsmlSourceMarker {
+    kind: "mark" | "bookmark";
+    name: string;
+    originalTextRange: {
+        start: number;
+        end: number;
+    };
+    sourceNodePath: string[];
+}
 
 interface SsmlTextRange {
     start: number;
@@ -186,6 +203,8 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     /** Host-side validation hook for URL-bearing SSML attributes. */
     urlValidator?: AzureUrlValidator;
+    /** Source path associated with a chunk being validated. */
+    sourceNodePath?: readonly string[];
     /** Alias for urlValidator retained for applications that use the longer name. */
     customUrlValidator?: AzureUrlValidator;
     /** Controls deduplication, caching, cancellation, and concurrency for URL checks. */
@@ -221,7 +240,8 @@ type AzureUrlValidationResult = boolean | {
 type AzureUrlValidator = (url: string, context: {
     tag: string;
     attribute: string;
-}) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
+    sourceNodePath?: readonly string[];
+}, signal: AbortSignal) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
 interface AzureUrlValidationRunnerOptions {
     concurrency?: number;
     cache?: Map<string, AzureUrlValidationResult>;
@@ -229,4 +249,4 @@ interface AzureUrlValidationRunnerOptions {
     timeoutMs?: number;
 }
 
-export type { AzureValidationOptions as A, SsmlTextRange as S, SsmlDiagnostic as a, SsmlDocument as b, SsmlElement as c };
+export type { AzureValidationOptions as A, SsmlTextRange as S, SsmlSourceTextSegment as a, SsmlSourceMarker as b, SsmlDiagnostic as c, SsmlDocument as d, SsmlElement as e };

package/dist/index.d.mts

@@ -1,5 +1,51 @@
-export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidationRunnerOptions, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SplitSsmlOptions, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlChunk, SsmlChunkContext, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity } from './core.mjs';
-import { S as SsmlTextRange, a as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-CUXRwSw0.mjs';
+export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidationRunnerOptions, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SplitSsmlOptions, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlChunk, SsmlChunkContext, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlSourceMap, SsmlSourceMarker, SsmlSourceTextSegment, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, getSsmlSourceMap, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity } from './core.mjs';
+import { S as SsmlTextRange, a as SsmlSourceTextSegment, b as SsmlSourceMarker, c as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-8BvkB9gz.mjs';
+import * as SpeechSDK from 'microsoft-cognitiveservices-speech-sdk';
+
+declare const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
+declare const OUTPUT_FORMATS: {
+    "raw-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoMULaw;
+    "riff-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16KbpsMonoSiren;
+    "audio-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16KbpsMonoSiren;
+    "audio-16khz-32kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3;
+    "audio-16khz-128kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3;
+    "audio-16khz-64kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz64KBitRateMonoMp3;
+    "audio-24khz-48kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3;
+    "audio-24khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz96KBitRateMonoMp3;
+    "audio-24khz-160kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3;
+    "raw-16khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoTrueSilk;
+    "riff-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm;
+    "riff-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz16BitMonoPcm;
+    "riff-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm;
+    "riff-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoMULaw;
+    "raw-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoPcm;
+    "raw-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm;
+    "raw-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz16BitMonoPcm;
+    "ogg-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus;
+    "ogg-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus;
+    "raw-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw48Khz16BitMonoPcm;
+    "riff-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff48Khz16BitMonoPcm;
+    "audio-48khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz96KBitRateMonoMp3;
+    "audio-48khz-192kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz192KBitRateMonoMp3;
+    "ogg-48khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus;
+    "webm-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm16Khz16BitMonoOpus;
+    "webm-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16BitMonoOpus;
+    "webm-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16Bit24KbpsMonoOpus;
+    "raw-24khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoTrueSilk;
+    "raw-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoALaw;
+    "riff-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoALaw;
+    "audio-16khz-16bit-32kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16Bit32KbpsMonoOpus;
+    "audio-24khz-16bit-48kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit48KbpsMonoOpus;
+    "audio-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit24KbpsMonoOpus;
+    "raw-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw22050Hz16BitMonoPcm;
+    "riff-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff22050Hz16BitMonoPcm;
+    "raw-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw44100Hz16BitMonoPcm;
+    "riff-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff44100Hz16BitMonoPcm;
+    "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz;
+    "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps;
+};
+type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
+declare function resolveMimeType(outputFormat: string): string;
 
 interface TtsConfig {
     signal?: AbortSignal;
@@ -18,6 +64,9 @@ interface TtsConfig {
     /** Metadata used to map synchronization events back to the source document. */
     chunkIndex?: number;
     sourceNodePath?: string[];
+    /** Exact source text segments used to map individual Azure events. */
+    sourceTextSegments?: SsmlSourceTextSegment[];
+    sourceMarkers?: SsmlSourceMarker[];
 }
 type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
 interface SsmlSynthesisBoundary {
@@ -82,6 +131,11 @@ interface SsmlSynthesisResult {
         start: number;
         end: number;
     };
+    /** MIME type of a result produced by an explicit merge operation. */
+    mimeType?: string;
+}
+interface MergedSynthesisResult extends SsmlSynthesisResult {
+    mimeType: string;
 }
 interface SsmlSynthesisChunk {
     ssml: string;
@@ -90,9 +144,15 @@ interface SsmlSynthesisChunk {
         end: number;
     };
     sourceNodePath?: string[];
+    sourceTextSegments?: SsmlSourceTextSegment[];
+    sourceMarkers?: SsmlSourceMarker[];
 }
 interface SynthesizeChunksOptions {
     onProgress?: (event: SynthesisProgressEvent) => void;
+    outputFormat?: AzureTtsOutputFormat | string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    sourceNodePath?: string[];
 }
 interface SynthesisProgressEvent {
     /** 1-based completed chunk count retained for backward compatibility. */
@@ -122,7 +182,9 @@ interface AzureTtsClientOptions {
     onProgress?: (event: SynthesisProgressEvent) => void;
 }
 
+type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "unsupported-format-error" | "cancelled" | "timeout";
 declare class AzureTtsError extends Error {
+    readonly kind: "azure-api-error";
     readonly status: number;
     readonly statusText: string;
     readonly responseBody: string;
@@ -133,19 +195,35 @@ declare class AzureTtsSdkError extends AzureTtsError {
     readonly errorDetails: string;
     constructor(errorDetails: string);
 }
+declare class SynthesisCancelledError extends Error {
+    readonly kind: "cancelled";
+    constructor(message?: string);
+}
+declare class SynthesisTimeoutError extends Error {
+    readonly kind: "timeout";
+    constructor(message: string);
+}
+declare class MergeError extends Error {
+    readonly kind: "merge-error";
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
 /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
 declare class UnsupportedMergeFormatError extends Error {
+    readonly kind: "unsupported-format-error";
     readonly format: string;
     constructor(format: string);
 }
+type AzureTtsSynthesisError = AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
 
 interface SsmlValidationError {
-    readonly kind: "validation";
+    readonly kind: "validation-error";
     readonly message: string;
     readonly diagnostics: readonly SsmlDiagnostic[];
 }
+type SsmlSynthesisError = SsmlValidationError | AzureTtsSynthesisError;
 declare class ChunkValidationError extends Error {
-    readonly kind: "chunk-validation";
+    readonly kind: "validation-error";
     readonly chunkIndex: number;
     readonly diagnostics: readonly SsmlDiagnostic[];
     constructor(chunkIndex: number, diagnostics: readonly SsmlDiagnostic[]);
@@ -155,12 +233,19 @@ type Result<T, E> = {
     readonly success: true;
     readonly status: "success";
     readonly value: T;
-} | {
+} | (E extends {
+    readonly kind: infer Kind extends SynthesisErrorKind;
+} ? {
     readonly ok: false;
     readonly success: false;
-    readonly status: "validation-error" | "azure-api-error";
+    readonly status: Kind;
     readonly error: E;
-};
+} : {
+    readonly ok: false;
+    readonly success: false;
+    readonly status: SynthesisErrorKind;
+    readonly error: E;
+});
 type SynthesisResult<T, E> = Result<T, E>;
 type Success<T> = Extract<Result<T, never>, {
     readonly ok: true;
@@ -171,22 +256,24 @@ type ValidationErrorResult = Extract<Result<never, SsmlValidationError>, {
 type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, {
     readonly status: "azure-api-error";
 }>;
-type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, AzureTtsError>;
+type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, SsmlSynthesisError>;
 interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
     /** Optional nested form for callers that want to keep validation settings grouped. */
     validation?: AzureValidationOptions;
+    signal?: AbortSignal;
 }
 interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     validation?: AzureValidationOptions;
     outputFormat?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    sourceNodePath?: string[];
     onProgress?: (event: SynthesisProgressEvent) => void;
 }
-type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, AzureTtsError>;
+type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
 interface SynthesisClient {
-    synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
-    synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: {
-        onProgress?: (event: SynthesisProgressEvent) => void;
-    }): Promise<SsmlSynthesisResult>;
+    synthesizeSsml(ssml: string, options?: Partial<SynthesizeChunksOptions>): Promise<SsmlSynthesisResult>;
+    synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
 }
 /** Validates SSML before invoking Azure and converts validation/API failures to one result shape. */
 declare function synthesizeSsmlSafe(client: Pick<AzureTtsClient, "synthesizeSsml"> | SynthesisClient, ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
@@ -197,7 +284,7 @@ declare class AzureTtsClient {
     #private;
     constructor(options: AzureTtsClientOptions);
     synthesize(ssml: string): Promise<ArrayBuffer>;
-    synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
+    synthesizeSsml(ssml: string, options?: Partial<TtsConfig>): Promise<SsmlSynthesisResult>;
     synthesizeChunks(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
     synthesizeSsmlSafe(ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
     synthesizeChunksSafe(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeSsmlChunksSafeOptions): Promise<SsmlSynthesisChunksSafeResult>;
@@ -205,16 +292,25 @@ declare class AzureTtsClient {
 }
 
 type MergeAudioFormat = "wav" | "mp3" | "raw";
+interface MergeAudioOptions {
+    format: AzureTtsOutputFormat;
+}
+interface MergeSynthesisOptions extends MergeAudioOptions {
+    customMerger?: (buffers: ArrayBuffer[], format: string) => Promise<ArrayBuffer> | ArrayBuffer;
+}
+type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
+    customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
+};
 /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
 declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined;
 declare function canMergeAudioFormat(format: string): boolean;
 /** Merges audio buffers while preserving the invariants of supported containers. */
-declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], format: string): ArrayBuffer;
+declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], options: MergeAudioOptions): ArrayBuffer;
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
 /** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
 declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
-/** Concatenates audio buffers and shifts all synchronization events by prior chunk durations. */
-declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], format?: string): SsmlSynthesisResult;
+declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: AsyncMergeSynthesisOptions): Promise<MergedSynthesisResult>;
+declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: MergeAudioOptions): MergedSynthesisResult;
 /** Backward-compatible audio-only synthesis helper. */
 declare function synthesizeSpeech(ssml: string, config: TtsConfig): Promise<ArrayBuffer>;
 
@@ -246,4 +342,4 @@ interface AzureVoiceCatalog {
 /** Fetches and deduplicates the current Azure Speech voice catalog for one or more regions. */
 declare function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOptions): Promise<AzureVoiceCatalog>;
 
-export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, AzureTtsSdkError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, type SynthesisChunkStatus, type SynthesisProgressEvent, type SynthesisResult, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
+export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };

package/dist/index.d.ts

@@ -1,5 +1,51 @@
-export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidationRunnerOptions, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SplitSsmlOptions, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlChunk, SsmlChunkContext, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity } from './core.js';
-import { S as SsmlTextRange, a as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-CUXRwSw0.js';
+export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidationRunnerOptions, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SplitSsmlOptions, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlChunk, SsmlChunkContext, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlSourceMap, SsmlSourceMarker, SsmlSourceTextSegment, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, getSsmlSourceMap, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity } from './core.js';
+import { S as SsmlTextRange, a as SsmlSourceTextSegment, b as SsmlSourceMarker, c as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-8BvkB9gz.js';
+import * as SpeechSDK from 'microsoft-cognitiveservices-speech-sdk';
+
+declare const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
+declare const OUTPUT_FORMATS: {
+    "raw-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoMULaw;
+    "riff-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16KbpsMonoSiren;
+    "audio-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16KbpsMonoSiren;
+    "audio-16khz-32kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3;
+    "audio-16khz-128kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3;
+    "audio-16khz-64kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz64KBitRateMonoMp3;
+    "audio-24khz-48kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3;
+    "audio-24khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz96KBitRateMonoMp3;
+    "audio-24khz-160kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3;
+    "raw-16khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoTrueSilk;
+    "riff-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm;
+    "riff-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz16BitMonoPcm;
+    "riff-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm;
+    "riff-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoMULaw;
+    "raw-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoPcm;
+    "raw-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm;
+    "raw-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz16BitMonoPcm;
+    "ogg-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus;
+    "ogg-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus;
+    "raw-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw48Khz16BitMonoPcm;
+    "riff-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff48Khz16BitMonoPcm;
+    "audio-48khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz96KBitRateMonoMp3;
+    "audio-48khz-192kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz192KBitRateMonoMp3;
+    "ogg-48khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus;
+    "webm-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm16Khz16BitMonoOpus;
+    "webm-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16BitMonoOpus;
+    "webm-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16Bit24KbpsMonoOpus;
+    "raw-24khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoTrueSilk;
+    "raw-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoALaw;
+    "riff-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoALaw;
+    "audio-16khz-16bit-32kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16Bit32KbpsMonoOpus;
+    "audio-24khz-16bit-48kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit48KbpsMonoOpus;
+    "audio-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit24KbpsMonoOpus;
+    "raw-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw22050Hz16BitMonoPcm;
+    "riff-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff22050Hz16BitMonoPcm;
+    "raw-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw44100Hz16BitMonoPcm;
+    "riff-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff44100Hz16BitMonoPcm;
+    "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz;
+    "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps;
+};
+type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
+declare function resolveMimeType(outputFormat: string): string;
 
 interface TtsConfig {
     signal?: AbortSignal;
@@ -18,6 +64,9 @@ interface TtsConfig {
     /** Metadata used to map synchronization events back to the source document. */
     chunkIndex?: number;
     sourceNodePath?: string[];
+    /** Exact source text segments used to map individual Azure events. */
+    sourceTextSegments?: SsmlSourceTextSegment[];
+    sourceMarkers?: SsmlSourceMarker[];
 }
 type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
 interface SsmlSynthesisBoundary {
@@ -82,6 +131,11 @@ interface SsmlSynthesisResult {
         start: number;
         end: number;
     };
+    /** MIME type of a result produced by an explicit merge operation. */
+    mimeType?: string;
+}
+interface MergedSynthesisResult extends SsmlSynthesisResult {
+    mimeType: string;
 }
 interface SsmlSynthesisChunk {
     ssml: string;
@@ -90,9 +144,15 @@ interface SsmlSynthesisChunk {
         end: number;
     };
     sourceNodePath?: string[];
+    sourceTextSegments?: SsmlSourceTextSegment[];
+    sourceMarkers?: SsmlSourceMarker[];
 }
 interface SynthesizeChunksOptions {
     onProgress?: (event: SynthesisProgressEvent) => void;
+    outputFormat?: AzureTtsOutputFormat | string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    sourceNodePath?: string[];
 }
 interface SynthesisProgressEvent {
     /** 1-based completed chunk count retained for backward compatibility. */
@@ -122,7 +182,9 @@ interface AzureTtsClientOptions {
     onProgress?: (event: SynthesisProgressEvent) => void;
 }
 
+type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "unsupported-format-error" | "cancelled" | "timeout";
 declare class AzureTtsError extends Error {
+    readonly kind: "azure-api-error";
     readonly status: number;
     readonly statusText: string;
     readonly responseBody: string;
@@ -133,19 +195,35 @@ declare class AzureTtsSdkError extends AzureTtsError {
     readonly errorDetails: string;
     constructor(errorDetails: string);
 }
+declare class SynthesisCancelledError extends Error {
+    readonly kind: "cancelled";
+    constructor(message?: string);
+}
+declare class SynthesisTimeoutError extends Error {
+    readonly kind: "timeout";
+    constructor(message: string);
+}
+declare class MergeError extends Error {
+    readonly kind: "merge-error";
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
 /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
 declare class UnsupportedMergeFormatError extends Error {
+    readonly kind: "unsupported-format-error";
     readonly format: string;
     constructor(format: string);
 }
+type AzureTtsSynthesisError = AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
 
 interface SsmlValidationError {
-    readonly kind: "validation";
+    readonly kind: "validation-error";
     readonly message: string;
     readonly diagnostics: readonly SsmlDiagnostic[];
 }
+type SsmlSynthesisError = SsmlValidationError | AzureTtsSynthesisError;
 declare class ChunkValidationError extends Error {
-    readonly kind: "chunk-validation";
+    readonly kind: "validation-error";
     readonly chunkIndex: number;
     readonly diagnostics: readonly SsmlDiagnostic[];
     constructor(chunkIndex: number, diagnostics: readonly SsmlDiagnostic[]);
@@ -155,12 +233,19 @@ type Result<T, E> = {
     readonly success: true;
     readonly status: "success";
     readonly value: T;
-} | {
+} | (E extends {
+    readonly kind: infer Kind extends SynthesisErrorKind;
+} ? {
     readonly ok: false;
     readonly success: false;
-    readonly status: "validation-error" | "azure-api-error";
+    readonly status: Kind;
     readonly error: E;
-};
+} : {
+    readonly ok: false;
+    readonly success: false;
+    readonly status: SynthesisErrorKind;
+    readonly error: E;
+});
 type SynthesisResult<T, E> = Result<T, E>;
 type Success<T> = Extract<Result<T, never>, {
     readonly ok: true;
@@ -171,22 +256,24 @@ type ValidationErrorResult = Extract<Result<never, SsmlValidationError>, {
 type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, {
     readonly status: "azure-api-error";
 }>;
-type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, AzureTtsError>;
+type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, SsmlSynthesisError>;
 interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
     /** Optional nested form for callers that want to keep validation settings grouped. */
     validation?: AzureValidationOptions;
+    signal?: AbortSignal;
 }
 interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     validation?: AzureValidationOptions;
     outputFormat?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    sourceNodePath?: string[];
     onProgress?: (event: SynthesisProgressEvent) => void;
 }
-type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, AzureTtsError>;
+type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
 interface SynthesisClient {
-    synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
-    synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: {
-        onProgress?: (event: SynthesisProgressEvent) => void;
-    }): Promise<SsmlSynthesisResult>;
+    synthesizeSsml(ssml: string, options?: Partial<SynthesizeChunksOptions>): Promise<SsmlSynthesisResult>;
+    synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
 }
 /** Validates SSML before invoking Azure and converts validation/API failures to one result shape. */
 declare function synthesizeSsmlSafe(client: Pick<AzureTtsClient, "synthesizeSsml"> | SynthesisClient, ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
@@ -197,7 +284,7 @@ declare class AzureTtsClient {
     #private;
     constructor(options: AzureTtsClientOptions);
     synthesize(ssml: string): Promise<ArrayBuffer>;
-    synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
+    synthesizeSsml(ssml: string, options?: Partial<TtsConfig>): Promise<SsmlSynthesisResult>;
     synthesizeChunks(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
     synthesizeSsmlSafe(ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
     synthesizeChunksSafe(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeSsmlChunksSafeOptions): Promise<SsmlSynthesisChunksSafeResult>;
@@ -205,16 +292,25 @@ declare class AzureTtsClient {
 }
 
 type MergeAudioFormat = "wav" | "mp3" | "raw";
+interface MergeAudioOptions {
+    format: AzureTtsOutputFormat;
+}
+interface MergeSynthesisOptions extends MergeAudioOptions {
+    customMerger?: (buffers: ArrayBuffer[], format: string) => Promise<ArrayBuffer> | ArrayBuffer;
+}
+type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
+    customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
+};
 /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
 declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined;
 declare function canMergeAudioFormat(format: string): boolean;
 /** Merges audio buffers while preserving the invariants of supported containers. */
-declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], format: string): ArrayBuffer;
+declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], options: MergeAudioOptions): ArrayBuffer;
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
 /** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
 declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
-/** Concatenates audio buffers and shifts all synchronization events by prior chunk durations. */
-declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], format?: string): SsmlSynthesisResult;
+declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: AsyncMergeSynthesisOptions): Promise<MergedSynthesisResult>;
+declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: MergeAudioOptions): MergedSynthesisResult;
 /** Backward-compatible audio-only synthesis helper. */
 declare function synthesizeSpeech(ssml: string, config: TtsConfig): Promise<ArrayBuffer>;
 
@@ -246,4 +342,4 @@ interface AzureVoiceCatalog {
 /** Fetches and deduplicates the current Azure Speech voice catalog for one or more regions. */
 declare function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOptions): Promise<AzureVoiceCatalog>;
 
-export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, AzureTtsSdkError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, type SynthesisChunkStatus, type SynthesisProgressEvent, type SynthesisResult, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
+export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };