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

package/dist/index.mjs

@@ -8,7 +8,7 @@ var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "
 
 // src/errors.ts
 var AzureTtsError = class extends Error {
-  constructor(status, statusText, responseBody, requestId) {
+  constructor(status, statusText, responseBody, requestId, responseHeaders) {
     super(`Azure TTS request failed: ${status} ${statusText}`);
     this.kind = "azure-api-error";
     this.name = "AzureTtsError";
@@ -16,8 +16,37 @@ var AzureTtsError = class extends Error {
     this.statusText = statusText;
     this.responseBody = responseBody;
     this.requestId = requestId;
+    const value = responseHeaders instanceof Headers ? responseHeaders.get("retry-after") : responseHeaders?.["retry-after"] ?? responseHeaders?.["Retry-After"];
+    const seconds = value ? Number(value.trim()) : NaN;
+    const date = value ? Date.parse(value) : NaN;
+    if (Number.isFinite(seconds) && seconds >= 0) this.retryAfterMs = seconds * 1e3;
+    else if (Number.isFinite(date)) this.retryAfterMs = Math.max(0, date - Date.now());
   }
 };
+function getRetryAfterDelayMs(error) {
+  if (error instanceof AzureTtsError && error.retryAfterMs !== void 0) return error.retryAfterMs;
+  if (!error || typeof error !== "object") return void 0;
+  const candidate = error;
+  if (typeof candidate.retryAfterMs === "number" && candidate.retryAfterMs >= 0) return candidate.retryAfterMs;
+  const headers = candidate.headers ?? candidate.response?.headers;
+  if (headers instanceof Headers) {
+    const value = headers.get("retry-after");
+    if (!value) return void 0;
+    const seconds = Number(value.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : void 0;
+  }
+  if (headers && typeof headers === "object") {
+    const value = headers["retry-after"] ?? headers["Retry-After"];
+    if (typeof value !== "string") return void 0;
+    const seconds = Number(value.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : void 0;
+  }
+  return void 0;
+}
 var AzureTtsSdkError = class extends AzureTtsError {
   constructor(errorDetails) {
     super(0, "Speech SDK", errorDetails, null);
@@ -48,6 +77,14 @@ var MergeError = class extends Error {
     this.cause = cause;
   }
 };
+var AudioFormatMismatchError = class extends Error {
+  constructor(message, inputSpecs = []) {
+    super(message);
+    this.kind = "audio-format-mismatch";
+    this.name = "AudioFormatMismatchError";
+    this.inputSpecs = inputSpecs;
+  }
+};
 var UnsupportedMergeFormatError = class extends Error {
   constructor(format) {
     super(`Audio format "${format}" cannot be safely concatenated; container re-multiplexing is required.`);
@@ -57,7 +94,7 @@ var UnsupportedMergeFormatError = class extends Error {
   }
 };
 function toSynthesisError(error) {
-  if (error instanceof AzureTtsError || error instanceof MergeError || error instanceof UnsupportedMergeFormatError || error instanceof SynthesisCancelledError || error instanceof SynthesisTimeoutError)
+  if (error instanceof AzureTtsError || error instanceof MergeError || error instanceof AudioFormatMismatchError || 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);
@@ -187,6 +224,115 @@ function parseWav(buffer) {
   }
   return { chunks, data, format };
 }
+function formatNumber(format, pattern, fallback) {
+  const match = pattern.exec(format);
+  return match?.[1] ? Number(match[1]) : fallback;
+}
+function formatChannels(format, fallback) {
+  if (/stereo|2ch|dual/i.test(format)) return 2;
+  if (/mono|1ch/i.test(format)) return 1;
+  return fallback;
+}
+function formatAudioSpecification(format) {
+  const sampleRate = formatNumber(format, /(\d+)(?:khz|kHz|hz|Hz)/, 0);
+  const channels = formatChannels(format, 0);
+  const bitrateMatch = /(\d+)(?:kbitrate|kbps|kbits?)/i.exec(format);
+  const bitrate = bitrateMatch?.[1] ? Number(bitrateMatch[1]) * 1e3 : void 0;
+  const codec = /mp3|mpeg/i.test(format) ? "mp3" : /opus/i.test(format) ? "opus" : /silk/i.test(format) ? "silk" : /pcm|mulaw|alaw|siren/i.test(format) ? "pcm" : "unknown";
+  const bitDepthMatch = /(\d+)bit/i.exec(format);
+  const container = /(?:wav|wave|riff)/i.test(format) ? "riff-wave" : /mp3|mpeg/i.test(format) ? "mp3-raw" : /ogg/i.test(format) ? "ogg" : /webm/i.test(format) ? "webm" : /raw/i.test(format) ? "raw" : void 0;
+  return {
+    format,
+    mimeType: resolveMimeType(format),
+    codec,
+    sampleRate,
+    channels,
+    ...bitrate ? { bitrate } : {},
+    ...bitDepthMatch?.[1] ? { bitDepth: Number(bitDepthMatch[1]) } : {},
+    ...container ? { container } : {},
+    isVbr: /vbr/i.test(format),
+    isCompressed: codec === "mp3" || codec === "opus" || codec === "silk"
+  };
+}
+function parseMp3Specification(buffer, format) {
+  const bytes = stripMp3Tags(buffer);
+  const bitrates = [
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0],
+    [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 0]
+  ];
+  const sampleRates = [
+    [44100, 48e3, 32e3],
+    [22050, 24e3, 16e3],
+    [11025, 12e3, 8e3]
+  ];
+  for (let index = 0; index + 4 <= bytes.length; index += 1) {
+    if (bytes[index] !== 255 || (bytes[index + 1] ?? 0) < 224) continue;
+    const header = bytes[index + 1] ?? 0;
+    const versionBits = header >> 3 & 3;
+    const layer = header >> 1 & 3;
+    const bitrateIndex = (bytes[index + 2] ?? 0) >> 4;
+    const sampleIndex = (bytes[index + 2] ?? 0) >> 2 & 3;
+    if (versionBits === 1 || layer !== 1 || bitrateIndex === 0 || bitrateIndex === 15 || sampleIndex === 3) continue;
+    const versionIndex = versionBits === 3 ? 0 : versionBits === 2 ? 1 : 2;
+    const bitrateTable = versionBits === 3 ? bitrates[1] : bitrates[2];
+    const sampleRate = sampleRates[versionIndex]?.[sampleIndex] ?? 0;
+    const bitrateKbps = bitrateTable?.[bitrateIndex] ?? 0;
+    if (!sampleRate || !bitrateKbps) continue;
+    return {
+      format,
+      mimeType: "audio/mpeg",
+      codec: "mp3",
+      sampleRate,
+      channels: (bytes[index + 3] ?? 0) >> 6 === 3 ? 1 : 2,
+      bitrate: bitrateKbps * 1e3,
+      container: "mp3-raw",
+      isVbr: false,
+      isCompressed: true
+    };
+  }
+  return void 0;
+}
+function inspectAudioSpecification(buffer, format) {
+  if (isWavFormat(format) || ascii(new Uint8Array(buffer), 0, "RIFF")) {
+    const parsed = parseWav(buffer);
+    if (parsed.format.byteLength < 16) throw new Error("Invalid WAV fmt chunk.");
+    const view = new DataView(parsed.format.buffer, parsed.format.byteOffset, parsed.format.byteLength);
+    const sampleRate = view.getUint32(4, true);
+    const channels = view.getUint16(2, true);
+    const bitsPerSample = parsed.format.byteLength >= 16 ? view.getUint16(14, true) : 0;
+    const formatCode = view.getUint16(0, true);
+    return {
+      format,
+      mimeType: "audio/wav",
+      codec: formatCode === 1 ? "pcm" : "unknown",
+      sampleRate,
+      channels,
+      ...sampleRate && channels && bitsPerSample ? { bitrate: sampleRate * channels * bitsPerSample } : {},
+      bitDepth: bitsPerSample,
+      container: "riff-wave",
+      isVbr: false,
+      isCompressed: formatCode !== 1
+    };
+  }
+  if (isMp3Format(format)) return parseMp3Specification(buffer, format) ?? formatAudioSpecification(format);
+  return formatAudioSpecification(format);
+}
+function validateAudioSpecifications(specs) {
+  const first = specs[0];
+  if (!first) return;
+  const mismatch = specs.find(
+    (spec) => spec.sampleRate !== first.sampleRate || spec.channels !== first.channels || first.bitrate !== void 0 && spec.bitrate !== void 0 && spec.bitrate !== first.bitrate || first.bitDepth !== void 0 && spec.bitDepth !== void 0 && spec.bitDepth !== first.bitDepth || first.container !== void 0 && spec.container !== void 0 && spec.container !== first.container || first.isVbr !== void 0 && spec.isVbr !== void 0 && spec.isVbr !== first.isVbr
+  );
+  if (mismatch)
+    throw new AudioFormatMismatchError(
+      `Audio chunks have incompatible specifications: ${first.sampleRate}Hz/${first.channels}ch versus ${mismatch.sampleRate}Hz/${mismatch.channels}ch.`,
+      specs
+    );
+}
+function isAudioFormatMismatch(error) {
+  return error instanceof AudioFormatMismatchError || error !== null && typeof error === "object" && "kind" in error && error.kind === "audio-format-mismatch";
+}
 function writeUint32(target, offset, value) {
   new DataView(target.buffer).setUint32(offset, value, true);
 }
@@ -272,6 +418,7 @@ function mergeAudioBuffers(buffers, options) {
   const format = typeof options === "string" ? options : options?.format;
   if (!format) throw new UnsupportedMergeFormatError("");
   try {
+    validateAudioSpecifications(buffers.map((buffer) => inspectAudioSpecification(buffer, format)));
     if (isWavFormat(format)) return mergeWavBuffers(buffers);
     if (isMp3Format(format)) {
       const parts = buffers.map(stripMp3Tags);
@@ -294,7 +441,8 @@ function mergeAudioBuffers(buffers, options) {
     }
     throw new UnsupportedMergeFormatError(format);
   } catch (error) {
-    if (error instanceof UnsupportedMergeFormatError || error instanceof MergeError) throw error;
+    if (error instanceof UnsupportedMergeFormatError || isAudioFormatMismatch(error) || error instanceof MergeError)
+      throw error;
     throw new MergeError(`Audio buffers could not be merged for format "${format}".`, error);
   }
 }
@@ -372,17 +520,24 @@ async function synthesizeSsml(ssml, config) {
         return {
           originalTextRange: { ...marker.originalTextRange },
           sourceNodePath: [...marker.sourceNodePath],
-          textRange: { ...marker.originalTextRange }
+          textRange: { ...marker.originalTextRange },
+          mappingStatus: "exact"
         };
       }
-      if (sourceSegments.length === 0 && !config.sourceTextRange && !config.sourceNodePath) return {};
+      if (sourceSegments.length === 0 && !config.sourceTextRange && !config.sourceNodePath) {
+        return { mappingStatus: "unmapped" };
+      }
       const value = text ?? "";
       let localStart = Number.isFinite(offsetHint) && (offsetHint ?? 0) >= 0 ? offsetHint : -1;
-      if (value && localStart >= 0 && sourceText.slice(localStart, localStart + value.length) !== value)
+      let mappingStatus = "exact";
+      if (value && localStart >= 0 && sourceText.slice(localStart, localStart + value.length) !== value) {
         localStart = -1;
+        mappingStatus = "fallback";
+      }
       if (localStart < 0 || localStart > sourceText.length) {
         localStart = value ? sourceText.indexOf(value, sourceEventCursor) : sourceEventCursor;
         if (localStart < 0) localStart = value ? sourceText.indexOf(value) : sourceEventCursor;
+        mappingStatus = "fallback";
       }
       localStart = Math.max(0, localStart);
       const localEnd = Math.min(sourceText.length, localStart + value.length);
@@ -393,7 +548,8 @@ async function synthesizeSsml(ssml, config) {
       return {
         originalTextRange: { ...fallbackRange },
         textRange: { ...fallbackRange },
-        ...segment ? { sourceNodePath: [...segment.sourceNodePath] } : config.sourceNodePath ? { sourceNodePath: [...config.sourceNodePath] } : {}
+        ...segment ? { sourceNodePath: [...segment.sourceNodePath] } : config.sourceNodePath ? { sourceNodePath: [...config.sourceNodePath] } : {},
+        mappingStatus: segment || config.sourceTextRange || config.sourceNodePath ? mappingStatus : "unmapped"
       };
     };
     synthesizer.wordBoundary = (_sender, event) => {
@@ -442,20 +598,32 @@ async function synthesizeSsml(ssml, config) {
       );
       const durationMs = result.audioDuration ? ticksToMilliseconds(result.audioDuration) : eventDurationMs;
       const requestId = result.resultId;
-      const addSourceMetadata = (event) => ({
-        ...event,
-        ...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 } : {}
-      });
+      const addSourceMetadata = (event) => {
+        const mapped = {
+          ...event,
+          ...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 } : {}
+        };
+        if (event.mappingStatus === "unmapped") {
+          Object.defineProperty(mapped, "mappingStatus", { value: "unmapped", enumerable: false });
+          Object.defineProperty(mapped, "toJSON", {
+            value: () => ({ ...mapped, mappingStatus: "unmapped" }),
+            enumerable: false
+          });
+        }
+        return mapped;
+      };
       const sourceBoundaries = boundaries.map((boundary) => addSourceMetadata(boundary));
       const sourceVisemes = visemes.map((viseme) => addSourceMetadata(viseme));
       const sourceBookmarks = bookmarks.map((bookmark) => addSourceMetadata(bookmark));
       resolve({
         audioData: result.audioData,
         durationMs,
+        audioSpec: inspectAudioSpecification(result.audioData, config.outputFormat ?? DEFAULT_OUTPUT_FORMAT),
+        mimeType: resolveMimeType(config.outputFormat ?? DEFAULT_OUTPUT_FORMAT),
         ...config.sourceTextRange ? { textRange: { ...config.sourceTextRange } } : {},
         ...requestId ? { requestId } : {},
         ...sourceBoundaries.length > 0 ? { boundaries: sourceBoundaries, wordBoundary: sourceBoundaries, wordBoundaries: sourceBoundaries } : {},
@@ -468,10 +636,11 @@ async function synthesizeSsml(ssml, config) {
         abortHandler = () => rejectWithError(new SynthesisCancelledError());
         config.signal.addEventListener("abort", abortHandler, { once: true });
       }
-      if (config.timeoutMs !== void 0 && config.timeoutMs > 0) {
+      const timeoutMs = config.timeouts?.perChunkMs ?? config.timeoutMs;
+      if (timeoutMs !== void 0 && timeoutMs > 0) {
         timeout = setTimeout(
-          () => rejectWithError(new SynthesisTimeoutError(`Speech synthesis timed out after ${config.timeoutMs} ms.`)),
-          config.timeoutMs
+          () => rejectWithError(new SynthesisTimeoutError(`Speech synthesis timed out after ${timeoutMs} ms.`)),
+          timeoutMs
         );
       }
       synthesizer.speakSsmlAsync(ssml, cb, rejectWithError);
@@ -480,9 +649,109 @@ async function synthesizeSsml(ssml, config) {
     }
   });
 }
+function isRetryableSynthesisError(error) {
+  if (error instanceof SynthesisCancelledError || error instanceof SynthesisTimeoutError) return false;
+  if (error instanceof AzureTtsError && error.status !== 0)
+    return error.status === 429 || error.status >= 500 && error.status < 600;
+  const message = error instanceof Error ? error.message : String(error);
+  if (/\b4\d{2}\b/.test(message)) return false;
+  const status = error && typeof error === "object" && "status" in error ? error.status : void 0;
+  if (typeof status === "number") return status === 429 || status >= 500 && status < 600;
+  return /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message);
+}
+function retryDelay(options, retryAttempt, error) {
+  const retryAfterMs = getRetryAfterDelayMs(error);
+  if (retryAfterMs !== void 0) return retryAfterMs;
+  const base = Math.min(options.maxDelayMs, options.initialDelayMs * 2 ** Math.max(0, retryAttempt - 1));
+  return Math.floor(Math.random() * (base + 1));
+}
+function resolveConcurrency(value, total) {
+  if (value === void 0) return 1;
+  if (value === Infinity) return Math.max(1, total);
+  return Number.isFinite(value) ? Math.max(1, Math.floor(value)) : 1;
+}
+async function waitForRetry(delayMs, signal) {
+  if (signal?.aborted) throw new SynthesisCancelledError();
+  if (delayMs <= 0) return;
+  await new Promise((resolve, reject) => {
+    let timer;
+    const abort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      reject(new SynthesisCancelledError());
+    };
+    timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, delayMs);
+    if (signal) {
+      signal.addEventListener("abort", abort, { once: true });
+    }
+  });
+}
+async function synthesizeWithRetry(ssml, config, retryOptions, onRetry) {
+  const options = retryOptions ? {
+    maxRetries: Math.max(0, Math.floor(retryOptions.maxRetries)),
+    initialDelayMs: Math.max(0, retryOptions.initialDelayMs),
+    maxDelayMs: Math.max(0, retryOptions.maxDelayMs),
+    shouldRetry: retryOptions.shouldRetry
+  } : void 0;
+  let attempt = 0;
+  while (true) {
+    if (config.signal?.aborted) throw new SynthesisCancelledError();
+    try {
+      return await synthesizeSsml(ssml, config);
+    } catch (error) {
+      if (!options || attempt >= options.maxRetries || !(options.shouldRetry?.(error, attempt + 1) ?? isRetryableSynthesisError(error)))
+        throw error;
+      attempt += 1;
+      const delayMs = retryDelay(options, attempt, error);
+      onRetry(attempt, delayMs);
+      await waitForRetry(delayMs, config.signal);
+    }
+  }
+}
+function createAbortScope(parent, timeoutMs) {
+  const controller = new AbortController();
+  let didTimeout = false;
+  const onAbort = () => controller.abort();
+  if (parent?.aborted) controller.abort();
+  parent?.addEventListener("abort", onAbort, { once: true });
+  const timer = timeoutMs !== void 0 && timeoutMs > 0 ? setTimeout(() => {
+    didTimeout = true;
+    controller.abort();
+  }, timeoutMs) : void 0;
+  return {
+    signal: controller.signal,
+    timedOut: () => didTimeout,
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      parent?.removeEventListener("abort", onAbort);
+    },
+    abort: () => controller.abort()
+  };
+}
+async function synthesizeChunkWithTimeout(ssml, config, retryOptions, timeoutMs, onRetry) {
+  const scope = createAbortScope(config.signal, timeoutMs);
+  try {
+    return await synthesizeWithRetry(ssml, { ...config, signal: scope.signal }, retryOptions, onRetry);
+  } catch (error) {
+    if (scope.timedOut()) throw new SynthesisTimeoutError(`Speech synthesis timed out after ${timeoutMs} ms.`);
+    throw error;
+  } finally {
+    scope.dispose();
+  }
+}
 async function synthesizeSsmlChunks(chunks, config) {
-  const results = [];
+  const results = new Array(chunks.length);
   const totalChunks = chunks.length;
+  const cachedChunks = new Map((config.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+  for (const [index, cached] of cachedChunks) {
+    if (index >= 0 && index < totalChunks) results[index] = cached;
+  }
+  const requestedIndices = config.resumeChunkIndices ? new Set(config.resumeChunkIndices.filter((index) => index >= 0 && index < totalChunks)) : void 0;
+  const shouldSynthesize = (index) => !cachedChunks.has(index) && (requestedIndices === void 0 || requestedIndices.has(index));
+  const scope = createAbortScope(config.signal, config.timeouts?.totalJobMs);
   const report = (event) => config.onProgress?.(event);
   for (const [index, chunk] of chunks.entries()) {
     const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
@@ -496,57 +765,112 @@ async function synthesizeSsmlChunks(chunks, config) {
       durationMs: 0
     });
   }
-  for (const [index, chunk] of chunks.entries()) {
-    const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
-    report({
-      currentChunk: index,
-      totalChunks,
-      percent: totalChunks === 0 ? 100 : Math.round(index / totalChunks * 100),
-      chunkIndex: index,
-      originalTextRange: input.originalTextRange,
-      status: "synthesizing",
-      durationMs: 0
-    });
-    const startedAt = Date.now();
-    try {
-      const result = await synthesizeSsml(input.ssml, {
-        ...config,
-        ...input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {},
-        ...input.sourceNodePath ?? config.sourceNodePath ? { sourceNodePath: [...input.sourceNodePath ?? config.sourceNodePath ?? []] } : {},
-        ...input.sourceTextSegments ? { sourceTextSegments: input.sourceTextSegments } : {},
-        ...input.sourceMarkers ? { sourceMarkers: input.sourceMarkers } : {},
-        chunkIndex: index,
-        onProgress: void 0
-      });
-      results.push(result);
-      report({
-        currentChunk: index + 1,
-        totalChunks,
-        percent: totalChunks === 0 ? 100 : Math.round((index + 1) / totalChunks * 100),
-        chunkIndex: index,
-        originalTextRange: input.originalTextRange,
-        status: "success",
-        durationMs: Date.now() - startedAt
-      });
-    } catch (error) {
+  let completed = [...results].filter((result) => result !== void 0).length;
+  let nextIndex = 0;
+  const concurrency = resolveConcurrency(config.concurrency, chunks.length);
+  let firstError;
+  const failedIndices = /* @__PURE__ */ new Set();
+  const worker = async () => {
+    while (true) {
+      const index = nextIndex++;
+      if (index >= chunks.length) return;
+      if (!shouldSynthesize(index)) continue;
+      if (firstError && config.cancelOnFailure !== false) return;
+      const chunk = chunks[index];
+      const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
       report({
-        currentChunk: index,
+        currentChunk: completed,
         totalChunks,
-        percent: totalChunks === 0 ? 100 : Math.round(index / totalChunks * 100),
+        percent: totalChunks === 0 ? 100 : Math.round(completed / totalChunks * 100),
         chunkIndex: index,
         originalTextRange: input.originalTextRange,
-        status: "failed",
-        durationMs: Date.now() - startedAt,
-        error
+        status: "synthesizing",
+        durationMs: 0
       });
-      throw error;
+      const startedAt = Date.now();
+      try {
+        const result = await synthesizeChunkWithTimeout(
+          input.ssml,
+          {
+            ...config,
+            signal: scope.signal,
+            ...input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {},
+            ...input.sourceNodePath ?? config.sourceNodePath ? { sourceNodePath: [...input.sourceNodePath ?? config.sourceNodePath ?? []] } : {},
+            ...input.sourceTextSegments ? { sourceTextSegments: input.sourceTextSegments } : {},
+            ...input.sourceMarkers ? { sourceMarkers: input.sourceMarkers } : {},
+            chunkIndex: index,
+            onProgress: void 0
+          },
+          config.retryOptions,
+          config.timeouts?.chunkWithRetriesMs ?? config.timeouts?.perChunkMs ?? config.timeoutMs,
+          (retryAttempt, nextRetryDelayMs) => report({
+            currentChunk: completed,
+            totalChunks,
+            percent: totalChunks === 0 ? 100 : Math.round(completed / totalChunks * 100),
+            chunkIndex: index,
+            originalTextRange: input.originalTextRange,
+            status: "synthesizing",
+            durationMs: Date.now() - startedAt,
+            retryAttempt,
+            nextRetryDelayMs,
+            isRetrying: true
+          })
+        );
+        results[index] = result;
+        completed += 1;
+        report({
+          currentChunk: completed,
+          totalChunks,
+          percent: totalChunks === 0 ? 100 : Math.round(completed / totalChunks * 100),
+          chunkIndex: index,
+          originalTextRange: input.originalTextRange,
+          status: "success",
+          durationMs: Date.now() - startedAt
+        });
+      } catch (error) {
+        failedIndices.add(index);
+        report({
+          currentChunk: completed,
+          totalChunks,
+          percent: totalChunks === 0 ? 100 : Math.round(completed / totalChunks * 100),
+          chunkIndex: index,
+          originalTextRange: input.originalTextRange,
+          status: "failed",
+          durationMs: Date.now() - startedAt,
+          error
+        });
+        firstError ?? (firstError = scope.timedOut() ? new SynthesisTimeoutError(`Speech synthesis timed out after ${config.timeouts?.totalJobMs} ms.`) : error);
+        if (config.cancelOnFailure !== false) scope.abort();
+        return;
+      }
     }
+  };
+  try {
+    await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    if (firstError) throw firstError;
+    const orderedResults = results.filter((result) => result !== void 0);
+    return await mergeSynthesisResults(orderedResults, {
+      format: config.outputFormat ?? DEFAULT_OUTPUT_FORMAT,
+      signal: scope.signal,
+      customMerger: config.customMerger,
+      outputMimeType: config.outputMimeType,
+      postMergeValidator: config.postMergeValidator
+    });
+  } catch (error) {
+    const partial = {
+      synthesizedChunks: results.flatMap((result, chunkIndex) => result ? [{ ...result, chunkIndex }] : []),
+      completedChunks: results.flatMap((result, chunkIndex) => result ? [{ ...result, chunkIndex }] : []),
+      pendingChunkIndices: chunks.flatMap((_chunk, chunkIndex) => results[chunkIndex] ? [] : [chunkIndex]),
+      failedChunkIndices: [...failedIndices],
+      totalChunks
+    };
+    if (error && typeof error === "object") error.partialResult = partial;
+    throw error;
+  } finally {
+    scope.dispose();
   }
-  return mergeSynthesisResults(results, {
-    format: config.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3"
-  });
 }
-function createMergedResult(results, audioData, format) {
+function createMergedResult(results, audioData, format, audioSpec, outputMimeType) {
   const boundaries = [];
   const visemes = [];
   const bookmarks = [];
@@ -565,7 +889,8 @@ function createMergedResult(results, audioData, format) {
         ...boundary.sourceNodePath ? { sourceNodePath: [...boundary.sourceNodePath] } : {},
         ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
-        ...requestId ? { requestId } : {}
+        ...requestId ? { requestId } : {},
+        mappingStatus: boundary.mappingStatus ?? "unmapped"
       });
     }
     for (const viseme of result.visemes ?? []) {
@@ -580,7 +905,8 @@ function createMergedResult(results, audioData, format) {
         ...viseme.sourceNodePath ? { sourceNodePath: [...viseme.sourceNodePath] } : {},
         ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
-        ...requestId ? { requestId } : {}
+        ...requestId ? { requestId } : {},
+        mappingStatus: viseme.mappingStatus ?? "unmapped"
       });
     }
     for (const bookmark of result.bookmarks ?? []) {
@@ -595,7 +921,8 @@ function createMergedResult(results, audioData, format) {
         ...bookmark.sourceNodePath ? { sourceNodePath: [...bookmark.sourceNodePath] } : {},
         ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
-        ...requestId ? { requestId } : {}
+        ...requestId ? { requestId } : {},
+        mappingStatus: bookmark.mappingStatus ?? "unmapped"
       });
     }
     durationOffset += Math.max(0, result.durationMs);
@@ -604,6 +931,8 @@ function createMergedResult(results, audioData, format) {
     audioData,
     durationMs: durationOffset,
     mimeType: resolveMimeType(format),
+    audioSpec: audioSpec ?? formatAudioSpecification(format),
+    ...outputMimeType ? { mimeType: outputMimeType } : {},
     ...boundaries.length > 0 ? { boundaries, wordBoundary: boundaries, wordBoundaries: boundaries } : {},
     ...visemes.length > 0 ? { visemes } : {},
     ...bookmarks.length > 0 ? { bookmarks } : {},
@@ -616,19 +945,73 @@ function mergeSynthesisResults(results, options) {
   const format = resolvedOptions?.format;
   if (!format) throw new UnsupportedMergeFormatError("");
   const buffers = results.map((result) => result.audioData);
+  const inputSpecs = results.map((result) => result.audioSpec ?? inspectAudioSpecification(result.audioData, format));
+  validateAudioSpecifications(inputSpecs);
+  const signal = resolvedOptions.signal ?? new AbortController().signal;
+  if (signal.aborted) throw new SynthesisCancelledError();
   if (resolvedOptions.customMerger) {
-    return Promise.resolve().then(() => resolvedOptions.customMerger?.(buffers, format)).then((merged) => {
+    return Promise.resolve().then(
+      () => resolvedOptions.customMerger?.(buffers, {
+        format,
+        outputMimeType: resolvedOptions.outputMimeType ?? resolveMimeType(format),
+        inputSpecs,
+        signal
+      })
+    ).then((merged) => {
       if (!merged) throw new MergeError("The custom audio merger returned no audio buffer.");
-      return createMergedResult(results, merged, format);
+      if (!(merged instanceof ArrayBuffer) || buffers.some((buffer) => buffer.byteLength > 0) && merged.byteLength === 0)
+        throw new MergeError("The custom audio merger returned an invalid audio buffer.");
+      if (signal.aborted) throw new SynthesisCancelledError();
+      const result = createMergedResult(
+        results,
+        merged,
+        format,
+        inspectAudioSpecification(merged, format),
+        resolvedOptions.outputMimeType
+      );
+      return Promise.resolve(
+        resolvedOptions.postMergeValidator?.(result, {
+          format,
+          outputMimeType: resolvedOptions.outputMimeType ?? resolveMimeType(format),
+          inputSpecs,
+          signal
+        })
+      ).then((valid) => {
+        if (valid === false) throw new MergeError("The post-merge validator rejected the merged audio.");
+        return result;
+      });
     }).catch((error) => {
-      if (error instanceof UnsupportedMergeFormatError || error instanceof MergeError) throw error;
+      if (error instanceof UnsupportedMergeFormatError || isAudioFormatMismatch(error) || error instanceof MergeError)
+        throw error;
       throw new MergeError(`Custom audio merger failed for format "${format}".`, error);
     });
   }
   try {
-    return createMergedResult(results, mergeAudioBuffers(buffers, { format }), format);
+    const result = createMergedResult(
+      results,
+      mergeAudioBuffers(buffers, { format }),
+      format,
+      inputSpecs[0],
+      resolvedOptions.outputMimeType
+    );
+    if (resolvedOptions.postMergeValidator) {
+      const validation = resolvedOptions.postMergeValidator(result, {
+        format,
+        outputMimeType: resolvedOptions.outputMimeType ?? resolveMimeType(format),
+        inputSpecs,
+        signal
+      });
+      if (validation instanceof Promise)
+        return validation.then((valid) => {
+          if (valid === false) throw new MergeError("The post-merge validator rejected the merged audio.");
+          return result;
+        });
+      if (validation === false) throw new MergeError("The post-merge validator rejected the merged audio.");
+    }
+    return result;
   } catch (error) {
-    if (error instanceof UnsupportedMergeFormatError || error instanceof MergeError) throw error;
+    if (error instanceof UnsupportedMergeFormatError || isAudioFormatMismatch(error) || error instanceof MergeError)
+      throw error;
     throw new MergeError(`Audio buffers could not be merged for format "${format}".`, error);
   }
 }
@@ -637,7 +1020,10 @@ async function synthesizeSpeech(ssml, config) {
 }
 
 // src/safe.ts
-import { validateAzureSsml } from "@ssml-builder-js/ssml-core";
+import {
+  createAzureUrlValidatorRunner,
+  validateAzureSsml
+} from "@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.`);
@@ -647,11 +1033,125 @@ var ChunkValidationError = class extends Error {
     this.diagnostics = diagnostics;
   }
 };
-function failure(error) {
-  return { ok: false, success: false, status: error.kind, error };
+var BatchChunkValidationError = class extends ChunkValidationError {
+  constructor(chunkDiagnostics) {
+    const first = chunkDiagnostics[0];
+    super(first?.chunkIndex ?? -1, first?.diagnostics ?? []);
+    this.name = "BatchChunkValidationError";
+    this.message = `SSML validation failed for ${chunkDiagnostics.length} chunk(s); the Azure Speech API was not called.`;
+    this.chunkDiagnostics = chunkDiagnostics;
+    this.totalErrorCount = chunkDiagnostics.reduce((total, chunk) => total + chunk.diagnostics.length, 0);
+    this.errorCount = this.totalErrorCount;
+    this.totalErrors = this.totalErrorCount;
+  }
+};
+function failure(error, partialResult) {
+  return {
+    ok: false,
+    success: false,
+    status: error.kind,
+    error,
+    ...partialResult ? { partialResult } : {}
+  };
+}
+function partialResultFrom(error) {
+  if (!error || typeof error !== "object") return void 0;
+  const partial = error.partialResult;
+  if (!partial || typeof partial !== "object") return void 0;
+  return partial;
+}
+function createSafeAbortScope(parent, timeoutMs) {
+  const controller = new AbortController();
+  let didTimeout = false;
+  const onAbort = () => controller.abort();
+  if (parent?.aborted) controller.abort();
+  parent?.addEventListener("abort", onAbort, { once: true });
+  const timer = timeoutMs !== void 0 && timeoutMs > 0 ? setTimeout(() => {
+    didTimeout = true;
+    controller.abort();
+  }, timeoutMs) : void 0;
+  return {
+    signal: controller.signal,
+    timedOut: () => didTimeout,
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      parent?.removeEventListener("abort", onAbort);
+    },
+    abort: () => controller.abort()
+  };
+}
+function isRetryable(error) {
+  if (error instanceof Error && /cancel|abort|tim(?:e|ed) ?out/i.test(error.message)) return false;
+  const status = error && typeof error === "object" && "status" in error ? error.status : void 0;
+  if (typeof status === "number" && status !== 0) return status === 429 || status >= 500 && status < 600;
+  const message = error instanceof Error ? error.message : String(error);
+  if (/\b4\d{2}\b/.test(message)) return false;
+  return /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message);
+}
+function delayForRetry(options, attempt) {
+  const maxDelay = Math.max(0, options.maxDelayMs);
+  const base = Math.min(maxDelay, Math.max(0, options.initialDelayMs) * 2 ** Math.max(0, attempt - 1));
+  return Math.floor(Math.random() * (base + 1));
+}
+function retryDelayForError(options, attempt, error) {
+  return getRetryAfterDelayMs(error) ?? delayForRetry(options, attempt);
+}
+function resolveConcurrency2(value, total) {
+  if (value === void 0) return 1;
+  if (value === Infinity) return Math.max(1, total);
+  return Number.isFinite(value) ? Math.max(1, Math.floor(value)) : 1;
+}
+async function retryableSynthesis(synthesize, options, signal, onRetry) {
+  const retry = options ? {
+    maxRetries: Math.max(0, Math.floor(options.maxRetries)),
+    initialDelayMs: options.initialDelayMs,
+    maxDelayMs: options.maxDelayMs,
+    shouldRetry: options.shouldRetry
+  } : void 0;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) throw new Error("Speech synthesis was cancelled.");
+    try {
+      return await synthesize();
+    } catch (error) {
+      if (!retry || attempt >= retry.maxRetries || !(retry.shouldRetry?.(error, attempt + 1) ?? isRetryable(error)))
+        throw error;
+      attempt += 1;
+      const delayMs = retryDelayForError(retry, attempt, error);
+      onRetry(attempt, delayMs);
+      if (delayMs > 0)
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+          }, delayMs);
+          const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(new Error("Speech synthesis was cancelled."));
+          };
+          signal?.addEventListener("abort", abort, { once: true });
+        });
+    }
+  }
+}
+function sharedValidationOptions(options, signal) {
+  const validator = options.urlValidator ?? options.customUrlValidator;
+  if (!validator) return signal ? withValidationSignal(options, signal) : options;
+  const runner = createAzureUrlValidatorRunner(validator, {
+    ...options.urlValidation ?? {},
+    ...options.urlValidatorConcurrency !== void 0 ? { concurrency: options.urlValidatorConcurrency } : {},
+    ...options.timeouts?.urlValidationMs !== void 0 ? { timeoutMs: options.timeouts.urlValidationMs } : options.urlValidatorTimeoutMs !== void 0 ? { timeoutMs: options.urlValidatorTimeoutMs } : {},
+    ...signal ? { signal } : {},
+    ...options.urlValidatorCache ? { cache: options.urlValidatorCache } : {}
+  });
+  return {
+    ...withValidationSignal(options, signal),
+    urlValidatorRunner: runner
+  };
 }
 async function synthesizeSsmlSafe(client, ssml, options = {}) {
-  const validationOptions = withValidationSignal(options.validation ?? options, options.signal);
+  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
   const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
   if (options.signal?.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
@@ -670,7 +1170,11 @@ async function synthesizeSsmlSafe(client, ssml, options = {}) {
       ok: true,
       success: true,
       status: "success",
-      value: await client.synthesizeSsml(ssml, { signal: options.signal })
+      value: await client.synthesizeSsml(ssml, {
+        signal: options.signal,
+        timeoutMs: options.timeouts?.perChunkMs,
+        timeouts: options.timeouts
+      })
     };
   } catch (error) {
     const synthesisError = toSynthesisError(error);
@@ -678,7 +1182,10 @@ async function synthesizeSsmlSafe(client, ssml, options = {}) {
   }
 }
 async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
-  const validationOptions = withValidationSignal(options.validation ?? options, options.signal);
+  const validationOptions = sharedValidationOptions(
+    { ...options.validation ?? options, timeouts: options.timeouts },
+    options.signal
+  );
   if (options.signal?.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
     return failure(error);
@@ -699,21 +1206,30 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
     pending(index, "pending");
   });
   const validations = await Promise.all(
-    chunks.map(async (chunk) => {
+    chunks.map(async (chunk, index) => {
       const ssml = typeof chunk === "string" ? chunk : chunk.ssml;
       const sourceNodePath = typeof chunk === "string" ? options.sourceNodePath : chunk.sourceNodePath ?? options.sourceNodePath;
       const diagnostics = await Promise.resolve(
-        validateAzureSsml(ssml, { ...validationOptions, ...sourceNodePath ? { sourceNodePath } : {} })
+        validateAzureSsml(ssml, {
+          ...validationOptions,
+          ...sourceNodePath ? { sourceNodePath } : {},
+          chunkIndex: index
+        })
       );
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     })
   );
-  const firstInvalidIndex = validations.findIndex((diagnostics) => diagnostics.length > 0);
-  if (firstInvalidIndex >= 0) {
-    const error = new ChunkValidationError(firstInvalidIndex, validations[firstInvalidIndex] ?? []);
-    pending(firstInvalidIndex, "failed", error);
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
     return failure(error);
   }
+  const chunkDiagnostics = validations.map((diagnostics, chunkIndex) => ({ chunkIndex, diagnostics })).filter((entry) => entry.diagnostics.length > 0);
+  if (chunkDiagnostics.length > 0) {
+    const error = new BatchChunkValidationError(chunkDiagnostics);
+    for (const entry of chunkDiagnostics) pending(entry.chunkIndex, "failed", error);
+    return failure(error);
+  }
+  let fallbackJobScope;
   try {
     if (client.synthesizeChunks) {
       const normalizedChunks = chunks.map((chunk) => {
@@ -725,101 +1241,181 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
         outputFormat: options.outputFormat,
         signal: options.signal,
         timeoutMs: options.timeoutMs,
-        sourceNodePath: options.sourceNodePath
+        timeouts: options.timeouts,
+        sourceNodePath: options.sourceNodePath,
+        concurrency: options.concurrency,
+        retryOptions: options.retryOptions,
+        cancelOnFailure: options.cancelOnFailure,
+        resumeChunks: options.resumeChunks,
+        resumeChunkIndices: options.resumeChunkIndices,
+        customMerger: options.customMerger,
+        outputMimeType: options.outputMimeType,
+        postMergeValidator: options.postMergeValidator
       });
       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, {
-          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],
-              ...event.originalTextRange ? { originalTextRange: { ...event.originalTextRange } } : input.originalTextRange ? { originalTextRange: { ...input.originalTextRange } } : {}
-            })),
-            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?.({
-          currentChunk: index + 1,
-          totalChunks: chunks.length,
-          percent: chunks.length === 0 ? 100 : Math.round((index + 1) / chunks.length * 100),
-          chunkIndex: index,
-          originalTextRange: input.originalTextRange,
-          status: "success",
-          durationMs: Date.now() - startedAt
-        });
-      } catch (error) {
-        options.onProgress?.({
-          currentChunk: index,
-          totalChunks: chunks.length,
-          percent: chunks.length === 0 ? 100 : Math.round(index / chunks.length * 100),
-          chunkIndex: index,
-          originalTextRange: input.originalTextRange,
-          status: "failed",
-          durationMs: Date.now() - startedAt,
-          error
-        });
-        throw error;
+    const results = new Array(chunks.length);
+    const cachedChunks = new Map((options.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+    for (const [index, cached] of cachedChunks) {
+      if (index >= 0 && index < chunks.length) results[index] = cached;
+    }
+    const requestedIndices = options.resumeChunkIndices ? new Set(options.resumeChunkIndices.filter((index) => index >= 0 && index < chunks.length)) : void 0;
+    const shouldSynthesize = (index) => !cachedChunks.has(index) && (requestedIndices === void 0 || requestedIndices.has(index));
+    const jobScope = chunks.length > 1 || options.timeouts?.totalJobMs !== void 0 ? createSafeAbortScope(options.signal, options.timeouts?.totalJobMs) : void 0;
+    fallbackJobScope = jobScope;
+    const failedIndices = /* @__PURE__ */ new Set();
+    let firstError;
+    let completed = [...results].filter((result) => result !== void 0).length;
+    let nextIndex = 0;
+    const concurrency = resolveConcurrency2(options.concurrency, chunks.length);
+    const worker = async () => {
+      while (true) {
+        const index = nextIndex++;
+        if (index >= chunks.length) return;
+        if (!shouldSynthesize(index)) continue;
+        if (failedIndices.size > 0 && options.cancelOnFailure !== false) return;
+        const chunk = chunks[index];
+        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 chunkTimeout = options.timeouts?.chunkWithRetriesMs ?? options.timeouts?.perChunkMs;
+          const chunkScope = chunkTimeout !== void 0 || jobScope ? createSafeAbortScope(jobScope?.signal ?? options.signal, chunkTimeout ?? options.timeoutMs) : void 0;
+          const chunkSignal = chunkScope?.signal ?? options.signal;
+          let result;
+          try {
+            result = await retryableSynthesis(
+              () => client.synthesizeSsml(input.ssml, {
+                outputFormat: options.outputFormat,
+                signal: chunkSignal,
+                timeoutMs: options.timeouts?.perChunkMs ?? options.timeoutMs,
+                sourceNodePath: input.sourceNodePath ?? options.sourceNodePath
+              }),
+              options.retryOptions,
+              chunkSignal,
+              (retryAttempt, nextRetryDelayMs) => options.onProgress?.({
+                currentChunk: completed,
+                totalChunks: chunks.length,
+                percent: chunks.length === 0 ? 100 : Math.round(completed / chunks.length * 100),
+                chunkIndex: index,
+                originalTextRange: input.originalTextRange,
+                status: "synthesizing",
+                durationMs: Date.now() - startedAt,
+                retryAttempt,
+                nextRetryDelayMs,
+                isRetrying: true
+              })
+            );
+          } catch (error) {
+            if (chunkScope?.timedOut())
+              throw new Error(`Speech synthesis timed out after ${chunkTimeout ?? options.timeoutMs} ms.`);
+            throw error;
+          } finally {
+            chunkScope?.dispose();
+          }
+          results[index] = {
+            ...result,
+            ...input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {},
+            ...sourceNodePath ? {
+              boundaries: result.boundaries?.map((event) => ({
+                ...event,
+                sourceNodePath: [...sourceNodePath],
+                ...event.originalTextRange ? { originalTextRange: { ...event.originalTextRange } } : input.originalTextRange ? { originalTextRange: { ...input.originalTextRange } } : {}
+              })),
+              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 }
+              }))
+            } : {}
+          };
+          completed += 1;
+          options.onProgress?.({
+            currentChunk: completed,
+            totalChunks: chunks.length,
+            percent: chunks.length === 0 ? 100 : Math.round(completed / chunks.length * 100),
+            chunkIndex: index,
+            originalTextRange: input.originalTextRange,
+            status: "success",
+            durationMs: Date.now() - startedAt
+          });
+        } catch (error) {
+          failedIndices.add(index);
+          options.onProgress?.({
+            currentChunk: completed,
+            totalChunks: chunks.length,
+            percent: chunks.length === 0 ? 100 : Math.round(index / chunks.length * 100),
+            chunkIndex: index,
+            originalTextRange: input.originalTextRange,
+            status: "failed",
+            durationMs: Date.now() - startedAt,
+            error
+          });
+          if (options.cancelOnFailure !== false) jobScope?.abort();
+          firstError ?? (firstError = error);
+          return;
+        }
       }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    if (failedIndices.size > 0) {
+      const error = firstError ?? new Error("One or more SSML chunks failed to synthesize.");
+      error.partialResult = {
+        synthesizedChunks: results.flatMap((result, chunkIndex) => result ? [{ ...result, chunkIndex }] : []),
+        completedChunks: results.flatMap((result, chunkIndex) => result ? [{ ...result, chunkIndex }] : []),
+        pendingChunkIndices: chunks.flatMap((_chunk, chunkIndex) => results[chunkIndex] ? [] : [chunkIndex]),
+        failedChunkIndices: [...failedIndices],
+        totalChunks: chunks.length
+      };
+      throw error;
     }
+    const orderedResults = results.filter((result) => result !== void 0);
     return {
       ok: true,
       success: true,
       status: "success",
-      value: mergeSynthesisResults(results, {
-        format: options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3"
+      value: await mergeSynthesisResults(orderedResults, {
+        format: options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3",
+        signal: jobScope?.signal ?? options.signal,
+        customMerger: options.customMerger,
+        outputMimeType: options.outputMimeType,
+        postMergeValidator: options.postMergeValidator
       })
     };
   } catch (error) {
     const synthesisError = toSynthesisError(error);
-    return failure(synthesisError);
+    return failure(synthesisError, partialResultFrom(error));
+  } finally {
+    fallbackJobScope?.dispose();
   }
 }
 function withValidationSignal(options, signal) {
@@ -840,14 +1436,14 @@ var AzureTtsClient = class {
     __privateSet(this, _options, options);
   }
   async synthesize(ssml) {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = __privateGet(this, _options);
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = __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);
-    const config = { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs };
+    const config = { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts };
     return synthesizeSpeech(ssml, config);
   }
   async synthesizeSsml(ssml, options = {}) {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = __privateGet(this, _options);
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = __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, {
@@ -857,13 +1453,14 @@ var AzureTtsClient = class {
       outputFormat: options.outputFormat ?? outputFormat,
       signal: options.signal ?? signal,
       timeoutMs: options.timeoutMs ?? timeoutMs,
+      timeouts: options.timeouts ?? timeouts,
       sourceNodePath: options.sourceNodePath,
       sourceTextSegments: options.sourceTextSegments,
       sourceMarkers: options.sourceMarkers
     });
   }
   async synthesizeChunks(chunks, options = {}) {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = __privateGet(this, _options);
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = __privateGet(this, _options);
     const endpoint = __privateGet(this, _options).endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     return synthesizeSsmlChunks(chunks, {
       endpoint,
@@ -872,8 +1469,17 @@ var AzureTtsClient = class {
       outputFormat: options.outputFormat ?? outputFormat,
       signal: options.signal ?? signal,
       timeoutMs: options.timeoutMs ?? timeoutMs,
+      timeouts: options.timeouts ?? timeouts,
       sourceNodePath: options.sourceNodePath,
-      onProgress: options.onProgress ?? __privateGet(this, _options).onProgress
+      onProgress: options.onProgress ?? __privateGet(this, _options).onProgress,
+      concurrency: options.concurrency ?? __privateGet(this, _options).concurrency,
+      retryOptions: options.retryOptions ?? __privateGet(this, _options).retryOptions,
+      cancelOnFailure: options.cancelOnFailure,
+      resumeChunks: options.resumeChunks,
+      resumeChunkIndices: options.resumeChunkIndices,
+      customMerger: options.customMerger,
+      outputMimeType: options.outputMimeType,
+      postMergeValidator: options.postMergeValidator
     });
   }
   async synthesizeSsmlSafe(ssml, options = {}) {
@@ -885,7 +1491,10 @@ var AzureTtsClient = class {
       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
+      timeouts: options.timeouts ?? __privateGet(this, _options).timeouts,
+      onProgress: options.onProgress ?? __privateGet(this, _options).onProgress,
+      concurrency: options.concurrency ?? __privateGet(this, _options).concurrency,
+      retryOptions: options.retryOptions ?? __privateGet(this, _options).retryOptions
     });
   }
   async synthesizeSsmlChunksSafe(chunks, options = {}) {
@@ -976,14 +1585,18 @@ async function fetchAzureVoiceCatalog(options) {
       voiceCount: sortedVoices.length,
       generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
       apiVersion: AZURE_VOICE_API_VERSION,
-      regions
+      regions,
+      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1e3).toISOString(),
+      regionDiffs: {}
     }
   };
 }
 export {
+  AudioFormatMismatchError,
   AzureTtsClient,
   AzureTtsError,
   AzureTtsSdkError,
+  BatchChunkValidationError,
   ChunkValidationError,
   DEFAULT_OUTPUT_FORMAT,
   MergeError,
@@ -992,6 +1605,8 @@ export {
   UnsupportedMergeFormatError,
   canMergeAudioFormat,
   fetchAzureVoiceCatalog,
+  getRetryAfterDelayMs,
+  inspectAudioSpecification,
   mergeAudioBuffers,
   mergeSynthesisResults,
   resolveMergeAudioFormat,