@ssml-builder-js/azure-tts-client 2.16.0 → 2.18.0

package/src/synthesis.ts

@@ -8,6 +8,7 @@ import {
   SynthesisTimeoutError,
   toSynthesisError,
   UnsupportedMergeFormatError,
+  getRetryAfterDelayMs,
 } from "./errors.ts";
 import { DEFAULT_OUTPUT_FORMAT, resolveMimeType, type AzureTtsOutputFormat } from "./outputFormats.ts";
 import { createSpeechConfig } from "./speechConfig.ts";
@@ -19,6 +20,9 @@ import type {
   SynthesisProgressEvent,
   TtsConfig,
   RetryOptions,
+  CustomAudioMerger,
+  PostMergeValidator,
+  ChunkExecutionState,
 } from "./types.ts";
 
 export type MergeAudioFormat = "wav" | "mp3" | "raw";
@@ -31,15 +35,36 @@ export interface MergeAudioOptions {
 
 export type InputAudioSpecs = AudioSpecification[];
 
-export interface CustomMergerContext {
-  format: string;
-  outputMimeType: string;
-  inputSpecs: InputAudioSpecs;
-  signal: AbortSignal;
+/**
+ * Creates a deterministic, runtime-independent fingerprint for a synthesis chunk.
+ * The complete SSML is included so changes to voice, language, prosody, or text
+ * invalidate a cached result even when those settings are nested in the markup.
+ */
+export function computeChunkFingerprint(ssml: string, outputFormat = DEFAULT_OUTPUT_FORMAT): string {
+  const readAttribute = (name: string): string => {
+    const pattern = new RegExp(`(?:${name})\\s*=\\s*[\\"']([^\\"']*)`, "gi");
+    return [...ssml.matchAll(pattern)].map((match) => match[1] ?? "").join("|");
+  };
+  const payload = JSON.stringify({
+    ssml,
+    outputFormat,
+    voice: readAttribute("(?:name|voice)"),
+    language: readAttribute("(?:xml:lang|lang)"),
+    rate: readAttribute("rate"),
+    pitch: readAttribute("pitch"),
+  });
+  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")}`;
 }
 
 export interface MergeSynthesisOptions extends MergeAudioOptions {
-  customMerger?: (buffers: ArrayBuffer[], context: CustomMergerContext) => Promise<ArrayBuffer> | ArrayBuffer;
+  customMerger?: CustomAudioMerger;
+  postMergeValidator?: PostMergeValidator;
 }
 
 type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
@@ -99,9 +124,11 @@ function parseWav(buffer: ArrayBuffer): ParsedWav {
   return { chunks, data, format };
 }
 
-function formatNumber(format: string, pattern: RegExp, fallback: number): number {
-  const match = pattern.exec(format);
-  return match?.[1] ? Number(match[1]) : fallback;
+function formatSampleRate(format: string): number {
+  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 * 1000 : value;
 }
 
 function formatChannels(format: string, fallback: number): number {
@@ -111,7 +138,7 @@ function formatChannels(format: string, fallback: number): number {
 }
 
 function formatAudioSpecification(format: string): AudioSpecification {
-  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]) * 1000 : undefined;
@@ -121,9 +148,27 @@ function formatAudioSpecification(format: string): AudioSpecification {
       ? "opus"
       : /silk/i.test(format)
         ? "silk"
-        : /pcm|mulaw|alaw|siren/i.test(format)
-          ? "pcm"
-          : "unknown";
+        : /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"
+            : undefined;
   return {
     format,
     mimeType: resolveMimeType(format),
@@ -131,7 +176,10 @@ function formatAudioSpecification(format: string): AudioSpecification {
     sampleRate,
     channels,
     ...(bitrate ? { bitrate } : {}),
-    isCompressed: codec === "mp3" || codec === "opus" || codec === "silk",
+    ...(bitDepthMatch?.[1] ? { bitDepth: Number(bitDepthMatch[1]) } : {}),
+    ...(container ? { container } : {}),
+    isVbr: /vbr/i.test(format),
+    isCompressed: codec !== "pcm" && codec !== "unknown",
   };
 }
 
@@ -167,6 +215,8 @@ function parseMp3Specification(buffer: ArrayBuffer, format: string): AudioSpecif
       sampleRate,
       channels: (bytes[index + 3] ?? 0) >> 6 === 3 ? 1 : 2,
       bitrate: bitrateKbps * 1000,
+      container: "mp3-raw",
+      isVbr: false,
       isCompressed: true,
     };
   }
@@ -183,18 +233,47 @@ export function inspectAudioSpecification(buffer: ArrayBuffer, format: string):
     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: AudioSpecification["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 } : {}),
-      isCompressed: formatCode !== 1,
+      bitDepth: bitsPerSample,
+      container: "riff-wave",
+      isVbr: false,
+      isCompressed: codec !== "pcm" && codec !== "unknown",
     };
   }
   if (isMp3Format(format)) return parseMp3Specification(buffer, format) ?? formatAudioSpecification(format);
-  return formatAudioSpecification(format);
+  const specification = formatAudioSpecification(format);
+  if (specification.container === "raw") validateRawAudioBuffer(buffer, specification);
+  return specification;
+}
+
+function validateRawAudioBuffer(buffer: ArrayBuffer, specification: AudioSpecification): void {
+  if (specification.sampleRate <= 0 || specification.channels <= 0 || specification.bitDepth === undefined) {
+    throw new Error(`RAW audio format "${specification.format}" does not define a complete audio specification.`);
+  }
+  if (specification.codec === "siren" || specification.codec === "silk") 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 validateAudioSpecifications(specs: readonly AudioSpecification[]): void {
@@ -204,7 +283,11 @@ function validateAudioSpecifications(specs: readonly AudioSpecification[]): void
     (spec) =>
       spec.sampleRate !== first.sampleRate ||
       spec.channels !== first.channels ||
-      (first.bitrate !== undefined && spec.bitrate !== undefined && spec.bitrate !== first.bitrate),
+      spec.codec !== first.codec ||
+      (first.bitrate !== undefined && spec.bitrate !== undefined && spec.bitrate !== first.bitrate) ||
+      (first.bitDepth !== undefined && spec.bitDepth !== undefined && spec.bitDepth !== first.bitDepth) ||
+      (first.container !== undefined && spec.container !== undefined && spec.container !== first.container) ||
+      (first.isVbr !== undefined && spec.isVbr !== undefined && spec.isVbr !== first.isVbr),
   );
   if (mismatch)
     throw new AudioFormatMismatchError(
@@ -303,6 +386,43 @@ function isRawFormat(format: string): boolean {
   return /^raw(?:-|$)/i.test(format);
 }
 
+function validateMergedAudioBuffer(
+  merged: ArrayBuffer,
+  format: string,
+  buffers: readonly ArrayBuffer[],
+  inputSpecs: readonly AudioSpecification[],
+  outputMimeType: string,
+): AudioSpecification {
+  if (!(merged instanceof ArrayBuffer) || merged.byteLength === 0) {
+    throw new MergeError("The custom audio merger returned an empty or invalid audio buffer.");
+  }
+  const specification = inspectAudioSpecification(merged, 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 !== undefined && 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;
+}
+
 /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
 export function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined {
   if (isWavFormat(format)) return "wav";
@@ -362,7 +482,7 @@ function closeSpeechResources(speechConfig: SpeechSDK.SpeechConfig, synthesizer:
 
 const ticksToMilliseconds = (ticks: number): number => Math.max(0, ticks) / 10_000;
 
-export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult> {
+async function synthesizeSsmlOnce(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult> {
   if (config.signal?.aborted) {
     throw new SynthesisCancelledError();
   }
@@ -448,9 +568,7 @@ export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<S
         };
       }
       if (sourceSegments.length === 0 && !config.sourceTextRange && !config.sourceNodePath) {
-        const unmapped: { mappingStatus: "unmapped" } = { mappingStatus: "unmapped" };
-        Object.defineProperty(unmapped, "mappingStatus", { value: "unmapped", enumerable: false });
-        return unmapped;
+        return { mappingStatus: "unmapped" };
       }
       const value = text ?? "";
       let localStart = Number.isFinite(offsetHint) && (offsetHint ?? 0) >= 0 ? (offsetHint as number) : -1;
@@ -522,6 +640,13 @@ export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<S
         rejectWithError(err);
         return;
       }
+      let audioSpec: AudioSpecification;
+      try {
+        audioSpec = inspectAudioSpecification(result.audioData, config.outputFormat ?? DEFAULT_OUTPUT_FORMAT);
+      } catch (error) {
+        rejectWithError(error);
+        return;
+      }
       settled = true;
       cleanup();
       closeResources();
@@ -546,8 +671,13 @@ export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<S
           ...(config.sourceNodePath ? { sourceNodePath: [...config.sourceNodePath] } : {}),
           ...(requestId ? { requestId } : {}),
         } as T;
-        if (event.mappingStatus === "unmapped")
+        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));
@@ -556,8 +686,8 @@ export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<S
       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
@@ -573,10 +703,11 @@ export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<S
         abortHandler = () => rejectWithError(new SynthesisCancelledError());
         config.signal.addEventListener("abort", abortHandler, { once: true });
       }
-      if (config.timeoutMs !== undefined && config.timeoutMs > 0) {
+      const timeoutMs = config.timeouts?.perChunkMs ?? config.timeouts?.totalJobMs ?? config.timeoutMs;
+      if (timeoutMs !== undefined && 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);
@@ -597,7 +728,9 @@ function isRetryableSynthesisError(error: unknown): boolean {
   return /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message);
 }
 
-function retryDelay(options: RetryOptions, retryAttempt: number): number {
+function retryDelay(options: RetryOptions, retryAttempt: number, error?: unknown): number {
+  const retryAfterMs = getRetryAfterDelayMs(error);
+  if (retryAfterMs !== undefined) return retryAfterMs;
   const base = Math.min(options.maxDelayMs, options.initialDelayMs * 2 ** Math.max(0, retryAttempt - 1));
   return Math.floor(Math.random() * (base + 1));
 }
@@ -633,39 +766,147 @@ async function synthesizeWithRetry(
   config: TtsConfig,
   retryOptions: RetryOptions | undefined,
   onRetry: (retryAttempt: number, nextRetryDelayMs: number) => void,
+  deadlineAtMs?: number,
 ): Promise<SsmlSynthesisResult> {
   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,
       }
     : undefined;
   let attempt = 0;
   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 || !isRetryableSynthesisError(error)) throw error;
+      if (
+        !options ||
+        attempt >= options.maxRetries ||
+        !(options.shouldRetry?.(error, attempt + 1) ?? isRetryableSynthesisError(error))
+      )
+        throw error;
       attempt += 1;
-      const delayMs = retryDelay(options, attempt);
+      const delayMs = retryDelay(options, attempt, error);
+      const remainingMs = deadlineAtMs === undefined ? undefined : Math.max(0, deadlineAtMs - Date.now());
+      if (
+        getRetryAfterDelayMs(error) !== undefined &&
+        (delayMs > options.maxDelayMs || (remainingMs !== undefined && delayMs > remainingMs))
+      ) {
+        throw new SynthesisTimeoutError(
+          remainingMs === undefined
+            ? `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);
     }
   }
 }
 
+/** Synthesizes one SSML document, optionally retrying transient failures within the job deadline. */
+export async function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult> {
+  const totalJobMs = config.timeouts?.totalJobMs;
+  const deadlineAtMs = totalJobMs !== undefined && totalJobMs > 0 ? Date.now() + totalJobMs : undefined;
+  if (!config.retryOptions) return synthesizeSsmlOnce(ssml, config);
+  return synthesizeWithRetry(ssml, config, config.retryOptions, () => undefined, deadlineAtMs);
+}
+
+interface AbortScope {
+  signal: AbortSignal;
+  timedOut: () => boolean;
+  dispose: () => void;
+  abort: () => void;
+}
+
+function createAbortScope(parent: AbortSignal | undefined, timeoutMs: number | undefined): AbortScope {
+  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 !== undefined && timeoutMs > 0
+      ? setTimeout(() => {
+          didTimeout = true;
+          controller.abort();
+        }, timeoutMs)
+      : undefined;
+  return {
+    signal: controller.signal,
+    timedOut: () => didTimeout,
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      parent?.removeEventListener("abort", onAbort);
+    },
+    abort: () => controller.abort(),
+  };
+}
+
+async function synthesizeChunkWithTimeout(
+  ssml: string,
+  config: TtsConfig,
+  retryOptions: RetryOptions | undefined,
+  timeoutMs: number | undefined,
+  onRetry: (retryAttempt: number, nextRetryDelayMs: number) => void,
+  deadlineAtMs?: number,
+): Promise<SsmlSynthesisResult> {
+  const scope = createAbortScope(config.signal, timeoutMs);
+  try {
+    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;
+  } finally {
+    scope.dispose();
+  }
+}
+
 /** Synthesizes chunks with bounded concurrency, retries transient failures, and merges in chunk order. */
 export async function synthesizeSsmlChunks(
   chunks: readonly (SsmlSynthesisChunk | string)[],
   config: TtsConfig,
 ): Promise<SsmlSynthesisResult> {
-  const results: Array<SsmlSynthesisResult | undefined> = 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),
+  );
+  const results: Array<SsmlSynthesisResult | undefined> = new Array(totalChunks);
+  const cachedChunks = new Map((config.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+  const invalidCachedIndices = new Set<number>();
+  const chunkStates: ChunkExecutionState[] = inputs.map((_chunk, chunkIndex) => ({
+    chunkIndex,
+    status: "pending",
+    canResume: true,
+  }));
+  for (const [index, cached] of cachedChunks) {
+    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))
+    : undefined;
+  const shouldSynthesize = (index: number): boolean =>
+    (!cachedChunks.has(index) || invalidCachedIndices.has(index)) &&
+    (requestedIndices === undefined || requestedIndices.has(index) || invalidCachedIndices.has(index));
+  const jobStartedAt = Date.now();
+  const jobDeadlineAt =
+    config.timeouts?.totalJobMs !== undefined && config.timeouts.totalJobMs > 0
+      ? jobStartedAt + config.timeouts.totalJobMs
+      : undefined;
+  const scope = createAbortScope(config.signal, config.timeouts?.totalJobMs);
   const report = (event: SynthesisProgressEvent): void => 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,
@@ -676,15 +917,18 @@ export async function synthesizeSsmlChunks(
       durationMs: 0,
     });
   }
-  let completed = 0;
+  let completed = [...results].filter((result) => result !== undefined).length;
   let nextIndex = 0;
   const concurrency = resolveConcurrency(config.concurrency, chunks.length);
+  let firstError: unknown;
+  const failedIndices = new Set<number>();
   const worker = async (): Promise<void> => {
     while (true) {
       const index = nextIndex++;
       if (index >= chunks.length) return;
-      const chunk = chunks[index];
-      const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
+      if (!shouldSynthesize(index)) continue;
+      if (firstError && config.cancelOnFailure !== false) return;
+      const input = inputs[index];
       report({
         currentChunk: completed,
         totalChunks,
@@ -696,10 +940,11 @@ export async function synthesizeSsmlChunks(
       });
       const startedAt = Date.now();
       try {
-        const result = await synthesizeWithRetry(
+        const result = await synthesizeChunkWithTimeout(
           input.ssml,
           {
             ...config,
+            signal: scope.signal,
             ...(input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {}),
             ...((input.sourceNodePath ?? config.sourceNodePath)
               ? { sourceNodePath: [...(input.sourceNodePath ?? config.sourceNodePath ?? [])] }
@@ -710,6 +955,7 @@ export async function synthesizeSsmlChunks(
             onProgress: undefined,
           },
           config.retryOptions,
+          config.timeouts?.chunkWithRetriesMs ?? config.timeouts?.perChunkMs ?? config.timeoutMs,
           (retryAttempt, nextRetryDelayMs) =>
             report({
               currentChunk: completed,
@@ -723,8 +969,10 @@ export async function synthesizeSsmlChunks(
               nextRetryDelayMs,
               isRetrying: true,
             }),
+          jobDeadlineAt,
         );
         results[index] = result;
+        chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result };
         completed += 1;
         report({
           currentChunk: completed,
@@ -736,6 +984,18 @@ export async function synthesizeSsmlChunks(
           durationMs: Date.now() - startedAt,
         });
       } catch (error) {
+        const wasCancelled = firstError !== undefined || (scope.signal.aborted && !scope.timedOut());
+        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: error as ChunkExecutionState["error"],
+        };
         report({
           currentChunk: completed,
           totalChunks,
@@ -746,16 +1006,53 @@ export async function synthesizeSsmlChunks(
           durationMs: Date.now() - startedAt,
           error,
         });
-        throw error;
+        if (config.cancelOnFailure !== false) scope.abort();
+        return;
       }
     }
   };
-  await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
-  const orderedResults = results.filter((result): result is SsmlSynthesisResult => result !== undefined);
-  return mergeSynthesisResults(orderedResults, {
-    format: (config.outputFormat ?? DEFAULT_OUTPUT_FORMAT) as AzureTtsOutputFormat,
-    signal: config.signal,
-  });
+  try {
+    await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    if (firstError) throw firstError;
+    const orderedResults = results.filter((result): result is SsmlSynthesisResult => result !== undefined);
+    return await mergeSynthesisResults(orderedResults, {
+      format: (config.outputFormat ?? DEFAULT_OUTPUT_FORMAT) as AzureTtsOutputFormat,
+      signal: scope.signal,
+      customMerger: config.customMerger,
+      outputMimeType: config.outputMimeType,
+      postMergeValidator: config.postMergeValidator,
+    });
+  } 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,
+      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 as { partialResult?: unknown }).partialResult = partial;
+    throw error;
+  } finally {
+    scope.dispose();
+  }
 }
 
 /** Concatenates audio buffers and shifts all synchronization events by prior chunk durations. */
@@ -845,6 +1142,10 @@ export function mergeSynthesisResults(
   results: readonly SsmlSynthesisResult[],
   options: AsyncMergeSynthesisOptions,
 ): Promise<MergedSynthesisResult>;
+export function mergeSynthesisResults(
+  results: readonly SsmlSynthesisResult[],
+  options: MergeSynthesisOptions,
+): MergedSynthesisResult | Promise<MergedSynthesisResult>;
 export function mergeSynthesisResults(
   results: readonly SsmlSynthesisResult[],
   options: MergeAudioOptions,
@@ -874,19 +1175,26 @@ export function mergeSynthesisResults(
       )
       .then((merged) => {
         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();
-        return createMergedResult(
-          results,
+        const mergedSpec = validateMergedAudioBuffer(
           merged,
           format,
-          inspectAudioSpecification(merged, format),
-          resolvedOptions.outputMimeType,
+          buffers,
+          inputSpecs,
+          resolvedOptions.outputMimeType ?? resolveMimeType(format),
         );
+        const result = createMergedResult(results, merged, format, mergedSpec, 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: unknown) => {
         if (error instanceof UnsupportedMergeFormatError || isAudioFormatMismatch(error) || error instanceof MergeError)
@@ -895,13 +1203,28 @@ export function mergeSynthesisResults(
       });
   }
   try {
-    return createMergedResult(
+    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 || isAudioFormatMismatch(error) || error instanceof MergeError)
       throw error;