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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssml-builder-js/azure-tts-client",
-  "version": "2.17.0",
+  "version": "2.19.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.17.0",
+    "@ssml-builder-js/ssml-core": "^2.19.0",
     "microsoft-cognitiveservices-speech-sdk": "1.51.0"
   }
 }

package/src/client.ts

@@ -19,16 +19,45 @@ export class AzureTtsClient {
   }
 
   async synthesize(ssml: string): Promise<ArrayBuffer> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion,
+    } = 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, timeouts };
+    const config = {
+      endpoint,
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      retryOptions: this.#options.retryOptions,
+      customHeaders,
+      fingerprintSchemaVersion,
+    };
     return synthesizeSpeech(ssml, config);
   }
 
   async synthesizeSsml(ssml: string, options: Partial<TtsConfig> = {}): Promise<SsmlSynthesisResult> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion,
+    } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     this.#options.logger?.debug?.("Using Azure TTS endpoint:", endpoint);
 
@@ -43,6 +72,14 @@ export class AzureTtsClient {
       sourceNodePath: options.sourceNodePath,
       sourceTextSegments: options.sourceTextSegments,
       sourceMarkers: options.sourceMarkers,
+      retryOptions: options.retryOptions ?? this.#options.retryOptions,
+      cancelOnFailure: options.cancelOnFailure ?? this.#options.cancelOnFailure,
+      customMerger: options.customMerger ?? this.#options.customMerger,
+      outputMimeType: options.outputMimeType ?? this.#options.outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? this.#options.postMergeValidator,
+      resumeValidation: options.resumeValidation ?? this.#options.resumeValidation,
+      customHeaders: options.customHeaders ?? customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? fingerprintSchemaVersion,
     });
   }
 
@@ -50,7 +87,16 @@ export class AzureTtsClient {
     chunks: readonly (SsmlSynthesisChunk | string)[],
     options: SynthesizeChunksOptions = {},
   ): Promise<SsmlSynthesisResult> {
-    const { region, subscriptionKey, outputFormat, signal, timeoutMs, timeouts } = this.#options;
+    const {
+      region,
+      subscriptionKey,
+      outputFormat,
+      signal,
+      timeoutMs,
+      timeouts,
+      customHeaders,
+      fingerprintSchemaVersion,
+    } = this.#options;
     const endpoint = this.#options.endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     return synthesizeSsmlChunks(chunks, {
       endpoint,
@@ -64,12 +110,15 @@ export class AzureTtsClient {
       onProgress: options.onProgress ?? this.#options.onProgress,
       concurrency: options.concurrency ?? this.#options.concurrency,
       retryOptions: options.retryOptions ?? this.#options.retryOptions,
-      cancelOnFailure: options.cancelOnFailure,
+      cancelOnFailure: options.cancelOnFailure ?? this.#options.cancelOnFailure,
       resumeChunks: options.resumeChunks,
       resumeChunkIndices: options.resumeChunkIndices,
-      customMerger: options.customMerger,
-      outputMimeType: options.outputMimeType,
-      postMergeValidator: options.postMergeValidator,
+      customMerger: options.customMerger ?? this.#options.customMerger,
+      outputMimeType: options.outputMimeType ?? this.#options.outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? this.#options.postMergeValidator,
+      resumeValidation: options.resumeValidation ?? this.#options.resumeValidation,
+      customHeaders: options.customHeaders ?? customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? fingerprintSchemaVersion,
     });
   }
 
@@ -90,6 +139,13 @@ export class AzureTtsClient {
       onProgress: options.onProgress ?? this.#options.onProgress,
       concurrency: options.concurrency ?? this.#options.concurrency,
       retryOptions: options.retryOptions ?? this.#options.retryOptions,
+      cancelOnFailure: options.cancelOnFailure ?? this.#options.cancelOnFailure,
+      customMerger: options.customMerger ?? this.#options.customMerger,
+      outputMimeType: options.outputMimeType ?? this.#options.outputMimeType,
+      postMergeValidator: options.postMergeValidator ?? this.#options.postMergeValidator,
+      resumeValidation: options.resumeValidation ?? this.#options.resumeValidation,
+      customHeaders: options.customHeaders ?? this.#options.customHeaders,
+      fingerprintSchemaVersion: options.fingerprintSchemaVersion ?? this.#options.fingerprintSchemaVersion,
     });
   }
 

package/src/deadline.ts

@@ -0,0 +1,52 @@
+import { SynthesisTimeoutError } from "./errors.ts";
+
+/** Coordinates one absolute deadline across validation, synthesis, retries, and merging. */
+export class DeadlineController {
+  readonly deadlineAtMs: number | undefined;
+  readonly signal: AbortSignal;
+  readonly #controller = new AbortController();
+  readonly #parent?: AbortSignal;
+  readonly #onParentAbort: () => void;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+  #timedOut = false;
+
+  constructor(totalJobMs: number | undefined, parent?: AbortSignal) {
+    this.#parent = parent;
+    this.#onParentAbort = () => this.#controller.abort();
+    this.deadlineAtMs = totalJobMs !== undefined && totalJobMs > 0 ? Date.now() + totalJobMs : undefined;
+    this.signal = this.deadlineAtMs === undefined && parent ? parent : this.#controller.signal;
+    if (parent?.aborted) this.#controller.abort();
+    parent?.addEventListener("abort", this.#onParentAbort, { once: true });
+    if (this.deadlineAtMs !== undefined) {
+      this.#timer = setTimeout(
+        () => {
+          this.#timedOut = true;
+          this.#controller.abort();
+        },
+        Math.max(0, this.deadlineAtMs - Date.now()),
+      );
+    }
+  }
+
+  get timedOut(): boolean {
+    return this.#timedOut || (this.deadlineAtMs !== undefined && this.remainingMs <= 0);
+  }
+
+  get remainingMs(): number {
+    return this.deadlineAtMs === undefined ? Number.POSITIVE_INFINITY : Math.max(0, this.deadlineAtMs - Date.now());
+  }
+
+  throwIfExpired(): void {
+    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(): void {
+    this.#controller.abort();
+  }
+
+  dispose(): void {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#parent?.removeEventListener("abort", this.#onParentAbort);
+  }
+}

package/src/errors.ts

@@ -5,7 +5,29 @@ export type SynthesisErrorKind =
   | "audio-format-mismatch"
   | "unsupported-format-error"
   | "cancelled"
-  | "timeout";
+  | "timeout"
+  | "incomplete-chunk-set";
+
+export type SerializedChunkErrorCode =
+  | "VALIDATION_ERROR"
+  | "AZURE_API_ERROR"
+  | "TIMEOUT"
+  | "CANCELLED"
+  | "MERGE_ERROR"
+  | "FORMAT_MISMATCH";
+
+export interface SerializedChunkError {
+  code: SerializedChunkErrorCode;
+  phase: "url-validation" | "synthesis" | "merge";
+  message: string;
+  isOriginalFailure: boolean;
+  isRetryable: boolean;
+  httpStatus?: number;
+  details?: Record<string, unknown>;
+}
+
+/** Backward-compatible name used by persisted execution-state consumers. */
+export type SerializedExecutionError = SerializedChunkError;
 
 export class AzureTtsError extends Error {
   readonly kind = "azure-api-error" as const;
@@ -95,6 +117,19 @@ export class SynthesisTimeoutError extends Error {
   }
 }
 
+export class IncompleteChunkSetError extends Error {
+  readonly kind = "incomplete-chunk-set" as const;
+  readonly totalChunks: number;
+  readonly missingChunkIndices: readonly number[];
+
+  constructor(totalChunks: number, missingChunkIndices: readonly number[]) {
+    super(`Cannot merge an incomplete chunk set; missing chunk indices: ${missingChunkIndices.join(", ")}.`);
+    this.name = "IncompleteChunkSetError";
+    this.totalChunks = totalChunks;
+    this.missingChunkIndices = [...missingChunkIndices];
+  }
+}
+
 export class MergeError extends Error {
   readonly kind = "merge-error" as const;
   readonly cause: unknown;
@@ -136,7 +171,52 @@ export type AzureTtsSynthesisError =
   | AudioFormatMismatchError
   | UnsupportedMergeFormatError
   | SynthesisCancelledError
-  | SynthesisTimeoutError;
+  | SynthesisTimeoutError
+  | IncompleteChunkSetError;
+
+export function serializeChunkError(
+  error: unknown,
+  phase: SerializedChunkError["phase"],
+  isOriginalFailure: boolean,
+): SerializedChunkError {
+  const message = error instanceof Error ? error.message : String(error);
+  const status = error instanceof AzureTtsError ? error.status : undefined;
+  const kind = error && typeof error === "object" && "kind" in error ? String(error.kind) : "";
+  const code: SerializedChunkErrorCode =
+    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: Record<string, unknown> = {};
+  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 !== undefined && status >= 500) ||
+        /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message)),
+    ...(status !== undefined && status > 0 ? { httpStatus: status } : {}),
+    ...(Object.keys(details).length > 0 ? { details } : {}),
+  };
+}
 
 export function toSynthesisError(
   error: unknown,
@@ -146,14 +226,16 @@ export function toSynthesisError(
   | AudioFormatMismatchError
   | UnsupportedMergeFormatError
   | SynthesisCancelledError
-  | SynthesisTimeoutError {
+  | SynthesisTimeoutError
+  | IncompleteChunkSetError {
   if (
     error instanceof AzureTtsError ||
     error instanceof MergeError ||
     error instanceof AudioFormatMismatchError ||
     error instanceof UnsupportedMergeFormatError ||
     error instanceof SynthesisCancelledError ||
-    error instanceof SynthesisTimeoutError
+    error instanceof SynthesisTimeoutError ||
+    error instanceof IncompleteChunkSetError
   )
     return error;
   const message = error instanceof Error ? error.message : String(error);

package/src/index.ts

@@ -21,6 +21,9 @@ export type {
   SynthesizedChunk,
   PartialChunkSynthesisResult,
   PartialSynthesisResult,
+  ChunkExecutionState,
+  ChunkExecutionStatus,
+  ResumeValidationMode,
   CustomMergerContext,
   CustomAudioMerger,
   PostMergeValidator,
@@ -33,10 +36,19 @@ export {
   MergeError,
   SynthesisCancelledError,
   SynthesisTimeoutError,
+  IncompleteChunkSetError,
+  serializeChunkError,
   UnsupportedMergeFormatError,
   getRetryAfterDelayMs,
 } from "./errors.ts";
-export type { AzureTtsSynthesisError, SynthesisErrorKind } from "./errors.ts";
+export type {
+  AzureTtsSynthesisError,
+  SerializedChunkError,
+  SerializedChunkErrorCode,
+  SerializedExecutionError,
+  SynthesisErrorKind,
+} from "./errors.ts";
+export { DeadlineController } from "./deadline.ts";
 export { AzureTtsClient } from "./client.ts";
 export { synthesizeSpeech } from "./synthesis.ts";
 export { synthesizeSsml } from "./synthesis.ts";
@@ -47,9 +59,11 @@ export {
   inspectAudioSpecification,
   resolveMergeAudioFormat,
   synthesizeSsmlChunks,
+  computeChunkFingerprint,
 } from "./synthesis.ts";
 export type {
   InputAudioSpecs,
+  ChunkFingerprintOptions,
   MergeAudioFormat,
   MergeAudioOptions,
   MergeSynthesisOptions,

package/src/outputFormats.ts

@@ -49,6 +49,9 @@ export type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
 export function resolveMimeType(outputFormat: string): string {
   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";