@ssml-builder-js/azure-tts-client 2.14.0 → 2.15.0

package/dist/index.js

@@ -41,12 +41,17 @@ __export(index_exports, {
   AzureTtsError: () => AzureTtsError,
   AzureTtsSdkError: () => AzureTtsSdkError,
   ChunkValidationError: () => ChunkValidationError,
+  DEFAULT_OUTPUT_FORMAT: () => DEFAULT_OUTPUT_FORMAT,
+  MergeError: () => MergeError,
+  SynthesisCancelledError: () => SynthesisCancelledError,
+  SynthesisTimeoutError: () => SynthesisTimeoutError,
   UnsupportedMergeFormatError: () => UnsupportedMergeFormatError,
   canMergeAudioFormat: () => canMergeAudioFormat,
   fetchAzureVoiceCatalog: () => fetchAzureVoiceCatalog,
   mergeAudioBuffers: () => mergeAudioBuffers,
   mergeSynthesisResults: () => mergeSynthesisResults,
   resolveMergeAudioFormat: () => resolveMergeAudioFormat,
+  resolveMimeType: () => resolveMimeType,
   synthesizeSpeech: () => synthesizeSpeech,
   synthesizeSsml: () => synthesizeSsml,
   synthesizeSsmlChunks: () => synthesizeSsmlChunks,
@@ -59,6 +64,7 @@ module.exports = __toCommonJS(index_exports);
 var AzureTtsError = class extends Error {
   constructor(status, statusText, responseBody, requestId) {
     super(`Azure TTS request failed: ${status} ${statusText}`);
+    this.kind = "azure-api-error";
     this.name = "AzureTtsError";
     this.status = status;
     this.statusText = statusText;
@@ -74,13 +80,44 @@ var AzureTtsSdkError = class extends AzureTtsError {
     this.errorDetails = errorDetails;
   }
 };
+var SynthesisCancelledError = class extends Error {
+  constructor(message = "Speech synthesis was cancelled.") {
+    super(message);
+    this.kind = "cancelled";
+    this.name = "SynthesisCancelledError";
+  }
+};
+var SynthesisTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.kind = "timeout";
+    this.name = "SynthesisTimeoutError";
+  }
+};
+var MergeError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.kind = "merge-error";
+    this.name = "MergeError";
+    this.cause = cause;
+  }
+};
 var UnsupportedMergeFormatError = class extends Error {
   constructor(format) {
     super(`Audio format "${format}" cannot be safely concatenated; container re-multiplexing is required.`);
+    this.kind = "unsupported-format-error";
     this.name = "UnsupportedMergeFormatError";
     this.format = format;
   }
 };
+function toSynthesisError(error) {
+  if (error instanceof AzureTtsError || error instanceof MergeError || error instanceof UnsupportedMergeFormatError || error instanceof SynthesisCancelledError || error instanceof SynthesisTimeoutError)
+    return error;
+  const message = error instanceof Error ? error.message : String(error);
+  if (/cancel|abort/i.test(message)) return new SynthesisCancelledError(message);
+  if (/tim(?:e|ed) ?out/i.test(message)) return new SynthesisTimeoutError(message);
+  return createSpeechSdkError(error);
+}
 function createSpeechSdkError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new AzureTtsSdkError(message);
@@ -88,9 +125,7 @@ function createSpeechSdkError(error) {
 
 // src/synthesis.ts
 var SpeechSDK2 = __toESM(require("microsoft-cognitiveservices-speech-sdk"));
-
-// src/speechConfig.ts
-var import_microsoft_cognitiveservices_speech_sdk = require("microsoft-cognitiveservices-speech-sdk");
+var import_ssml_core = require("@ssml-builder-js/ssml-core");
 
 // src/outputFormats.ts
 var SpeechSDK = __toESM(require("microsoft-cognitiveservices-speech-sdk"));
@@ -136,6 +171,14 @@ var OUTPUT_FORMATS = {
   "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz,
   "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps
 };
+function resolveMimeType(outputFormat) {
+  if (/(?:wav|wave|riff)/i.test(outputFormat)) return "audio/wav";
+  if (/(?:mp3|mpeg)/i.test(outputFormat)) return "audio/mpeg";
+  if (/ogg/i.test(outputFormat)) return "audio/ogg";
+  if (/webm/i.test(outputFormat)) return "audio/webm";
+  if (/raw/i.test(outputFormat)) return "audio/L16";
+  return "application/octet-stream";
+}
 function resolveOutputFormat(outputFormat) {
   const resolvedFormat = OUTPUT_FORMATS[outputFormat];
   if (resolvedFormat === void 0) {
@@ -145,6 +188,7 @@ function resolveOutputFormat(outputFormat) {
 }
 
 // src/speechConfig.ts
+var import_microsoft_cognitiveservices_speech_sdk = require("microsoft-cognitiveservices-speech-sdk");
 function resolveEndpoint(config) {
   const endpoint = config.endpoint?.trim() || "https://{region}.tts.speech.microsoft.com/cognitiveservices/v1";
   return endpoint.replace(/\{region\}/g, encodeURIComponent(config.region));
@@ -278,28 +322,35 @@ function resolveMergeAudioFormat(format) {
 function canMergeAudioFormat(format) {
   return resolveMergeAudioFormat(format) !== void 0;
 }
-function mergeAudioBuffers(buffers, format) {
-  if (isWavFormat(format)) return mergeWavBuffers(buffers);
-  if (isMp3Format(format)) {
-    const parts = buffers.map(stripMp3Tags);
-    const output = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
-    let offset = 0;
-    for (const part of parts) {
-      output.set(part, offset);
-      offset += part.byteLength;
+function mergeAudioBuffers(buffers, options) {
+  const format = typeof options === "string" ? options : options?.format;
+  if (!format) throw new UnsupportedMergeFormatError("");
+  try {
+    if (isWavFormat(format)) return mergeWavBuffers(buffers);
+    if (isMp3Format(format)) {
+      const parts = buffers.map(stripMp3Tags);
+      const output = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+      let offset = 0;
+      for (const part of parts) {
+        output.set(part, offset);
+        offset += part.byteLength;
+      }
+      return output.buffer;
     }
-    return output.buffer;
-  }
-  if (isRawFormat(format)) {
-    const output = new Uint8Array(buffers.reduce((total, buffer) => total + buffer.byteLength, 0));
-    let offset = 0;
-    for (const buffer of buffers) {
-      output.set(new Uint8Array(buffer), offset);
-      offset += buffer.byteLength;
+    if (isRawFormat(format)) {
+      const output = new Uint8Array(buffers.reduce((total, buffer) => total + buffer.byteLength, 0));
+      let offset = 0;
+      for (const buffer of buffers) {
+        output.set(new Uint8Array(buffer), offset);
+        offset += buffer.byteLength;
+      }
+      return output.buffer;
     }
-    return output.buffer;
+    throw new UnsupportedMergeFormatError(format);
+  } catch (error) {
+    if (error instanceof UnsupportedMergeFormatError || error instanceof MergeError) throw error;
+    throw new MergeError(`Audio buffers could not be merged for format "${format}".`, error);
   }
-  throw new UnsupportedMergeFormatError(format);
 }
 function closeSpeechResources(speechConfig, synthesizer) {
   try {
@@ -314,7 +365,7 @@ function closeSpeechResources(speechConfig, synthesizer) {
 var ticksToMilliseconds = (ticks) => Math.max(0, ticks) / 1e4;
 async function synthesizeSsml(ssml, config) {
   if (config.signal?.aborted) {
-    throw createSpeechSdkError("Speech synthesis was cancelled.");
+    throw new SynthesisCancelledError();
   }
   const speechConfig = createSpeechConfig(config);
   const synthesizer = new SpeechSDK2.SpeechSynthesizer(speechConfig, null);
@@ -337,23 +388,94 @@ async function synthesizeSsml(ssml, config) {
       settled = true;
       cleanup();
       closeResources();
-      reject(createSpeechSdkError(error));
+      reject(toSynthesisError(error));
     };
     const boundaries = [];
     const visemes = [];
     const bookmarks = [];
+    let sourceEventCursor = 0;
+    let generatedSourceMap;
+    if (!config.sourceTextSegments && !config.sourceMarkers) {
+      try {
+        generatedSourceMap = (0, import_ssml_core.getSsmlSourceMap)(ssml);
+      } catch {
+        generatedSourceMap = void 0;
+      }
+    }
+    const sourceBaseOffset = config.sourceTextRange?.start ?? 0;
+    const sourceSegments = config.sourceTextSegments ?? generatedSourceMap?.segments.map((segment) => ({
+      ...segment,
+      range: {
+        start: segment.range.start + sourceBaseOffset,
+        end: segment.range.end + sourceBaseOffset
+      },
+      sourceNodePath: [...segment.sourceNodePath]
+    })) ?? [];
+    const sourceMarkers = config.sourceMarkers ?? generatedSourceMap?.markers.map((marker) => ({
+      ...marker,
+      originalTextRange: {
+        start: marker.originalTextRange.start + sourceBaseOffset,
+        end: marker.originalTextRange.end + sourceBaseOffset
+      },
+      sourceNodePath: [...marker.sourceNodePath]
+    })) ?? [];
+    const sourceText = sourceSegments.map((segment) => segment.text).join("");
+    const mapSourceEvent = (text, offsetHint, markerName) => {
+      const marker = markerName ? sourceMarkers.find((candidate) => candidate.name === markerName) : void 0;
+      if (marker) {
+        return {
+          originalTextRange: { ...marker.originalTextRange },
+          sourceNodePath: [...marker.sourceNodePath],
+          textRange: { ...marker.originalTextRange }
+        };
+      }
+      if (sourceSegments.length === 0 && !config.sourceTextRange && !config.sourceNodePath) return {};
+      const value = text ?? "";
+      let localStart = Number.isFinite(offsetHint) && (offsetHint ?? 0) >= 0 ? offsetHint : -1;
+      if (value && localStart >= 0 && sourceText.slice(localStart, localStart + value.length) !== value)
+        localStart = -1;
+      if (localStart < 0 || localStart > sourceText.length) {
+        localStart = value ? sourceText.indexOf(value, sourceEventCursor) : sourceEventCursor;
+        if (localStart < 0) localStart = value ? sourceText.indexOf(value) : sourceEventCursor;
+      }
+      localStart = Math.max(0, localStart);
+      const localEnd = Math.min(sourceText.length, localStart + value.length);
+      sourceEventCursor = Math.max(sourceEventCursor, localEnd);
+      const baseStart = config.sourceTextRange?.start ?? sourceSegments[0]?.range.start ?? 0;
+      const fallbackRange = { start: baseStart + localStart, end: baseStart + localEnd };
+      const segment = sourceSegments.find(({ range }) => range.start <= fallbackRange.start && range.end > fallbackRange.start) ?? sourceSegments.find(({ range }) => range.end > fallbackRange.start) ?? (value.length === 0 ? sourceSegments.find(({ range }) => range.start <= fallbackRange.start && range.end >= fallbackRange.start) : void 0);
+      return {
+        originalTextRange: { ...fallbackRange },
+        textRange: { ...fallbackRange },
+        ...segment ? { sourceNodePath: [...segment.sourceNodePath] } : config.sourceNodePath ? { sourceNodePath: [...config.sourceNodePath] } : {}
+      };
+    };
     synthesizer.wordBoundary = (_sender, event) => {
       boundaries.push({
         text: event.text,
         audioOffsetMs: ticksToMilliseconds(event.audioOffset),
-        durationMs: ticksToMilliseconds(event.duration)
+        durationMs: ticksToMilliseconds(event.duration),
+        ...mapSourceEvent(
+          event.text,
+          event.textOffset
+        )
       });
     };
     synthesizer.visemeReceived = (_sender, event) => {
-      visemes.push({ visemeId: event.visemeId, audioOffsetMs: ticksToMilliseconds(event.audioOffset) });
+      const eventWithOffset = event;
+      visemes.push({
+        visemeId: event.visemeId,
+        audioOffsetMs: ticksToMilliseconds(event.audioOffset),
+        ...mapSourceEvent(void 0, eventWithOffset.textOffset)
+      });
     };
     synthesizer.bookmarkReached = (_sender, event) => {
-      bookmarks.push({ name: event.text, audioOffsetMs: ticksToMilliseconds(event.audioOffset) });
+      const eventWithOffset = event;
+      bookmarks.push({
+        name: event.text,
+        audioOffsetMs: ticksToMilliseconds(event.audioOffset),
+        ...mapSourceEvent(void 0, eventWithOffset.textOffset, event.text)
+      });
     };
     const cb = (result) => {
       if (settled) return;
@@ -376,8 +498,8 @@ async function synthesizeSsml(ssml, config) {
       const requestId = result.resultId;
       const addSourceMetadata = (event) => ({
         ...event,
-        ...config.sourceTextRange ? { textRange: { ...config.sourceTextRange } } : {},
-        ...config.sourceTextRange ? { originalTextRange: { ...config.sourceTextRange } } : {},
+        ...config.sourceTextRange && !("textRange" in event) ? { textRange: { ...config.sourceTextRange } } : {},
+        ...config.sourceTextRange && !("originalTextRange" in event) ? { originalTextRange: { ...config.sourceTextRange } } : {},
         ...config.chunkIndex !== void 0 ? { chunkIndex: config.chunkIndex } : {},
         ...config.sourceNodePath ? { sourceNodePath: [...config.sourceNodePath] } : {},
         ...requestId ? { requestId } : {}
@@ -397,12 +519,12 @@ async function synthesizeSsml(ssml, config) {
     };
     try {
       if (config.signal) {
-        abortHandler = () => rejectWithError("Speech synthesis was cancelled.");
+        abortHandler = () => rejectWithError(new SynthesisCancelledError());
         config.signal.addEventListener("abort", abortHandler, { once: true });
       }
       if (config.timeoutMs !== void 0 && config.timeoutMs > 0) {
         timeout = setTimeout(
-          () => rejectWithError(`Speech synthesis timed out after ${config.timeoutMs} ms.`),
+          () => rejectWithError(new SynthesisTimeoutError(`Speech synthesis timed out after ${config.timeoutMs} ms.`)),
           config.timeoutMs
         );
       }
@@ -444,7 +566,9 @@ async function synthesizeSsmlChunks(chunks, config) {
       const result = await synthesizeSsml(input.ssml, {
         ...config,
         ...input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {},
-        ...input.sourceNodePath ? { sourceNodePath: input.sourceNodePath } : {},
+        ...input.sourceNodePath ?? config.sourceNodePath ? { sourceNodePath: [...input.sourceNodePath ?? config.sourceNodePath ?? []] } : {},
+        ...input.sourceTextSegments ? { sourceTextSegments: input.sourceTextSegments } : {},
+        ...input.sourceMarkers ? { sourceMarkers: input.sourceMarkers } : {},
         chunkIndex: index,
         onProgress: void 0
       });
@@ -472,27 +596,16 @@ async function synthesizeSsmlChunks(chunks, config) {
       throw error;
     }
   }
-  return mergeSynthesisResults(results, config.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3");
-}
-function mergeSynthesisResults(results, format) {
-  const audioData = format ? new Uint8Array(
-    mergeAudioBuffers(
-      results.map((result) => result.audioData),
-      format
-    )
-  ) : new Uint8Array(results.reduce((total, result) => total + result.audioData.byteLength, 0));
-  if (!format) {
-    let offset = 0;
-    for (const result of results) {
-      audioData.set(new Uint8Array(result.audioData), offset);
-      offset += result.audioData.byteLength;
-    }
-  }
+  return mergeSynthesisResults(results, {
+    format: config.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3"
+  });
+}
+function createMergedResult(results, audioData, format) {
   const boundaries = [];
   const visemes = [];
   const bookmarks = [];
   let durationOffset = 0;
-  for (const result of results) {
+  for (const [resultIndex, result] of results.entries()) {
     const chunkBoundaries = result.boundaries && result.boundaries.length > 0 ? result.boundaries : result.wordBoundary ?? result.wordBoundaries ?? [];
     for (const boundary of chunkBoundaries) {
       const textRange = boundary.textRange ?? result.textRange;
@@ -502,7 +615,7 @@ function mergeSynthesisResults(results, format) {
         ...boundary,
         audioOffsetMs: boundary.audioOffsetMs + durationOffset,
         chunkAudioOffsetMs: boundary.chunkAudioOffsetMs ?? boundary.audioOffsetMs,
-        ...boundary.chunkIndex === void 0 ? { chunkIndex: results.indexOf(result) } : {},
+        ...boundary.chunkIndex === void 0 ? { chunkIndex: resultIndex } : {},
         ...boundary.sourceNodePath ? { sourceNodePath: [...boundary.sourceNodePath] } : {},
         ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
@@ -517,7 +630,7 @@ function mergeSynthesisResults(results, format) {
         ...viseme,
         audioOffsetMs: viseme.audioOffsetMs + durationOffset,
         chunkAudioOffsetMs: viseme.chunkAudioOffsetMs ?? viseme.audioOffsetMs,
-        ...viseme.chunkIndex === void 0 ? { chunkIndex: results.indexOf(result) } : {},
+        ...viseme.chunkIndex === void 0 ? { chunkIndex: resultIndex } : {},
         ...viseme.sourceNodePath ? { sourceNodePath: [...viseme.sourceNodePath] } : {},
         ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
@@ -532,7 +645,7 @@ function mergeSynthesisResults(results, format) {
         ...bookmark,
         audioOffsetMs: bookmark.audioOffsetMs + durationOffset,
         chunkAudioOffsetMs: bookmark.chunkAudioOffsetMs ?? bookmark.audioOffsetMs,
-        ...bookmark.chunkIndex === void 0 ? { chunkIndex: results.indexOf(result) } : {},
+        ...bookmark.chunkIndex === void 0 ? { chunkIndex: resultIndex } : {},
         ...bookmark.sourceNodePath ? { sourceNodePath: [...bookmark.sourceNodePath] } : {},
         ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
@@ -542,8 +655,9 @@ function mergeSynthesisResults(results, format) {
     durationOffset += Math.max(0, result.durationMs);
   }
   return {
-    audioData: audioData.buffer,
+    audioData,
     durationMs: durationOffset,
+    mimeType: resolveMimeType(format),
     ...boundaries.length > 0 ? { boundaries, wordBoundary: boundaries, wordBoundaries: boundaries } : {},
     ...visemes.length > 0 ? { visemes } : {},
     ...bookmarks.length > 0 ? { bookmarks } : {},
@@ -551,46 +665,78 @@ function mergeSynthesisResults(results, format) {
     ...results.length === 1 && results[0]?.textRange ? { textRange: { ...results[0].textRange } } : {}
   };
 }
+function mergeSynthesisResults(results, options) {
+  const resolvedOptions = typeof options === "string" ? { format: options } : options;
+  const format = resolvedOptions?.format;
+  if (!format) throw new UnsupportedMergeFormatError("");
+  const buffers = results.map((result) => result.audioData);
+  if (resolvedOptions.customMerger) {
+    return Promise.resolve().then(() => resolvedOptions.customMerger?.(buffers, format)).then((merged) => {
+      if (!merged) throw new MergeError("The custom audio merger returned no audio buffer.");
+      return createMergedResult(results, merged, format);
+    }).catch((error) => {
+      if (error instanceof UnsupportedMergeFormatError || error instanceof MergeError) throw error;
+      throw new MergeError(`Custom audio merger failed for format "${format}".`, error);
+    });
+  }
+  try {
+    return createMergedResult(results, mergeAudioBuffers(buffers, { format }), format);
+  } catch (error) {
+    if (error instanceof UnsupportedMergeFormatError || error instanceof MergeError) throw error;
+    throw new MergeError(`Audio buffers could not be merged for format "${format}".`, error);
+  }
+}
 async function synthesizeSpeech(ssml, config) {
   return (await synthesizeSsml(ssml, config)).audioData;
 }
 
 // src/safe.ts
-var import_ssml_core = require("@ssml-builder-js/ssml-core");
+var import_ssml_core2 = require("@ssml-builder-js/ssml-core");
 var ChunkValidationError = class extends Error {
   constructor(chunkIndex, diagnostics) {
     super(`SSML validation failed for chunk ${chunkIndex}; the Azure Speech API was not called.`);
-    this.kind = "chunk-validation";
+    this.kind = "validation-error";
     this.name = "ChunkValidationError";
     this.chunkIndex = chunkIndex;
     this.diagnostics = diagnostics;
   }
 };
+function failure(error) {
+  return { ok: false, success: false, status: error.kind, error };
+}
 async function synthesizeSsmlSafe(client, ssml, options = {}) {
-  const validationOptions = options.validation ?? options;
-  const diagnostics = await Promise.resolve((0, import_ssml_core.validateAzureSsml)(ssml, validationOptions));
+  const validationOptions = withValidationSignal(options.validation ?? options, options.signal);
+  const diagnostics = await Promise.resolve((0, import_ssml_core2.validateAzureSsml)(ssml, validationOptions));
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
   if (errors.length > 0) {
-    return {
-      ok: false,
-      success: false,
-      status: "validation-error",
-      error: {
-        kind: "validation",
-        message: "SSML validation failed; the Azure Speech API was not called.",
-        diagnostics: errors
-      }
-    };
+    return failure({
+      kind: "validation-error",
+      message: "SSML validation failed; the Azure Speech API was not called.",
+      diagnostics: errors
+    });
   }
   try {
-    return { ok: true, success: true, status: "success", value: await client.synthesizeSsml(ssml) };
+    return {
+      ok: true,
+      success: true,
+      status: "success",
+      value: await client.synthesizeSsml(ssml, { signal: options.signal })
+    };
   } catch (error) {
-    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
-    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+    const synthesisError = toSynthesisError(error);
+    return failure(synthesisError);
   }
 }
 async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
-  const validationOptions = options.validation ?? options;
+  const validationOptions = withValidationSignal(options.validation ?? options, options.signal);
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   const pending = (index, status, error) => {
     options.onProgress?.({
       currentChunk: status === "success" ? index + 1 : index,
@@ -609,7 +755,10 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
   const validations = await Promise.all(
     chunks.map(async (chunk) => {
       const ssml = typeof chunk === "string" ? chunk : chunk.ssml;
-      const diagnostics = await Promise.resolve((0, import_ssml_core.validateAzureSsml)(ssml, validationOptions));
+      const sourceNodePath = typeof chunk === "string" ? options.sourceNodePath : chunk.sourceNodePath ?? options.sourceNodePath;
+      const diagnostics = await Promise.resolve(
+        (0, import_ssml_core2.validateAzureSsml)(ssml, { ...validationOptions, ...sourceNodePath ? { sourceNodePath } : {} })
+      );
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     })
   );
@@ -617,31 +766,78 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
   if (firstInvalidIndex >= 0) {
     const error = new ChunkValidationError(firstInvalidIndex, validations[firstInvalidIndex] ?? []);
     pending(firstInvalidIndex, "failed", error);
-    return { ok: false, success: false, status: "validation-error", error };
+    return failure(error);
   }
   try {
     if (client.synthesizeChunks) {
-      const value = await client.synthesizeChunks(chunks, { onProgress: options.onProgress });
+      const normalizedChunks = chunks.map((chunk) => {
+        if (typeof chunk === "string" || chunk.sourceNodePath || !options.sourceNodePath) return chunk;
+        return { ...chunk, sourceNodePath: [...options.sourceNodePath] };
+      });
+      const value = await client.synthesizeChunks(normalizedChunks, {
+        onProgress: options.onProgress,
+        outputFormat: options.outputFormat,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+        sourceNodePath: options.sourceNodePath
+      });
       return { ok: true, success: true, status: "success", value };
     }
     const results = [];
     for (const [index, chunk] of chunks.entries()) {
       const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
       const sourceNodePath = input.sourceNodePath;
+      const originalTextRange = input.originalTextRange;
       pending(index, "synthesizing");
       const startedAt = Date.now();
       try {
-        const result = await client.synthesizeSsml(input.ssml);
+        const result = await client.synthesizeSsml(input.ssml, {
+          outputFormat: options.outputFormat,
+          signal: options.signal,
+          timeoutMs: options.timeoutMs,
+          sourceNodePath: input.sourceNodePath ?? options.sourceNodePath
+        });
         results.push({
           ...result,
           ...input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {},
           ...sourceNodePath ? {
             boundaries: result.boundaries?.map((event) => ({
               ...event,
-              sourceNodePath: [...sourceNodePath]
+              sourceNodePath: [...sourceNodePath],
+              ...event.originalTextRange ? { originalTextRange: { ...event.originalTextRange } } : input.originalTextRange ? { originalTextRange: { ...input.originalTextRange } } : {}
             })),
-            visemes: result.visemes?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] })),
-            bookmarks: result.bookmarks?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] }))
+            visemes: result.visemes?.map((event) => ({
+              ...event,
+              sourceNodePath: [...sourceNodePath],
+              ...event.originalTextRange ? { originalTextRange: { ...event.originalTextRange } } : input.originalTextRange ? { originalTextRange: { ...input.originalTextRange } } : {}
+            })),
+            bookmarks: result.bookmarks?.map((event) => ({
+              ...event,
+              sourceNodePath: [...sourceNodePath],
+              ...event.originalTextRange ? { originalTextRange: { ...event.originalTextRange } } : input.originalTextRange ? { originalTextRange: { ...input.originalTextRange } } : {}
+            }))
+          } : {},
+          ...originalTextRange ? {
+            boundaries: result.boundaries?.map((event) => ({
+              ...event,
+              originalTextRange: event.originalTextRange ? { ...event.originalTextRange } : { ...originalTextRange }
+            })),
+            wordBoundary: result.wordBoundary?.map((event) => ({
+              ...event,
+              originalTextRange: event.originalTextRange ? { ...event.originalTextRange } : { ...originalTextRange }
+            })),
+            wordBoundaries: result.wordBoundaries?.map((event) => ({
+              ...event,
+              originalTextRange: event.originalTextRange ? { ...event.originalTextRange } : { ...originalTextRange }
+            })),
+            visemes: result.visemes?.map((event) => ({
+              ...event,
+              originalTextRange: event.originalTextRange ? { ...event.originalTextRange } : { ...originalTextRange }
+            })),
+            bookmarks: result.bookmarks?.map((event) => ({
+              ...event,
+              originalTextRange: event.originalTextRange ? { ...event.originalTextRange } : { ...originalTextRange }
+            }))
           } : {}
         });
         options.onProgress?.({
@@ -671,13 +867,23 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
       ok: true,
       success: true,
       status: "success",
-      value: mergeSynthesisResults(results, options.outputFormat)
+      value: mergeSynthesisResults(results, {
+        format: options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3"
+      })
     };
   } catch (error) {
-    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
-    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+    const synthesisError = toSynthesisError(error);
+    return failure(synthesisError);
   }
 }
+function withValidationSignal(options, signal) {
+  if (!signal) return options;
+  return {
+    ...options,
+    urlValidatorSignal: signal,
+    urlValidation: { ...options.urlValidation ?? {}, signal }
+  };
+}
 
 // src/client.ts
 var ENDPOINT_TEMPLATE = "https://{region}.tts.speech.microsoft.com/cognitiveservices/v1";
@@ -694,11 +900,21 @@ var AzureTtsClient = class {
     const config = { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs };
     return synthesizeSpeech(ssml, config);
   }
-  async synthesizeSsml(ssml) {
+  async synthesizeSsml(ssml, options = {}) {
     const { region, subscriptionKey, outputFormat, signal, timeoutMs } = __privateGet(this, _options);
     const endpoint = __privateGet(this, _options).endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     __privateGet(this, _options).logger?.debug?.("Using Azure TTS endpoint:", endpoint);
-    return synthesizeSsml(ssml, { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs });
+    return synthesizeSsml(ssml, {
+      endpoint,
+      region,
+      subscriptionKey,
+      outputFormat: options.outputFormat ?? outputFormat,
+      signal: options.signal ?? signal,
+      timeoutMs: options.timeoutMs ?? timeoutMs,
+      sourceNodePath: options.sourceNodePath,
+      sourceTextSegments: options.sourceTextSegments,
+      sourceMarkers: options.sourceMarkers
+    });
   }
   async synthesizeChunks(chunks, options = {}) {
     const { region, subscriptionKey, outputFormat, signal, timeoutMs } = __privateGet(this, _options);
@@ -707,9 +923,10 @@ var AzureTtsClient = class {
       endpoint,
       region,
       subscriptionKey,
-      outputFormat,
-      signal,
-      timeoutMs,
+      outputFormat: options.outputFormat ?? outputFormat,
+      signal: options.signal ?? signal,
+      timeoutMs: options.timeoutMs ?? timeoutMs,
+      sourceNodePath: options.sourceNodePath,
       onProgress: options.onProgress ?? __privateGet(this, _options).onProgress
     });
   }
@@ -720,6 +937,8 @@ var AzureTtsClient = class {
     return synthesizeSsmlChunksSafe(this, chunks, {
       ...options,
       outputFormat: options.outputFormat ?? __privateGet(this, _options).outputFormat,
+      signal: options.signal ?? __privateGet(this, _options).signal,
+      timeoutMs: options.timeoutMs ?? __privateGet(this, _options).timeoutMs,
       onProgress: options.onProgress ?? __privateGet(this, _options).onProgress
     });
   }
@@ -821,12 +1040,17 @@ async function fetchAzureVoiceCatalog(options) {
   AzureTtsError,
   AzureTtsSdkError,
   ChunkValidationError,
+  DEFAULT_OUTPUT_FORMAT,
+  MergeError,
+  SynthesisCancelledError,
+  SynthesisTimeoutError,
   UnsupportedMergeFormatError,
   canMergeAudioFormat,
   fetchAzureVoiceCatalog,
   mergeAudioBuffers,
   mergeSynthesisResults,
   resolveMergeAudioFormat,
+  resolveMimeType,
   synthesizeSpeech,
   synthesizeSsml,
   synthesizeSsmlChunks,