ssml-builder-js 2.17.0 → 2.19.0

package/dist/index.js

@@ -44,6 +44,8 @@ __export(src_exports, {
   BatchChunkValidationError: () => BatchChunkValidationError,
   ChunkValidationError: () => ChunkValidationError,
   DEFAULT_OUTPUT_FORMAT: () => DEFAULT_OUTPUT_FORMAT,
+  DeadlineController: () => DeadlineController,
+  IncompleteChunkSetError: () => IncompleteChunkSetError,
   MergeError: () => MergeError,
   SynthesisCancelledError: () => SynthesisCancelledError,
   SynthesisTimeoutError: () => SynthesisTimeoutError,
@@ -52,6 +54,7 @@ __export(src_exports, {
   buildPartialSsml: () => buildPartialSsml,
   buildSsml: () => buildSsml,
   canMergeAudioFormat: () => canMergeAudioFormat,
+  computeChunkFingerprint: () => computeChunkFingerprint,
   createAzureUrlValidatorRunner: () => createAzureUrlValidatorRunner,
   extractSsmlText: () => extractSsmlText,
   extractSsmlTranslatableText: () => extractSsmlTranslatableText,
@@ -70,6 +73,7 @@ __export(src_exports, {
   parseSsml: () => parseSsml,
   resolveMergeAudioFormat: () => resolveMergeAudioFormat,
   resolveMimeType: () => resolveMimeType,
+  serializeChunkError: () => serializeChunkError,
   splitSsmlDocument: () => splitSsmlDocument,
   synthesizeSpeech: () => synthesizeSpeech,
   synthesizeSsml: () => synthesizeSsml,
@@ -2802,6 +2806,15 @@ var SynthesisTimeoutError = class extends Error {
     this.name = "SynthesisTimeoutError";
   }
 };
+var IncompleteChunkSetError = class extends Error {
+  constructor(totalChunks, missingChunkIndices) {
+    super(`Cannot merge an incomplete chunk set; missing chunk indices: ${missingChunkIndices.join(", ")}.`);
+    this.kind = "incomplete-chunk-set";
+    this.name = "IncompleteChunkSetError";
+    this.totalChunks = totalChunks;
+    this.missingChunkIndices = [...missingChunkIndices];
+  }
+};
 var MergeError = class extends Error {
   constructor(message, cause) {
     super(message);
@@ -2826,8 +2839,32 @@ var UnsupportedMergeFormatError = class extends Error {
     this.format = format;
   }
 };
+function serializeChunkError(error, phase, isOriginalFailure) {
+  const message = error instanceof Error ? error.message : String(error);
+  const status = error instanceof AzureTtsError ? error.status : void 0;
+  const kind = error && typeof error === "object" && "kind" in error ? String(error.kind) : "";
+  const code = kind === "validation-error" ? "VALIDATION_ERROR" : kind === "timeout" || /tim(?:e|ed) ?out|deadline/i.test(message) ? "TIMEOUT" : kind === "cancelled" || /cancel|abort/i.test(message) ? "CANCELLED" : kind === "audio-format-mismatch" || kind === "unsupported-format-error" ? "FORMAT_MISMATCH" : kind === "merge-error" || phase === "merge" ? "MERGE_ERROR" : "AZURE_API_ERROR";
+  const details = {};
+  if (error instanceof AzureTtsError) {
+    details.statusText = error.statusText;
+    if (error.requestId) details.requestId = error.requestId;
+  }
+  if (error instanceof IncompleteChunkSetError) {
+    details.totalChunks = error.totalChunks;
+    details.missingChunkIndices = [...error.missingChunkIndices];
+  }
+  return {
+    code,
+    phase,
+    message,
+    isOriginalFailure,
+    isRetryable: code === "AZURE_API_ERROR" && (status === 429 || status !== void 0 && status >= 500 || /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message)),
+    ...status !== void 0 && status > 0 ? { httpStatus: status } : {},
+    ...Object.keys(details).length > 0 ? { details } : {}
+  };
+}
 function toSynthesisError(error) {
-  if (error instanceof AzureTtsError || error instanceof MergeError || error instanceof AudioFormatMismatchError || 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 || error instanceof IncompleteChunkSetError)
     return error;
   const message = error instanceof Error ? error.message : String(error);
   if (/cancel|abort/i.test(message)) return new SynthesisCancelledError(message);
@@ -2839,6 +2876,55 @@ function createSpeechSdkError(error) {
   return new AzureTtsSdkError(message);
 }
 
+// packages/azure-tts-client/src/deadline.ts
+var _controller, _parent, _onParentAbort, _timer, _timedOut;
+var DeadlineController = class {
+  constructor(totalJobMs, parent) {
+    __privateAdd(this, _controller, new AbortController());
+    __privateAdd(this, _parent);
+    __privateAdd(this, _onParentAbort);
+    __privateAdd(this, _timer);
+    __privateAdd(this, _timedOut, false);
+    __privateSet(this, _parent, parent);
+    __privateSet(this, _onParentAbort, () => __privateGet(this, _controller).abort());
+    this.deadlineAtMs = totalJobMs !== void 0 && totalJobMs > 0 ? Date.now() + totalJobMs : void 0;
+    this.signal = this.deadlineAtMs === void 0 && parent ? parent : __privateGet(this, _controller).signal;
+    if (parent?.aborted) __privateGet(this, _controller).abort();
+    parent?.addEventListener("abort", __privateGet(this, _onParentAbort), { once: true });
+    if (this.deadlineAtMs !== void 0) {
+      __privateSet(this, _timer, setTimeout(
+        () => {
+          __privateSet(this, _timedOut, true);
+          __privateGet(this, _controller).abort();
+        },
+        Math.max(0, this.deadlineAtMs - Date.now())
+      ));
+    }
+  }
+  get timedOut() {
+    return __privateGet(this, _timedOut) || this.deadlineAtMs !== void 0 && this.remainingMs <= 0;
+  }
+  get remainingMs() {
+    return this.deadlineAtMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, this.deadlineAtMs - Date.now());
+  }
+  throwIfExpired() {
+    if (this.timedOut) throw new SynthesisTimeoutError("Speech synthesis exceeded the total job deadline.");
+    if (this.signal.aborted) throw new Error("Speech synthesis was cancelled.");
+  }
+  abort() {
+    __privateGet(this, _controller).abort();
+  }
+  dispose() {
+    if (__privateGet(this, _timer)) clearTimeout(__privateGet(this, _timer));
+    __privateGet(this, _parent)?.removeEventListener("abort", __privateGet(this, _onParentAbort));
+  }
+};
+_controller = new WeakMap();
+_parent = new WeakMap();
+_onParentAbort = new WeakMap();
+_timer = new WeakMap();
+_timedOut = new WeakMap();
+
 // packages/azure-tts-client/src/synthesis.ts
 var SpeechSDK2 = __toESM(require("microsoft-cognitiveservices-speech-sdk"));
 
@@ -4583,6 +4669,9 @@ var OUTPUT_FORMATS = {
 function resolveMimeType(outputFormat) {
   if (/(?:wav|wave|riff)/i.test(outputFormat)) return "audio/wav";
   if (/(?:mp3|mpeg)/i.test(outputFormat)) return "audio/mpeg";
+  if (/mulaw|mu-law/i.test(outputFormat)) return "audio/basic";
+  if (/alaw|a-law/i.test(outputFormat)) return "audio/alaw";
+  if (/siren/i.test(outputFormat)) return "audio/siren";
   if (/ogg/i.test(outputFormat)) return "audio/ogg";
   if (/webm/i.test(outputFormat)) return "audio/webm";
   if (/raw/i.test(outputFormat)) return "audio/L16";
@@ -4611,6 +4700,32 @@ function createSpeechConfig(config) {
 }
 
 // packages/azure-tts-client/src/synthesis.ts
+function computeChunkFingerprint(ssml, outputFormat = DEFAULT_OUTPUT_FORMAT, options = {}) {
+  const readAttribute3 = (name) => {
+    const pattern = new RegExp(`(?:${name})\\s*=\\s*[\\"']([^\\"']*)`, "gi");
+    return [...ssml.matchAll(pattern)].map((match) => match[1] ?? "").join("|");
+  };
+  const headers = Object.fromEntries(
+    Object.entries(options.customHeaders ?? {}).sort(([first], [second]) => first.localeCompare(second))
+  );
+  const payload = JSON.stringify({
+    ssml,
+    outputFormat,
+    region: options.region ?? "",
+    endpoint: options.endpoint ?? "",
+    voice: options.voice ?? readAttribute3("(?:name|voice)"),
+    lang: options.lang ?? readAttribute3("(?:xml:lang|lang)"),
+    customHeaders: headers,
+    fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? options.schemaVersion ?? "2"
+  });
+  let hash = 0xcbf29ce484222325n;
+  const mask = 0xffffffffffffffffn;
+  for (let index = 0; index < payload.length; index += 1) {
+    hash ^= BigInt(payload.charCodeAt(index));
+    hash = hash * 0x100000001b3n & mask;
+  }
+  return `fnv1a64-${hash.toString(16).padStart(16, "0")}`;
+}
 function ascii(bytes, offset, value) {
   return [...value].every((character, index) => bytes[offset + index] === character.charCodeAt(0));
 }
@@ -4650,9 +4765,11 @@ 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 formatSampleRate(format) {
+  const match = /(?:^|-)(\d+)(khz|hz)(?:-|$)/i.exec(format);
+  if (!match?.[1] || !match[2]) return 0;
+  const value = Number(match[1]);
+  return match[2].toLowerCase() === "khz" ? value * 1e3 : value;
 }
 function formatChannels(format, fallback) {
   if (/stereo|2ch|dual/i.test(format)) return 2;
@@ -4660,11 +4777,11 @@ function formatChannels(format, fallback) {
   return fallback;
 }
 function formatAudioSpecification(format) {
-  const sampleRate = formatNumber(format, /(\d+)(?:khz|kHz|hz|Hz)/, 0);
+  const sampleRate = formatSampleRate(format);
   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 codec = /mp3|mpeg/i.test(format) ? "mp3" : /opus/i.test(format) ? "opus" : /silk/i.test(format) ? "silk" : /mulaw|mu-law/i.test(format) ? "mulaw" : /alaw|a-law/i.test(format) ? "alaw" : /siren/i.test(format) ? "siren" : /pcm/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 {
@@ -4677,7 +4794,7 @@ function formatAudioSpecification(format) {
     ...bitDepthMatch?.[1] ? { bitDepth: Number(bitDepthMatch[1]) } : {},
     ...container ? { container } : {},
     isVbr: /vbr/i.test(format),
-    isCompressed: codec === "mp3" || codec === "opus" || codec === "silk"
+    isCompressed: codec !== "pcm" && codec !== "unknown"
   };
 }
 function parseMp3Specification(buffer, format) {
@@ -4719,6 +4836,129 @@ function parseMp3Specification(buffer, format) {
   }
   return void 0;
 }
+function readEbmlVint(bytes, offset, preserveMarker) {
+  const first = bytes[offset];
+  if (first === void 0) throw new Error("Invalid EBML variable-length integer.");
+  let mask = 128;
+  let length = 1;
+  while (length <= 8 && (first & mask) === 0) {
+    mask >>= 1;
+    length += 1;
+  }
+  if (length > 8 || offset + length > bytes.byteLength) throw new Error("Truncated EBML variable-length integer.");
+  let value = preserveMarker ? first : first & mask - 1;
+  for (let index = 1; index < length; index += 1) value = value * 256 + (bytes[offset + index] ?? 0);
+  if (!preserveMarker && value === 2 ** (7 * length) - 1)
+    throw new Error("EBML unknown-size elements are not supported.");
+  return { value, length };
+}
+function readEbmlElement(bytes, offset) {
+  const id = readEbmlVint(bytes, offset, true);
+  const size = readEbmlVint(bytes, offset + id.length, false);
+  const dataStart = offset + id.length + size.length;
+  const dataEnd = dataStart + size.value;
+  if (dataEnd > bytes.byteLength) throw new Error("EBML element exceeds the audio buffer.");
+  return { id: id.value, dataStart, dataEnd };
+}
+function ebmlText(bytes, element) {
+  return new TextDecoder().decode(bytes.slice(element.dataStart, element.dataEnd));
+}
+function findEbmlElement(bytes, start, end, id) {
+  let offset = start;
+  while (offset < end) {
+    const element = readEbmlElement(bytes, offset);
+    if (element.id === id) return element;
+    offset = element.dataEnd;
+  }
+  if (offset !== end) throw new Error("Invalid EBML element boundary.");
+  return void 0;
+}
+function parseOggSpecification(buffer, format) {
+  const bytes = new Uint8Array(buffer);
+  let offset = 0;
+  let firstPayload;
+  let pages = 0;
+  while (offset < bytes.byteLength) {
+    if (offset + 27 > bytes.byteLength || !ascii(bytes, offset, "OggS")) throw new Error("Invalid Ogg page header.");
+    if (bytes[offset + 4] !== 0) throw new Error("Unsupported Ogg bitstream version.");
+    const segmentCount = bytes[offset + 26] ?? 0;
+    const lacingStart = offset + 27;
+    const payloadStart = lacingStart + segmentCount;
+    if (payloadStart > bytes.byteLength) throw new Error("Truncated Ogg segment table.");
+    const payloadLength = bytes.slice(lacingStart, payloadStart).reduce((total, value) => total + value, 0);
+    const pageEnd = payloadStart + payloadLength;
+    if (pageEnd > bytes.byteLength) throw new Error("Ogg page payload exceeds the audio buffer.");
+    if (pages === 0) firstPayload = bytes.slice(payloadStart, pageEnd);
+    offset = pageEnd;
+    pages += 1;
+  }
+  if (pages === 0 || !firstPayload || !ascii(firstPayload, 0, "OpusHead") || firstPayload.byteLength < 19)
+    throw new Error("Ogg audio must contain a valid OpusHead packet.");
+  const version = firstPayload[8];
+  const channels = firstPayload[9] ?? 0;
+  const sampleRate = new DataView(firstPayload.buffer, firstPayload.byteOffset, firstPayload.byteLength).getUint32(
+    12,
+    true
+  );
+  if (version !== 1 || channels <= 0 || sampleRate <= 0) throw new Error("Invalid Ogg OpusHead stream parameters.");
+  return {
+    format,
+    mimeType: "audio/ogg",
+    codec: "opus",
+    sampleRate,
+    channels,
+    container: "ogg",
+    isVbr: true,
+    isCompressed: true
+  };
+}
+function parseWebmSpecification(buffer, format) {
+  const bytes = new Uint8Array(buffer);
+  const ebml = readEbmlElement(bytes, 0);
+  if (ebml.id !== 440786851) throw new Error("WebM audio must begin with an EBML header.");
+  const docType = findEbmlElement(bytes, ebml.dataStart, ebml.dataEnd, 17026);
+  if (!docType || ebmlText(bytes, docType).toLowerCase() !== "webm") throw new Error("EBML DocType must be webm.");
+  const segment = readEbmlElement(bytes, ebml.dataEnd);
+  if (segment.id !== 408125543) throw new Error("WebM audio must contain a Segment element.");
+  const tracks = findEbmlElement(bytes, segment.dataStart, segment.dataEnd, 374648427);
+  if (!tracks) throw new Error("WebM audio must contain a Tracks element.");
+  let offset = tracks.dataStart;
+  let opusTrack;
+  while (offset < tracks.dataEnd) {
+    const track = readEbmlElement(bytes, offset);
+    if (track.id === 174) {
+      const codec = findEbmlElement(bytes, track.dataStart, track.dataEnd, 134);
+      const trackType = findEbmlElement(bytes, track.dataStart, track.dataEnd, 131);
+      if (codec && ebmlText(bytes, codec) === "A_OPUS" && trackType && bytes[trackType.dataStart] === 2) {
+        opusTrack = track;
+        break;
+      }
+    }
+    offset = track.dataEnd;
+  }
+  if (!opusTrack) throw new Error("WebM tracks do not define an Opus audio track.");
+  const audio = findEbmlElement(bytes, opusTrack.dataStart, opusTrack.dataEnd, 225);
+  const sampling = audio ? findEbmlElement(bytes, audio.dataStart, audio.dataEnd, 181) : void 0;
+  const channels = audio ? findEbmlElement(bytes, audio.dataStart, audio.dataEnd, 159) : void 0;
+  const sampleRate = sampling ? new DataView(
+    bytes.buffer,
+    bytes.byteOffset + sampling.dataStart,
+    sampling.dataEnd - sampling.dataStart
+  ).getFloat64(0, false) : 0;
+  const channelCount = channels ? bytes[channels.dataEnd - 1] ?? 0 : 0;
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0 || channelCount <= 0)
+    throw new Error("WebM Opus audio track has invalid sampling or channel parameters.");
+  return {
+    format,
+    mimeType: "audio/webm",
+    codec: "opus",
+    sampleRate: Math.round(sampleRate),
+    channels: channelCount,
+    container: "webm",
+    isVbr: true,
+    isCompressed: true
+  };
+}
 function inspectAudioSpecification(buffer, format) {
   if (isWavFormat(format) || ascii(new Uint8Array(buffer), 0, "RIFF")) {
     const parsed = parseWav(buffer);
@@ -4728,27 +4968,78 @@ function inspectAudioSpecification(buffer, format) {
     const channels = view.getUint16(2, true);
     const bitsPerSample = parsed.format.byteLength >= 16 ? view.getUint16(14, true) : 0;
     const formatCode = view.getUint16(0, true);
+    const namedCodec = formatAudioSpecification(format).codec;
+    const codec = formatCode === 1 ? "pcm" : formatCode === 6 ? "alaw" : formatCode === 7 ? "mulaw" : namedCodec === "siren" ? "siren" : "unknown";
     return {
       format,
       mimeType: "audio/wav",
-      codec: formatCode === 1 ? "pcm" : "unknown",
+      codec,
       sampleRate,
       channels,
       ...sampleRate && channels && bitsPerSample ? { bitrate: sampleRate * channels * bitsPerSample } : {},
       bitDepth: bitsPerSample,
       container: "riff-wave",
       isVbr: false,
-      isCompressed: formatCode !== 1
+      isCompressed: codec !== "pcm" && codec !== "unknown"
     };
   }
-  if (isMp3Format(format)) return parseMp3Specification(buffer, format) ?? formatAudioSpecification(format);
-  return formatAudioSpecification(format);
+  if (isMp3Format(format)) {
+    const specification2 = parseMp3Specification(buffer, format);
+    return specification2 ?? formatAudioSpecification(format);
+  }
+  if (isOggFormat(format) || ascii(new Uint8Array(buffer), 0, "OggS")) {
+    const specification2 = parseOggSpecification(buffer, format);
+    validateContainerFormat(specification2, format);
+    return specification2;
+  }
+  if (isWebmFormat(format) || new Uint8Array(buffer)[0] === 26) {
+    const specification2 = parseWebmSpecification(buffer, format);
+    validateContainerFormat(specification2, format);
+    return specification2;
+  }
+  const specification = formatAudioSpecification(format);
+  if (specification.container === "raw") validateRawAudioBuffer(buffer, specification);
+  return specification;
+}
+function validateRawAudioBuffer(buffer, specification) {
+  if (specification.sampleRate <= 0 || specification.channels <= 0 || specification.bitDepth === void 0) {
+    throw new Error(`RAW audio format "${specification.format}" does not define a complete audio specification.`);
+  }
+  if (specification.codec === "siren") return;
+  if (specification.codec === "silk") {
+    if (buffer.byteLength <= 9 || !ascii(new Uint8Array(buffer), 0, "#!SILK_V3"))
+      throw new Error("RAW SILK audio must contain a valid #!SILK_V3 payload header.");
+    return;
+  }
+  if (specification.codec === "opus" && buffer.byteLength === 0) throw new Error("RAW Opus audio cannot be empty.");
+  if (specification.codec === "opus") {
+    const packetCode = new Uint8Array(buffer)[0] ?? 0;
+    const frameCountCode = packetCode & 3;
+    if (packetCode >> 3 > 31 || buffer.byteLength < (frameCountCode === 3 ? 2 : 2) || frameCountCode === 3 && ((new Uint8Array(buffer)[1] ?? 0) & 63) === 0)
+      throw new Error("RAW Opus audio has an invalid packet framing header.");
+    return;
+  }
+  const bytesPerFrame = specification.channels * Math.ceil(specification.bitDepth / 8);
+  if (bytesPerFrame <= 0 || buffer.byteLength % bytesPerFrame !== 0) {
+    throw new Error(
+      `RAW audio buffer size ${buffer.byteLength} is not aligned to ${bytesPerFrame}-byte audio frames for "${specification.format}".`
+    );
+  }
+}
+function validateContainerFormat(specification, format) {
+  const expected = formatAudioSpecification(format);
+  if (expected.sampleRate > 0 && specification.sampleRate !== expected.sampleRate || expected.channels > 0 && specification.channels !== expected.channels || expected.codec !== "unknown" && specification.codec !== expected.codec) {
+    throw new AudioFormatMismatchError(`Audio container does not match the requested format "${format}".`, [
+      expected,
+      specification
+    ]);
+  }
 }
 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
+    (spec) => spec.sampleRate !== first.sampleRate || spec.channels !== first.channels || spec.codec !== first.codec || 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(
@@ -4825,12 +5116,67 @@ function stripMp3Tags(buffer) {
 function isMp3Format(format) {
   return /(?:mp3|mpeg)/i.test(format);
 }
+function isOggFormat(format) {
+  return /ogg/i.test(format);
+}
+function isWebmFormat(format) {
+  return /webm/i.test(format);
+}
 function isWavFormat(format) {
   return /(?:wav|wave|riff)/i.test(format);
 }
 function isRawFormat(format) {
   return /^raw(?:-|$)/i.test(format);
 }
+function validateMergedAudioBuffer(merged, format, buffers, inputSpecs, outputMimeType, allowExternalContainer) {
+  if (!(merged instanceof ArrayBuffer) || merged.byteLength === 0) {
+    throw new MergeError("The custom audio merger returned an empty or invalid audio buffer.");
+  }
+  let specification;
+  try {
+    specification = inspectAudioSpecification(merged, format);
+  } catch (error) {
+    if (!allowExternalContainer) throw error;
+    specification = inputSpecs[0] ?? formatAudioSpecification(format);
+  }
+  if (!outputMimeType.trim()) throw new MergeError("The custom audio merger output MIME type cannot be empty.");
+  const firstInput = inputSpecs[0];
+  if (firstInput && (specification.sampleRate !== firstInput.sampleRate || specification.channels !== firstInput.channels || specification.codec !== firstInput.codec || firstInput.bitDepth !== void 0 && specification.bitDepth !== firstInput.bitDepth)) {
+    throw new AudioFormatMismatchError("The custom audio merger returned an incompatible audio stream.", [
+      ...inputSpecs,
+      specification
+    ]);
+  }
+  if (isRawFormat(format)) {
+    const expectedSize = buffers.reduce((total, input) => total + input.byteLength, 0);
+    if (merged.byteLength !== expectedSize) {
+      throw new MergeError(
+        `The custom audio merger returned ${merged.byteLength} bytes; ${expectedSize} were expected.`
+      );
+    }
+    validateRawAudioBuffer(merged, specification);
+  }
+  return specification;
+}
+async function withinDeadline(value, deadline) {
+  if (!deadline) return value;
+  deadline.throwIfExpired();
+  if (!Number.isFinite(deadline.remainingMs)) return value;
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve(value),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new SynthesisTimeoutError("Speech synthesis exceeded the total job deadline.")),
+          deadline.remainingMs
+        );
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 function resolveMergeAudioFormat(format) {
   if (isWavFormat(format)) return "wav";
   if (isMp3Format(format)) return "mp3";
@@ -4843,6 +5189,7 @@ function canMergeAudioFormat(format) {
 function mergeAudioBuffers(buffers, options) {
   const format = typeof options === "string" ? options : options?.format;
   if (!format) throw new UnsupportedMergeFormatError("");
+  if (!canMergeAudioFormat(format)) throw new UnsupportedMergeFormatError(format);
   try {
     validateAudioSpecifications(buffers.map((buffer) => inspectAudioSpecification(buffer, format)));
     if (isWavFormat(format)) return mergeWavBuffers(buffers);
@@ -4883,7 +5230,7 @@ function closeSpeechResources(speechConfig, synthesizer) {
   }
 }
 var ticksToMilliseconds = (ticks) => Math.max(0, ticks) / 1e4;
-async function synthesizeSsml(ssml, config) {
+async function synthesizeSsmlOnce(ssml, config) {
   if (config.signal?.aborted) {
     throw new SynthesisCancelledError();
   }
@@ -5013,6 +5360,13 @@ async function synthesizeSsml(ssml, config) {
         rejectWithError(err);
         return;
       }
+      let audioSpec;
+      try {
+        audioSpec = inspectAudioSpecification(result.audioData, config.outputFormat ?? DEFAULT_OUTPUT_FORMAT);
+      } catch (error) {
+        rejectWithError(error);
+        return;
+      }
       settled = true;
       cleanup();
       closeResources();
@@ -5048,8 +5402,8 @@ async function synthesizeSsml(ssml, config) {
       resolve({
         audioData: result.audioData,
         durationMs,
-        audioSpec: inspectAudioSpecification(result.audioData, config.outputFormat ?? DEFAULT_OUTPUT_FORMAT),
-        mimeType: resolveMimeType(config.outputFormat ?? DEFAULT_OUTPUT_FORMAT),
+        audioSpec,
+        mimeType: config.outputMimeType ?? resolveMimeType(config.outputFormat ?? DEFAULT_OUTPUT_FORMAT),
         ...config.sourceTextRange ? { textRange: { ...config.sourceTextRange } } : {},
         ...requestId ? { requestId } : {},
         ...sourceBoundaries.length > 0 ? { boundaries: sourceBoundaries, wordBoundary: sourceBoundaries, wordBoundaries: sourceBoundaries } : {},
@@ -5062,7 +5416,7 @@ async function synthesizeSsml(ssml, config) {
         abortHandler = () => rejectWithError(new SynthesisCancelledError());
         config.signal.addEventListener("abort", abortHandler, { once: true });
       }
-      const timeoutMs = config.timeouts?.perChunkMs ?? config.timeoutMs;
+      const timeoutMs = config.timeouts?.perChunkMs ?? config.timeouts?.totalJobMs ?? config.timeoutMs;
       if (timeoutMs !== void 0 && timeoutMs > 0) {
         timeout = setTimeout(
           () => rejectWithError(new SynthesisTimeoutError(`Speech synthesis timed out after ${timeoutMs} ms.`)),
@@ -5115,7 +5469,7 @@ async function waitForRetry(delayMs, signal) {
     }
   });
 }
-async function synthesizeWithRetry(ssml, config, retryOptions, onRetry) {
+async function synthesizeWithRetry(ssml, config, retryOptions, onRetry, deadlineAtMs) {
   const options = retryOptions ? {
     maxRetries: Math.max(0, Math.floor(retryOptions.maxRetries)),
     initialDelayMs: Math.max(0, retryOptions.initialDelayMs),
@@ -5126,17 +5480,42 @@ async function synthesizeWithRetry(ssml, config, retryOptions, onRetry) {
   while (true) {
     if (config.signal?.aborted) throw new SynthesisCancelledError();
     try {
-      return await synthesizeSsml(ssml, config);
+      return await synthesizeSsmlOnce(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);
+      const remainingMs = deadlineAtMs === void 0 ? void 0 : Math.max(0, deadlineAtMs - Date.now());
+      if (getRetryAfterDelayMs(error) !== void 0 && (delayMs > options.maxDelayMs || remainingMs !== void 0 && delayMs > remainingMs)) {
+        throw new SynthesisTimeoutError(
+          remainingMs === void 0 ? `Retry-After exceeded maxDelayMs (${options.maxDelayMs} ms).` : `Retry-After exceeded the remaining total job timeout (${remainingMs} ms).`
+        );
+      }
       onRetry(attempt, delayMs);
-      await waitForRetry(delayMs, config.signal);
+      await waitForRetry(Math.min(delayMs, remainingMs ?? delayMs), config.signal);
     }
   }
 }
+async function synthesizeSsml(ssml, config) {
+  const deadline = new DeadlineController(config.timeouts?.totalJobMs, config.signal);
+  try {
+    deadline.throwIfExpired();
+    const synthesisConfig = {
+      ...config,
+      signal: deadline.signal,
+      timeouts: config.timeouts ? { ...config.timeouts, totalJobMs: void 0 } : void 0
+    };
+    const result = config.retryOptions ? await synthesizeWithRetry(ssml, synthesisConfig, config.retryOptions, () => void 0, deadline.deadlineAtMs) : await synthesizeSsmlOnce(ssml, synthesisConfig);
+    deadline.throwIfExpired();
+    return result;
+  } catch (error) {
+    if (deadline.timedOut) throw new SynthesisTimeoutError("Speech synthesis exceeded the total job deadline.");
+    throw error;
+  } finally {
+    deadline.dispose();
+  }
+}
 function createAbortScope(parent, timeoutMs) {
   const controller = new AbortController();
   let didTimeout = false;
@@ -5157,10 +5536,10 @@ function createAbortScope(parent, timeoutMs) {
     abort: () => controller.abort()
   };
 }
-async function synthesizeChunkWithTimeout(ssml, config, retryOptions, timeoutMs, onRetry) {
+async function synthesizeChunkWithTimeout(ssml, config, retryOptions, timeoutMs, onRetry, deadlineAtMs) {
   const scope = createAbortScope(config.signal, timeoutMs);
   try {
-    return await synthesizeWithRetry(ssml, { ...config, signal: scope.signal }, retryOptions, onRetry);
+    return await synthesizeWithRetry(ssml, { ...config, signal: scope.signal }, retryOptions, onRetry, deadlineAtMs);
   } catch (error) {
     if (scope.timedOut()) throw new SynthesisTimeoutError(`Speech synthesis timed out after ${timeoutMs} ms.`);
     throw error;
@@ -5169,18 +5548,42 @@ async function synthesizeChunkWithTimeout(ssml, config, retryOptions, timeoutMs,
   }
 }
 async function synthesizeSsmlChunks(chunks, config) {
-  const results = new Array(chunks.length);
   const totalChunks = chunks.length;
+  const inputs = chunks.map((chunk) => typeof chunk === "string" ? { ssml: chunk } : chunk);
+  const fingerprints = inputs.map(
+    (chunk) => computeChunkFingerprint(chunk.ssml, config.outputFormat ?? DEFAULT_OUTPUT_FORMAT, {
+      region: config.region,
+      endpoint: config.endpoint,
+      customHeaders: config.customHeaders,
+      fingerprintSchemaVersion: config.fingerprintSchemaVersion
+    })
+  );
+  const results = new Array(totalChunks);
   const cachedChunks = new Map((config.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+  const invalidCachedIndices = /* @__PURE__ */ new Set();
+  const chunkStates = inputs.map((_chunk, chunkIndex) => ({
+    chunkIndex,
+    status: "pending",
+    canResume: true
+  }));
   for (const [index, cached] of cachedChunks) {
-    if (index >= 0 && index < totalChunks) results[index] = cached;
+    if (index < 0 || index >= totalChunks) continue;
+    const isValid = config.resumeValidation === "disabled" || cached.fingerprint === fingerprints[index];
+    if (isValid) {
+      results[index] = { ...cached };
+      chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result: results[index] };
+    } else {
+      invalidCachedIndices.add(index);
+    }
   }
   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 shouldSynthesize = (index) => (!cachedChunks.has(index) || invalidCachedIndices.has(index)) && (requestedIndices === void 0 || requestedIndices.has(index) || invalidCachedIndices.has(index));
+  const jobStartedAt = Date.now();
+  const jobDeadlineAt = config.timeouts?.totalJobMs !== void 0 && config.timeouts.totalJobMs > 0 ? jobStartedAt + config.timeouts.totalJobMs : void 0;
+  const deadline = new DeadlineController(config.timeouts?.totalJobMs, config.signal);
   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;
+  for (const [index, input] of inputs.entries()) {
     report({
       currentChunk: index,
       totalChunks,
@@ -5202,8 +5605,7 @@ async function synthesizeSsmlChunks(chunks, config) {
       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;
+      const input = inputs[index];
       report({
         currentChunk: completed,
         totalChunks,
@@ -5219,7 +5621,7 @@ async function synthesizeSsmlChunks(chunks, config) {
           input.ssml,
           {
             ...config,
-            signal: scope.signal,
+            signal: deadline.signal,
             ...input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {},
             ...input.sourceNodePath ?? config.sourceNodePath ? { sourceNodePath: [...input.sourceNodePath ?? config.sourceNodePath ?? []] } : {},
             ...input.sourceTextSegments ? { sourceTextSegments: input.sourceTextSegments } : {},
@@ -5240,9 +5642,11 @@ async function synthesizeSsmlChunks(chunks, config) {
             retryAttempt,
             nextRetryDelayMs,
             isRetrying: true
-          })
+          }),
+          jobDeadlineAt
         );
         results[index] = result;
+        chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result };
         completed += 1;
         report({
           currentChunk: completed,
@@ -5254,7 +5658,16 @@ async function synthesizeSsmlChunks(chunks, config) {
           durationMs: Date.now() - startedAt
         });
       } catch (error) {
-        failedIndices.add(index);
+        const wasCancelled = firstError !== void 0 || scope.signal.aborted && !scope.timedOut();
+        firstError ?? (firstError = scope.timedOut() ? new SynthesisTimeoutError(`Speech synthesis timed out after ${config.timeouts?.totalJobMs} ms.`) : error);
+        if (!wasCancelled) failedIndices.add(index);
+        chunkStates[index] = {
+          chunkIndex: index,
+          status: wasCancelled ? "cancelled" : "failed",
+          isOriginalFailure: !wasCancelled,
+          canResume: true,
+          error: serializeChunkError(error, "synthesis", !wasCancelled)
+        };
         report({
           currentChunk: completed,
           totalChunks,
@@ -5265,7 +5678,6 @@ async function synthesizeSsmlChunks(chunks, config) {
           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;
       }
@@ -5274,26 +5686,47 @@ async function synthesizeSsmlChunks(chunks, config) {
   try {
     await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
     if (firstError) throw firstError;
+    const missingChunkIndices = Array.from(
+      { length: totalChunks },
+      (_value, index) => results[index] === void 0 ? index : void 0
+    ).filter((index) => index !== void 0);
+    if (missingChunkIndices.length > 0) throw new IncompleteChunkSetError(totalChunks, missingChunkIndices);
     const orderedResults = results.filter((result) => result !== void 0);
     return await mergeSynthesisResults(orderedResults, {
       format: config.outputFormat ?? DEFAULT_OUTPUT_FORMAT,
-      signal: scope.signal,
+      signal: deadline.signal,
       customMerger: config.customMerger,
       outputMimeType: config.outputMimeType,
-      postMergeValidator: config.postMergeValidator
+      postMergeValidator: config.postMergeValidator,
+      deadline
     });
   } catch (error) {
+    if (firstError && config.cancelOnFailure !== false) {
+      for (const [chunkIndex, state] of chunkStates.entries()) {
+        if (state.status === "pending" && shouldSynthesize(chunkIndex)) {
+          chunkStates[chunkIndex] = { chunkIndex, status: "cancelled", isOriginalFailure: false, canResume: true };
+        }
+      }
+    }
+    const synthesizedChunks = results.flatMap(
+      (result, chunkIndex) => result ? [{ ...result, chunkIndex, fingerprint: fingerprints[chunkIndex] ?? "" }] : []
+    );
     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]),
+      synthesizedChunks,
+      completedChunks: synthesizedChunks,
+      pendingChunkIndices: chunkStates.flatMap(
+        (state) => state.status === "pending" || state.status === "cancelled" || state.status === "failed" ? [state.chunkIndex] : []
+      ),
       failedChunkIndices: [...failedIndices],
+      cancelledChunkIndices: chunkStates.filter((state) => state.status === "cancelled").map((state) => state.chunkIndex),
+      chunkStates,
       totalChunks
     };
     if (error && typeof error === "object") error.partialResult = partial;
     throw error;
   } finally {
     scope.dispose();
+    deadline.dispose();
   }
 }
 function createMergedResult(results, audioData, format, audioSpec, outputMimeType) {
@@ -5371,30 +5804,44 @@ 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));
+  const inputSpecs = results.map((result) => {
+    if (result.audioSpec) return result.audioSpec;
+    try {
+      return inspectAudioSpecification(result.audioData, format);
+    } catch (error) {
+      if (resolvedOptions.customMerger) return formatAudioSpecification(format);
+      throw error;
+    }
+  });
   validateAudioSpecifications(inputSpecs);
-  const signal = resolvedOptions.signal ?? new AbortController().signal;
+  const deadline = resolvedOptions.deadline;
+  deadline?.throwIfExpired();
+  const signal = resolvedOptions.signal ?? deadline?.signal ?? new AbortController().signal;
   if (signal.aborted) throw new SynthesisCancelledError();
   if (resolvedOptions.customMerger) {
-    return Promise.resolve().then(
-      () => resolvedOptions.customMerger?.(buffers, {
-        format,
-        outputMimeType: resolvedOptions.outputMimeType ?? resolveMimeType(format),
-        inputSpecs,
-        signal
-      })
+    return withinDeadline(
+      Promise.resolve().then(
+        () => resolvedOptions.customMerger?.(buffers, {
+          format,
+          outputMimeType: resolvedOptions.outputMimeType ?? resolveMimeType(format),
+          inputSpecs,
+          signal
+        })
+      ),
+      deadline
     ).then((merged) => {
+      deadline?.throwIfExpired();
       if (!merged) throw new MergeError("The custom audio merger returned no audio buffer.");
-      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,
+      const mergedSpec = validateMergedAudioBuffer(
         merged,
         format,
-        inspectAudioSpecification(merged, format),
-        resolvedOptions.outputMimeType
+        buffers,
+        inputSpecs,
+        resolvedOptions.outputMimeType ?? resolveMimeType(format),
+        true
       );
+      const result = createMergedResult(results, merged, format, mergedSpec, resolvedOptions.outputMimeType);
       return Promise.resolve(
         resolvedOptions.postMergeValidator?.(result, {
           format,
@@ -5403,6 +5850,7 @@ function mergeSynthesisResults(results, options) {
           signal
         })
       ).then((valid) => {
+        deadline?.throwIfExpired();
         if (valid === false) throw new MergeError("The post-merge validator rejected the merged audio.");
         return result;
       });
@@ -5413,6 +5861,7 @@ function mergeSynthesisResults(results, options) {
     });
   }
   try {
+    deadline?.throwIfExpired();
     const result = createMergedResult(
       results,
       mergeAudioBuffers(buffers, { format }),
@@ -5428,12 +5877,14 @@ function mergeSynthesisResults(results, options) {
         signal
       });
       if (validation instanceof Promise)
-        return validation.then((valid) => {
+        return withinDeadline(validation, deadline).then((valid) => {
+          deadline?.throwIfExpired();
           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.");
     }
+    deadline?.throwIfExpired();
     return result;
   } catch (error) {
     if (error instanceof UnsupportedMergeFormatError || isAudioFormatMismatch(error) || error instanceof MergeError)
@@ -5523,7 +5974,7 @@ function resolveConcurrency2(value, total) {
   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) {
+async function retryableSynthesis(synthesize, options, signal, onRetry, deadlineAtMs) {
   const retry = options ? {
     maxRetries: Math.max(0, Math.floor(options.maxRetries)),
     initialDelayMs: options.initialDelayMs,
@@ -5540,6 +5991,11 @@ async function retryableSynthesis(synthesize, options, signal, onRetry) {
         throw error;
       attempt += 1;
       const delayMs = retryDelayForError(retry, attempt, error);
+      const retryAfterMs = getRetryAfterDelayMs(error);
+      const remainingMs = deadlineAtMs === void 0 ? void 0 : Math.max(0, deadlineAtMs - Date.now());
+      if (retryAfterMs !== void 0 && (retryAfterMs > retry.maxDelayMs || remainingMs !== void 0 && retryAfterMs > remainingMs)) {
+        throw new Error("Speech synthesis timed out because Retry-After exceeded the available retry budget.");
+      }
       onRetry(attempt, delayMs);
       if (delayMs > 0)
         await new Promise((resolve, reject) => {
@@ -5573,14 +6029,19 @@ function sharedValidationOptions(options, signal) {
   };
 }
 async function synthesizeSsmlSafe(client, ssml, options = {}) {
-  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
+  const deadline = new DeadlineController(options.timeouts?.totalJobMs, options.signal);
+  const validationOptions = sharedValidationOptions(options.validation ?? options, deadline.signal);
   const diagnostics = await Promise.resolve(validateAzureSsml2(ssml, validationOptions));
-  if (options.signal?.aborted) {
-    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+  if (deadline.signal.aborted) {
+    const error = toSynthesisError(
+      new Error(deadline.timedOut ? "Speech synthesis timed out." : "Speech synthesis was cancelled.")
+    );
+    deadline.dispose();
     return failure(error);
   }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
   if (errors.length > 0) {
+    deadline.dispose();
     return failure({
       kind: "validation-error",
       message: "SSML validation failed; the Azure Speech API was not called.",
@@ -5593,23 +6054,30 @@ async function synthesizeSsmlSafe(client, ssml, options = {}) {
       success: true,
       status: "success",
       value: await client.synthesizeSsml(ssml, {
-        signal: options.signal,
+        signal: deadline.signal,
         timeoutMs: options.timeouts?.perChunkMs,
-        timeouts: options.timeouts
+        timeouts: options.timeouts ? { ...options.timeouts, totalJobMs: void 0 } : void 0
       })
     };
   } catch (error) {
+    if (deadline.timedOut) return failure(toSynthesisError(new Error("Speech synthesis timed out.")));
     const synthesisError = toSynthesisError(error);
     return failure(synthesisError);
+  } finally {
+    deadline.dispose();
   }
 }
 async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
+  const deadline = new DeadlineController(options.timeouts?.totalJobMs, options.signal);
   const validationOptions = sharedValidationOptions(
     { ...options.validation ?? options, timeouts: options.timeouts },
-    options.signal
+    deadline.signal
   );
-  if (options.signal?.aborted) {
-    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+  if (deadline.signal.aborted) {
+    const error = toSynthesisError(
+      new Error(deadline.timedOut ? "Speech synthesis timed out." : "Speech synthesis was cancelled.")
+    );
+    deadline.dispose();
     return failure(error);
   }
   const pending = (index, status, error) => {
@@ -5641,14 +6109,16 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     })
   );
-  if (options.signal?.aborted) {
+  if (deadline.signal.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    deadline.dispose();
     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);
+    deadline.dispose();
     return failure(error);
   }
   let fallbackJobScope;
@@ -5661,9 +6131,9 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
       const value = await client.synthesizeChunks(normalizedChunks, {
         onProgress: options.onProgress,
         outputFormat: options.outputFormat,
-        signal: options.signal,
+        signal: deadline.signal,
         timeoutMs: options.timeoutMs,
-        timeouts: options.timeouts,
+        timeouts: options.timeouts ? { ...options.timeouts, totalJobMs: void 0 } : void 0,
         sourceNodePath: options.sourceNodePath,
         concurrency: options.concurrency,
         retryOptions: options.retryOptions,
@@ -5672,18 +6142,39 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
         resumeChunkIndices: options.resumeChunkIndices,
         customMerger: options.customMerger,
         outputMimeType: options.outputMimeType,
-        postMergeValidator: options.postMergeValidator
+        postMergeValidator: options.postMergeValidator,
+        resumeValidation: options.resumeValidation,
+        customHeaders: options.customHeaders,
+        fingerprintSchemaVersion: options.fingerprintSchemaVersion
       });
       return { ok: true, success: true, status: "success", value };
     }
+    const inputs = chunks.map((chunk) => typeof chunk === "string" ? { ssml: chunk } : chunk);
+    const fingerprints = inputs.map(
+      (chunk) => computeChunkFingerprint(chunk.ssml, options.outputFormat, {
+        customHeaders: options.customHeaders,
+        fingerprintSchemaVersion: options.fingerprintSchemaVersion
+      })
+    );
     const results = new Array(chunks.length);
+    const chunkStates = inputs.map((_chunk, chunkIndex) => ({
+      chunkIndex,
+      status: "pending",
+      canResume: true
+    }));
     const cachedChunks = new Map((options.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+    const invalidCachedIndices = /* @__PURE__ */ new Set();
     for (const [index, cached] of cachedChunks) {
-      if (index >= 0 && index < chunks.length) results[index] = cached;
+      if (index < 0 || index >= chunks.length) continue;
+      if (options.resumeValidation === "disabled" || cached.fingerprint === fingerprints[index]) {
+        results[index] = cached;
+        chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result: cached };
+      } else invalidCachedIndices.add(index);
     }
     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;
+    const shouldSynthesize = (index) => (!cachedChunks.has(index) || invalidCachedIndices.has(index)) && (requestedIndices === void 0 || requestedIndices.has(index) || invalidCachedIndices.has(index));
+    const jobDeadlineAt = deadline.deadlineAtMs;
+    const jobScope = chunks.length > 1 || options.timeouts?.totalJobMs !== void 0 ? createSafeAbortScope(deadline.signal, void 0) : void 0;
     fallbackJobScope = jobScope;
     const failedIndices = /* @__PURE__ */ new Set();
     let firstError;
@@ -5695,7 +6186,10 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
         const index = nextIndex++;
         if (index >= chunks.length) return;
         if (!shouldSynthesize(index)) continue;
-        if (failedIndices.size > 0 && options.cancelOnFailure !== false) return;
+        if (firstError && options.cancelOnFailure !== false) {
+          chunkStates[index] = { chunkIndex: index, status: "cancelled", isOriginalFailure: false, canResume: true };
+          return;
+        }
         const chunk = chunks[index];
         const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
         const sourceNodePath = input.sourceNodePath;
@@ -5704,8 +6198,8 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
         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;
+          const chunkScope = chunkTimeout !== void 0 || jobScope ? createSafeAbortScope(jobScope?.signal ?? deadline.signal, chunkTimeout ?? options.timeoutMs) : void 0;
+          const chunkSignal = chunkScope?.signal ?? deadline.signal;
           let result;
           try {
             result = await retryableSynthesis(
@@ -5728,10 +6222,11 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
                 retryAttempt,
                 nextRetryDelayMs,
                 isRetrying: true
-              })
+              }),
+              jobDeadlineAt
             );
           } catch (error) {
-            if (chunkScope?.timedOut())
+            if (chunkScope?.timedOut() || deadline.timedOut)
               throw new Error(`Speech synthesis timed out after ${chunkTimeout ?? options.timeoutMs} ms.`);
             throw error;
           } finally {
@@ -5780,6 +6275,7 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
               }))
             } : {}
           };
+          chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result: results[index] };
           completed += 1;
           options.onProgress?.({
             currentChunk: completed,
@@ -5791,7 +6287,16 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
             durationMs: Date.now() - startedAt
           });
         } catch (error) {
-          failedIndices.add(index);
+          const wasCancelled = firstError !== void 0 || !deadline.timedOut && Boolean(jobScope?.signal.aborted && !jobScope?.timedOut());
+          firstError ?? (firstError = deadline.timedOut ? new Error("Speech synthesis timed out.") : error);
+          if (!wasCancelled) failedIndices.add(index);
+          chunkStates[index] = {
+            chunkIndex: index,
+            status: wasCancelled ? "cancelled" : "failed",
+            isOriginalFailure: !wasCancelled,
+            canResume: true,
+            error: serializeChunkError(error, "synthesis", !wasCancelled)
+          };
           options.onProgress?.({
             currentChunk: completed,
             totalChunks: chunks.length,
@@ -5803,23 +6308,41 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
             error
           });
           if (options.cancelOnFailure !== false) jobScope?.abort();
-          firstError ?? (firstError = error);
           return;
         }
       }
     };
     await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    if (firstError && options.cancelOnFailure !== false) {
+      for (const [chunkIndex, state] of chunkStates.entries()) {
+        if (state.status === "pending" && shouldSynthesize(chunkIndex)) {
+          chunkStates[chunkIndex] = { chunkIndex, status: "cancelled", isOriginalFailure: false, canResume: true };
+        }
+      }
+    }
     if (failedIndices.size > 0) {
       const error = firstError ?? new Error("One or more SSML chunks failed to synthesize.");
+      const synthesizedChunks = results.flatMap(
+        (result, chunkIndex) => result ? [{ ...result, chunkIndex, fingerprint: fingerprints[chunkIndex] ?? "" }] : []
+      );
       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]),
+        synthesizedChunks,
+        completedChunks: synthesizedChunks,
+        pendingChunkIndices: chunkStates.flatMap(
+          (state) => state.status === "pending" || state.status === "cancelled" || state.status === "failed" ? [state.chunkIndex] : []
+        ),
         failedChunkIndices: [...failedIndices],
+        cancelledChunkIndices: chunkStates.filter((state) => state.status === "cancelled").map((state) => state.chunkIndex),
+        chunkStates,
         totalChunks: chunks.length
       };
       throw error;
     }
+    const missingChunkIndices = Array.from(
+      { length: chunks.length },
+      (_value, index) => results[index] === void 0 ? index : void 0
+    ).filter((index) => index !== void 0);
+    if (missingChunkIndices.length > 0) throw new IncompleteChunkSetError(chunks.length, missingChunkIndices);
     const orderedResults = results.filter((result) => result !== void 0);
     return {
       ok: true,
@@ -5827,7 +6350,7 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
       status: "success",
       value: await mergeSynthesisResults(orderedResults, {
         format: options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3",
-        signal: jobScope?.signal ?? options.signal,
+        signal: jobScope?.signal ?? deadline.signal,
         customMerger: options.customMerger,
         outputMimeType: options.outputMimeType,
         postMergeValidator: options.postMergeValidator
@@ -5838,6 +6361,7 @@ async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
     return failure(synthesisError, partialResultFrom(error));
   } finally {
     fallbackJobScope?.dispose();
+    deadline.dispose();
   }
 }
 function withValidationSignal(options, signal) {
@@ -5858,14 +6382,43 @@ var AzureTtsClient = class {
     __privateSet(this, _options, options);
   }
   async synthesize(ssml) {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = __privateGet(this, _options);
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion
+    } = __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, timeouts };
+    const config = {
+      endpoint,
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      retryOptions: __privateGet(this, _options).retryOptions,
+      customHeaders,
+      fingerprintSchemaVersion
+    };
     return synthesizeSpeech(ssml, config);
   }
   async synthesizeSsml(ssml, options = {}) {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = __privateGet(this, _options);
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion
+    } = __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, {
@@ -5878,11 +6431,28 @@ var AzureTtsClient = class {
       timeouts: options.timeouts ?? timeouts,
       sourceNodePath: options.sourceNodePath,
       sourceTextSegments: options.sourceTextSegments,
-      sourceMarkers: options.sourceMarkers
+      sourceMarkers: options.sourceMarkers,
+      retryOptions: options.retryOptions ?? __privateGet(this, _options).retryOptions,
+      cancelOnFailure: options.cancelOnFailure ?? __privateGet(this, _options).cancelOnFailure,
+      customMerger: options.customMerger ?? __privateGet(this, _options).customMerger,
+      outputMimeType: options.outputMimeType ?? __privateGet(this, _options).outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? __privateGet(this, _options).postMergeValidator,
+      resumeValidation: options.resumeValidation ?? __privateGet(this, _options).resumeValidation,
+      customHeaders: options.customHeaders ?? customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? fingerprintSchemaVersion
     });
   }
   async synthesizeChunks(chunks, options = {}) {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = __privateGet(this, _options);
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion
+    } = __privateGet(this, _options);
     const endpoint = __privateGet(this, _options).endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     return synthesizeSsmlChunks(chunks, {
       endpoint,
@@ -5896,12 +6466,15 @@ var AzureTtsClient = class {
       onProgress: options.onProgress ?? __privateGet(this, _options).onProgress,
       concurrency: options.concurrency ?? __privateGet(this, _options).concurrency,
       retryOptions: options.retryOptions ?? __privateGet(this, _options).retryOptions,
-      cancelOnFailure: options.cancelOnFailure,
+      cancelOnFailure: options.cancelOnFailure ?? __privateGet(this, _options).cancelOnFailure,
       resumeChunks: options.resumeChunks,
       resumeChunkIndices: options.resumeChunkIndices,
-      customMerger: options.customMerger,
-      outputMimeType: options.outputMimeType,
-      postMergeValidator: options.postMergeValidator
+      customMerger: options.customMerger ?? __privateGet(this, _options).customMerger,
+      outputMimeType: options.outputMimeType ?? __privateGet(this, _options).outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? __privateGet(this, _options).postMergeValidator,
+      resumeValidation: options.resumeValidation ?? __privateGet(this, _options).resumeValidation,
+      customHeaders: options.customHeaders ?? customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? fingerprintSchemaVersion
     });
   }
   async synthesizeSsmlSafe(ssml, options = {}) {
@@ -5916,7 +6489,14 @@ var AzureTtsClient = class {
       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
+      retryOptions: options.retryOptions ?? __privateGet(this, _options).retryOptions,
+      cancelOnFailure: options.cancelOnFailure ?? __privateGet(this, _options).cancelOnFailure,
+      customMerger: options.customMerger ?? __privateGet(this, _options).customMerger,
+      outputMimeType: options.outputMimeType ?? __privateGet(this, _options).outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? __privateGet(this, _options).postMergeValidator,
+      resumeValidation: options.resumeValidation ?? __privateGet(this, _options).resumeValidation,
+      customHeaders: options.customHeaders ?? __privateGet(this, _options).customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? __privateGet(this, _options).fingerprintSchemaVersion
     });
   }
   async synthesizeSsmlChunksSafe(chunks, options = {}) {
@@ -6022,6 +6602,8 @@ async function fetchAzureVoiceCatalog(options) {
   BatchChunkValidationError,
   ChunkValidationError,
   DEFAULT_OUTPUT_FORMAT,
+  DeadlineController,
+  IncompleteChunkSetError,
   MergeError,
   SynthesisCancelledError,
   SynthesisTimeoutError,
@@ -6030,6 +6612,7 @@ async function fetchAzureVoiceCatalog(options) {
   buildPartialSsml,
   buildSsml,
   canMergeAudioFormat,
+  computeChunkFingerprint,
   createAzureUrlValidatorRunner,
   extractSsmlText,
   extractSsmlTranslatableText,
@@ -6048,6 +6631,7 @@ async function fetchAzureVoiceCatalog(options) {
   parseSsml,
   resolveMergeAudioFormat,
   resolveMimeType,
+  serializeChunkError,
   splitSsmlDocument,
   synthesizeSpeech,
   synthesizeSsml,