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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssml-builder-js/azure-tts-client",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Azure Text-to-Speech client using the Microsoft Speech SDK",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@ssml-builder-js/ssml-core": "^2.16.0",
+    "@ssml-builder-js/ssml-core": "^2.17.0",
     "microsoft-cognitiveservices-speech-sdk": "1.51.0"
   }
 }

package/src/client.ts

@@ -19,16 +19,16 @@ export class AzureTtsClient {
   }
 
   async synthesize(ssml: string): Promise<ArrayBuffer> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = this.#options;
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     this.#options.logger?.debug?.("Using Azure TTS endpoint:", endpoint);
 
-    const config = { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs };
+    const config = { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts };
     return synthesizeSpeech(ssml, config);
   }
 
   async synthesizeSsml(ssml: string, options: Partial<TtsConfig> = {}): Promise<SsmlSynthesisResult> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = this.#options;
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     this.#options.logger?.debug?.("Using Azure TTS endpoint:", endpoint);
 
@@ -39,6 +39,7 @@ export class AzureTtsClient {
       outputFormat: options.outputFormat ?? outputFormat,
       signal: options.signal ?? signal,
       timeoutMs: options.timeoutMs ?? timeoutMs,
+      timeouts: options.timeouts ?? timeouts,
       sourceNodePath: options.sourceNodePath,
       sourceTextSegments: options.sourceTextSegments,
       sourceMarkers: options.sourceMarkers,
@@ -49,7 +50,7 @@ export class AzureTtsClient {
     chunks: readonly (SsmlSynthesisChunk | string)[],
     options: SynthesizeChunksOptions = {},
   ): Promise<SsmlSynthesisResult> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = this.#options;
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     return synthesizeSsmlChunks(chunks, {
       endpoint,
@@ -58,10 +59,17 @@ export class AzureTtsClient {
       outputFormat: options.outputFormat ?? outputFormat,
       signal: options.signal ?? signal,
       timeoutMs: options.timeoutMs ?? timeoutMs,
+      timeouts: options.timeouts ?? timeouts,
       sourceNodePath: options.sourceNodePath,
       onProgress: options.onProgress ?? this.#options.onProgress,
       concurrency: options.concurrency ?? this.#options.concurrency,
       retryOptions: options.retryOptions ?? this.#options.retryOptions,
+      cancelOnFailure: options.cancelOnFailure,
+      resumeChunks: options.resumeChunks,
+      resumeChunkIndices: options.resumeChunkIndices,
+      customMerger: options.customMerger,
+      outputMimeType: options.outputMimeType,
+      postMergeValidator: options.postMergeValidator,
     });
   }
 
@@ -78,6 +86,7 @@ export class AzureTtsClient {
       outputFormat: options.outputFormat ?? this.#options.outputFormat,
       signal: options.signal ?? this.#options.signal,
       timeoutMs: options.timeoutMs ?? this.#options.timeoutMs,
+      timeouts: options.timeouts ?? this.#options.timeouts,
       onProgress: options.onProgress ?? this.#options.onProgress,
       concurrency: options.concurrency ?? this.#options.concurrency,
       retryOptions: options.retryOptions ?? this.#options.retryOptions,

package/src/errors.ts

@@ -13,15 +13,57 @@ export class AzureTtsError extends Error {
   readonly statusText: string;
   readonly responseBody: string;
   readonly requestId: string | null;
-
-  constructor(status: number, statusText: string, responseBody: string, requestId: string | null) {
+  readonly retryAfterMs?: number;
+
+  constructor(
+    status: number,
+    statusText: string,
+    responseBody: string,
+    requestId: string | null,
+    responseHeaders?: Headers | Readonly<Record<string, string>>,
+  ) {
     super(`Azure TTS request failed: ${status} ${statusText}`);
     this.name = "AzureTtsError";
     this.status = status;
     this.statusText = statusText;
     this.responseBody = responseBody;
     this.requestId = requestId;
+    const value =
+      responseHeaders instanceof Headers
+        ? responseHeaders.get("retry-after")
+        : (responseHeaders?.["retry-after"] ?? responseHeaders?.["Retry-After"]);
+    const seconds = value ? Number(value.trim()) : NaN;
+    const date = value ? Date.parse(value) : NaN;
+    if (Number.isFinite(seconds) && seconds >= 0) this.retryAfterMs = seconds * 1000;
+    else if (Number.isFinite(date)) this.retryAfterMs = Math.max(0, date - Date.now());
+  }
+}
+
+/** Reads Retry-After from an error-like value, returning milliseconds when present. */
+export function getRetryAfterDelayMs(error: unknown): number | undefined {
+  if (error instanceof AzureTtsError && error.retryAfterMs !== undefined) return error.retryAfterMs;
+  if (!error || typeof error !== "object") return undefined;
+  const candidate = error as { retryAfterMs?: unknown; headers?: unknown; response?: unknown };
+  if (typeof candidate.retryAfterMs === "number" && candidate.retryAfterMs >= 0) return candidate.retryAfterMs;
+  const headers = candidate.headers ?? (candidate.response as { headers?: unknown } | undefined)?.headers;
+  if (headers instanceof Headers) {
+    const value = headers.get("retry-after");
+    if (!value) return undefined;
+    const seconds = Number(value.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
+  }
+  if (headers && typeof headers === "object") {
+    const value =
+      (headers as Record<string, unknown>)["retry-after"] ?? (headers as Record<string, unknown>)["Retry-After"];
+    if (typeof value !== "string") return undefined;
+    const seconds = Number(value.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
   }
+  return undefined;
 }
 
 export class AzureTtsSdkError extends AzureTtsError {

package/src/index.ts

@@ -17,6 +17,13 @@ export type {
   SynthesizeChunksOptions,
   SynthesisChunkStatus,
   RetryOptions,
+  SynthesisTimeouts,
+  SynthesizedChunk,
+  PartialChunkSynthesisResult,
+  PartialSynthesisResult,
+  CustomMergerContext,
+  CustomAudioMerger,
+  PostMergeValidator,
   TtsConfig,
 } from "./types.ts";
 export {
@@ -27,6 +34,7 @@ export {
   SynthesisCancelledError,
   SynthesisTimeoutError,
   UnsupportedMergeFormatError,
+  getRetryAfterDelayMs,
 } from "./errors.ts";
 export type { AzureTtsSynthesisError, SynthesisErrorKind } from "./errors.ts";
 export { AzureTtsClient } from "./client.ts";
@@ -41,7 +49,6 @@ export {
   synthesizeSsmlChunks,
 } from "./synthesis.ts";
 export type {
-  CustomMergerContext,
   InputAudioSpecs,
   MergeAudioFormat,
   MergeAudioOptions,
@@ -49,7 +56,12 @@ export type {
 } from "./synthesis.ts";
 export { DEFAULT_OUTPUT_FORMAT, resolveMimeType } from "./outputFormats.ts";
 export type { AzureTtsOutputFormat } from "./outputFormats.ts";
-export { ChunkValidationError, synthesizeSsmlChunksSafe, synthesizeSsmlSafe } from "./safe.ts";
+export {
+  BatchChunkValidationError,
+  ChunkValidationError,
+  synthesizeSsmlChunksSafe,
+  synthesizeSsmlSafe,
+} from "./safe.ts";
 export type {
   AzureApiErrorResult,
   Result,
@@ -62,6 +74,7 @@ export type {
   SsmlSynthesisChunksSafeResult,
   SynthesizeSsmlChunksSafeOptions,
   ValidationErrorResult,
+  ChunkDiagnostics,
 } from "./safe.ts";
 export { fetchAzureVoiceCatalog } from "./voiceCatalog.ts";
 export type {

package/src/safe.ts

@@ -10,6 +10,7 @@ import {
   type AzureTtsSynthesisError,
   type SynthesisErrorKind,
   toSynthesisError,
+  getRetryAfterDelayMs,
 } from "./errors.ts";
 import type { AzureTtsClient } from "./client.ts";
 import { mergeSynthesisResults } from "./synthesis.ts";
@@ -19,6 +20,11 @@ import type {
   SynthesisProgressEvent,
   SynthesizeChunksOptions,
   RetryOptions,
+  SynthesisTimeouts,
+  SynthesizedChunk,
+  PartialChunkSynthesisResult,
+  CustomAudioMerger,
+  PostMergeValidator,
 } from "./types.ts";
 import type { AzureTtsOutputFormat } from "./outputFormats.ts";
 
@@ -43,6 +49,29 @@ export class ChunkValidationError extends Error {
   }
 }
 
+export interface ChunkDiagnostics {
+  readonly chunkIndex: number;
+  readonly diagnostics: readonly SsmlDiagnostic[];
+}
+
+export class BatchChunkValidationError extends ChunkValidationError {
+  readonly chunkDiagnostics: readonly ChunkDiagnostics[];
+  readonly totalErrorCount: number;
+  readonly errorCount: number;
+  readonly totalErrors: number;
+
+  constructor(chunkDiagnostics: readonly ChunkDiagnostics[]) {
+    const first = chunkDiagnostics[0];
+    super(first?.chunkIndex ?? -1, first?.diagnostics ?? []);
+    this.name = "BatchChunkValidationError";
+    this.message = `SSML validation failed for ${chunkDiagnostics.length} chunk(s); the Azure Speech API was not called.`;
+    this.chunkDiagnostics = chunkDiagnostics;
+    this.totalErrorCount = chunkDiagnostics.reduce((total, chunk) => total + chunk.diagnostics.length, 0);
+    this.errorCount = this.totalErrorCount;
+    this.totalErrors = this.totalErrorCount;
+  }
+}
+
 export type Result<T, E> =
   | { readonly ok: true; readonly success: true; readonly status: "success"; readonly value: T }
   | (E extends { readonly kind: infer Kind extends SynthesisErrorKind }
@@ -51,18 +80,29 @@ export type Result<T, E> =
           readonly success: false;
           readonly status: Kind;
           readonly error: E;
+          readonly partialResult?: PartialChunkSynthesisResult;
         }
       : {
           readonly ok: false;
           readonly success: false;
           readonly status: SynthesisErrorKind;
           readonly error: E;
+          readonly partialResult?: PartialChunkSynthesisResult;
         });
 
 export type SynthesisResult<T, E> = Result<T, E>;
 
-function failure<E extends { readonly kind: SynthesisErrorKind }>(error: E): Result<never, E> {
-  return { ok: false, success: false, status: error.kind, error } as Result<never, E>;
+function failure<E extends { readonly kind: SynthesisErrorKind }>(
+  error: E,
+  partialResult?: PartialChunkSynthesisResult,
+): Result<never, E> {
+  return {
+    ok: false,
+    success: false,
+    status: error.kind,
+    error,
+    ...(partialResult ? { partialResult } : {}),
+  } as Result<never, E>;
 }
 
 export type Success<T> = Extract<Result<T, never>, { readonly ok: true }>;
@@ -81,6 +121,7 @@ export interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
   /** Optional nested form for callers that want to keep validation settings grouped. */
   validation?: AzureValidationOptions;
   signal?: AbortSignal;
+  timeouts?: SynthesisTimeouts;
 }
 
 export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
@@ -88,15 +129,23 @@ export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions
   outputFormat?: string;
   signal?: AbortSignal;
   timeoutMs?: number;
+  timeouts?: SynthesisTimeouts;
   sourceNodePath?: string[];
   onProgress?: (event: SynthesisProgressEvent) => void;
   concurrency?: number;
   retryOptions?: RetryOptions;
+  cancelOnFailure?: boolean;
+  resumeChunks?: readonly SynthesizedChunk[];
+  resumeChunkIndices?: readonly number[];
+  customMerger?: CustomAudioMerger;
+  outputMimeType?: string;
+  postMergeValidator?: PostMergeValidator;
 }
 
 export type SsmlSynthesisChunksSafeResult =
   | Result<SsmlSynthesisResult, never>
   | Result<never, ChunkValidationError>
+  | Result<never, BatchChunkValidationError>
   | Result<never, SsmlSynthesisError | ChunkValidationError>;
 
 interface SynthesisClient {
@@ -107,6 +156,44 @@ interface SynthesisClient {
   ): Promise<SsmlSynthesisResult>;
 }
 
+function partialResultFrom(error: unknown): PartialChunkSynthesisResult | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const partial = (error as { partialResult?: unknown }).partialResult;
+  if (!partial || typeof partial !== "object") return undefined;
+  return partial as PartialChunkSynthesisResult;
+}
+
+interface SafeAbortScope {
+  signal: AbortSignal;
+  timedOut: () => boolean;
+  dispose: () => void;
+  abort: () => void;
+}
+
+function createSafeAbortScope(parent: AbortSignal | undefined, timeoutMs: number | undefined): SafeAbortScope {
+  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(),
+  };
+}
+
 function isRetryable(error: unknown): boolean {
   if (error instanceof Error && /cancel|abort|tim(?:e|ed) ?out/i.test(error.message)) return false;
   const status =
@@ -123,6 +210,10 @@ function delayForRetry(options: RetryOptions, attempt: number): number {
   return Math.floor(Math.random() * (base + 1));
 }
 
+function retryDelayForError(options: RetryOptions, attempt: number, error: unknown): number {
+  return getRetryAfterDelayMs(error) ?? delayForRetry(options, attempt);
+}
+
 function resolveConcurrency(value: number | undefined, total: number): number {
   if (value === undefined) return 1;
   if (value === Infinity) return Math.max(1, total);
@@ -140,6 +231,7 @@ async function retryableSynthesis(
         maxRetries: Math.max(0, Math.floor(options.maxRetries)),
         initialDelayMs: options.initialDelayMs,
         maxDelayMs: options.maxDelayMs,
+        shouldRetry: options.shouldRetry,
       }
     : undefined;
   let attempt = 0;
@@ -148,9 +240,10 @@ async function retryableSynthesis(
     try {
       return await synthesize();
     } catch (error) {
-      if (!retry || attempt >= retry.maxRetries || !isRetryable(error)) throw error;
+      if (!retry || attempt >= retry.maxRetries || !(retry.shouldRetry?.(error, attempt + 1) ?? isRetryable(error)))
+        throw error;
       attempt += 1;
-      const delayMs = delayForRetry(retry, attempt);
+      const delayMs = retryDelayForError(retry, attempt, error);
       onRetry(attempt, delayMs);
       if (delayMs > 0)
         await new Promise<void>((resolve, reject) => {
@@ -169,13 +262,20 @@ async function retryableSynthesis(
   }
 }
 
-function sharedValidationOptions(options: AzureValidationOptions, signal?: AbortSignal): AzureValidationOptions {
+function sharedValidationOptions(
+  options: AzureValidationOptions & { timeouts?: SynthesisTimeouts },
+  signal?: AbortSignal,
+): AzureValidationOptions {
   const validator = options.urlValidator ?? options.customUrlValidator;
   if (!validator) return signal ? withValidationSignal(options, signal) : options;
   const runner = createAzureUrlValidatorRunner(validator as AzureUrlValidator, {
     ...(options.urlValidation ?? {}),
     ...(options.urlValidatorConcurrency !== undefined ? { concurrency: options.urlValidatorConcurrency } : {}),
-    ...(options.urlValidatorTimeoutMs !== undefined ? { timeoutMs: options.urlValidatorTimeoutMs } : {}),
+    ...(options.timeouts?.urlValidationMs !== undefined
+      ? { timeoutMs: options.timeouts.urlValidationMs }
+      : options.urlValidatorTimeoutMs !== undefined
+        ? { timeoutMs: options.urlValidatorTimeoutMs }
+        : {}),
     ...(signal ? { signal } : {}),
     ...(options.urlValidatorCache ? { cache: options.urlValidatorCache } : {}),
   });
@@ -211,7 +311,11 @@ export async function synthesizeSsmlSafe(
       ok: true,
       success: true,
       status: "success",
-      value: await client.synthesizeSsml(ssml, { signal: options.signal }),
+      value: await client.synthesizeSsml(ssml, {
+        signal: options.signal,
+        timeoutMs: options.timeouts?.perChunkMs,
+        timeouts: options.timeouts,
+      }),
     };
   } catch (error) {
     const synthesisError = toSynthesisError(error);
@@ -225,7 +329,10 @@ export async function synthesizeSsmlChunksSafe(
   chunks: readonly (SsmlSynthesisChunk | string)[],
   options: SynthesizeSsmlChunksSafeOptions = {},
 ): Promise<SsmlSynthesisChunksSafeResult> {
-  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
+  const validationOptions = sharedValidationOptions(
+    { ...(options.validation ?? options), timeouts: options.timeouts },
+    options.signal,
+  );
   if (options.signal?.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
     return failure(error);
@@ -261,17 +368,20 @@ export async function synthesizeSsmlChunksSafe(
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     }),
   );
-  const firstInvalidIndex = validations.findIndex((diagnostics) => diagnostics.length > 0);
   if (options.signal?.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
     return failure(error);
   }
-  if (firstInvalidIndex >= 0) {
-    const error = new ChunkValidationError(firstInvalidIndex, validations[firstInvalidIndex] ?? []);
-    pending(firstInvalidIndex, "failed", error);
+  const chunkDiagnostics = validations
+    .map((diagnostics, chunkIndex) => ({ chunkIndex, diagnostics }))
+    .filter((entry) => entry.diagnostics.length > 0);
+  if (chunkDiagnostics.length > 0) {
+    const error = new BatchChunkValidationError(chunkDiagnostics);
+    for (const entry of chunkDiagnostics) pending(entry.chunkIndex, "failed", error);
     return failure(error);
   }
 
+  let fallbackJobScope: SafeAbortScope | undefined;
   try {
     if (client.synthesizeChunks) {
       const normalizedChunks = chunks.map((chunk) => {
@@ -283,20 +393,45 @@ export async function synthesizeSsmlChunksSafe(
         outputFormat: options.outputFormat,
         signal: options.signal,
         timeoutMs: options.timeoutMs,
+        timeouts: options.timeouts,
         sourceNodePath: options.sourceNodePath,
         concurrency: options.concurrency,
         retryOptions: options.retryOptions,
+        cancelOnFailure: options.cancelOnFailure,
+        resumeChunks: options.resumeChunks,
+        resumeChunkIndices: options.resumeChunkIndices,
+        customMerger: options.customMerger,
+        outputMimeType: options.outputMimeType,
+        postMergeValidator: options.postMergeValidator,
       });
       return { ok: true, success: true, status: "success", value };
     }
     const results: Array<SsmlSynthesisResult | undefined> = new Array(chunks.length);
-    let completed = 0;
+    const cachedChunks = new Map((options.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+    for (const [index, cached] of cachedChunks) {
+      if (index >= 0 && index < chunks.length) results[index] = cached;
+    }
+    const requestedIndices = options.resumeChunkIndices
+      ? new Set(options.resumeChunkIndices.filter((index) => index >= 0 && index < chunks.length))
+      : undefined;
+    const shouldSynthesize = (index: number): boolean =>
+      !cachedChunks.has(index) && (requestedIndices === undefined || requestedIndices.has(index));
+    const jobScope =
+      chunks.length > 1 || options.timeouts?.totalJobMs !== undefined
+        ? createSafeAbortScope(options.signal, options.timeouts?.totalJobMs)
+        : undefined;
+    fallbackJobScope = jobScope;
+    const failedIndices = new Set<number>();
+    let firstError: unknown;
+    let completed = [...results].filter((result) => result !== undefined).length;
     let nextIndex = 0;
     const concurrency = resolveConcurrency(options.concurrency, chunks.length);
     const worker = async (): Promise<void> => {
       while (true) {
         const index = nextIndex++;
         if (index >= chunks.length) return;
+        if (!shouldSynthesize(index)) continue;
+        if (failedIndices.size > 0 && options.cancelOnFailure !== false) return;
         const chunk = chunks[index];
         const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
         const sourceNodePath = input.sourceNodePath;
@@ -304,30 +439,45 @@ export async function synthesizeSsmlChunksSafe(
         pending(index, "synthesizing");
         const startedAt = Date.now();
         try {
-          const result = await retryableSynthesis(
-            () =>
-              client.synthesizeSsml(input.ssml, {
-                outputFormat: options.outputFormat,
-                signal: options.signal,
-                timeoutMs: options.timeoutMs,
-                sourceNodePath: input.sourceNodePath ?? options.sourceNodePath,
-              }),
-            options.retryOptions,
-            options.signal,
-            (retryAttempt, nextRetryDelayMs) =>
-              options.onProgress?.({
-                currentChunk: completed,
-                totalChunks: chunks.length,
-                percent: chunks.length === 0 ? 100 : Math.round((completed / chunks.length) * 100),
-                chunkIndex: index,
-                originalTextRange: input.originalTextRange,
-                status: "synthesizing",
-                durationMs: Date.now() - startedAt,
-                retryAttempt,
-                nextRetryDelayMs,
-                isRetrying: true,
-              }),
-          );
+          const chunkTimeout = options.timeouts?.chunkWithRetriesMs ?? options.timeouts?.perChunkMs;
+          const chunkScope =
+            chunkTimeout !== undefined || jobScope
+              ? createSafeAbortScope(jobScope?.signal ?? options.signal, chunkTimeout ?? options.timeoutMs)
+              : undefined;
+          const chunkSignal = chunkScope?.signal ?? options.signal;
+          let result: SsmlSynthesisResult;
+          try {
+            result = await retryableSynthesis(
+              () =>
+                client.synthesizeSsml(input.ssml, {
+                  outputFormat: options.outputFormat,
+                  signal: chunkSignal,
+                  timeoutMs: options.timeouts?.perChunkMs ?? options.timeoutMs,
+                  sourceNodePath: input.sourceNodePath ?? options.sourceNodePath,
+                }),
+              options.retryOptions,
+              chunkSignal,
+              (retryAttempt, nextRetryDelayMs) =>
+                options.onProgress?.({
+                  currentChunk: completed,
+                  totalChunks: chunks.length,
+                  percent: chunks.length === 0 ? 100 : Math.round((completed / chunks.length) * 100),
+                  chunkIndex: index,
+                  originalTextRange: input.originalTextRange,
+                  status: "synthesizing",
+                  durationMs: Date.now() - startedAt,
+                  retryAttempt,
+                  nextRetryDelayMs,
+                  isRetrying: true,
+                }),
+            );
+          } catch (error) {
+            if (chunkScope?.timedOut())
+              throw new Error(`Speech synthesis timed out after ${chunkTimeout ?? options.timeoutMs} ms.`);
+            throw error;
+          } finally {
+            chunkScope?.dispose();
+          }
           results[index] = {
             ...result,
             ...(input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {}),
@@ -408,6 +558,7 @@ export async function synthesizeSsmlChunksSafe(
             durationMs: Date.now() - startedAt,
           });
         } catch (error) {
+          failedIndices.add(index);
           options.onProgress?.({
             currentChunk: completed,
             totalChunks: chunks.length,
@@ -418,24 +569,42 @@ export async function synthesizeSsmlChunksSafe(
             durationMs: Date.now() - startedAt,
             error,
           });
-          throw error;
+          if (options.cancelOnFailure !== false) jobScope?.abort();
+          firstError ??= error;
+          return;
         }
       }
     };
     await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    if (failedIndices.size > 0) {
+      const error = firstError ?? new Error("One or more SSML chunks failed to synthesize.");
+      (error as { partialResult?: PartialChunkSynthesisResult }).partialResult = {
+        synthesizedChunks: results.flatMap((result, chunkIndex) => (result ? [{ ...result, chunkIndex }] : [])),
+        completedChunks: results.flatMap((result, chunkIndex) => (result ? [{ ...result, chunkIndex }] : [])),
+        pendingChunkIndices: chunks.flatMap((_chunk, chunkIndex) => (results[chunkIndex] ? [] : [chunkIndex])),
+        failedChunkIndices: [...failedIndices],
+        totalChunks: chunks.length,
+      };
+      throw error;
+    }
     const orderedResults = results.filter((result): result is SsmlSynthesisResult => result !== undefined);
     return {
       ok: true,
       success: true,
       status: "success",
-      value: mergeSynthesisResults(orderedResults, {
+      value: await mergeSynthesisResults(orderedResults, {
         format: (options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3") as AzureTtsOutputFormat,
-        signal: options.signal,
+        signal: jobScope?.signal ?? options.signal,
+        customMerger: options.customMerger,
+        outputMimeType: options.outputMimeType,
+        postMergeValidator: options.postMergeValidator,
       }),
     };
   } catch (error) {
     const synthesisError = toSynthesisError(error);
-    return failure(synthesisError);
+    return failure(synthesisError, partialResultFrom(error));
+  } finally {
+    fallbackJobScope?.dispose();
   }
 }