@ssml-builder-js/azure-tts-client 2.15.0 → 2.17.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,8 +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,
     });
   }
 
@@ -76,7 +86,10 @@ 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

@@ -2,6 +2,7 @@ export type SynthesisErrorKind =
   | "validation-error"
   | "azure-api-error"
   | "merge-error"
+  | "audio-format-mismatch"
   | "unsupported-format-error"
   | "cancelled"
   | "timeout";
@@ -12,17 +13,59 @@ export class AzureTtsError extends Error {
   readonly statusText: string;
   readonly responseBody: string;
   readonly requestId: string | null;
+  readonly retryAfterMs?: number;
 
-  constructor(status: number, statusText: string, responseBody: string, requestId: string | null) {
+  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 {
   readonly errorDetails: string;
 
@@ -63,6 +106,18 @@ export class MergeError extends Error {
   }
 }
 
+/** Thrown when chunk headers describe incompatible audio streams. */
+export class AudioFormatMismatchError extends Error {
+  readonly kind = "audio-format-mismatch" as const;
+  readonly inputSpecs: readonly AudioSpecification[];
+
+  constructor(message: string, inputSpecs: readonly AudioSpecification[] = []) {
+    super(message);
+    this.name = "AudioFormatMismatchError";
+    this.inputSpecs = inputSpecs;
+  }
+}
+
 /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
 export class UnsupportedMergeFormatError extends Error {
   readonly kind = "unsupported-format-error" as const;
@@ -78,16 +133,24 @@ export class UnsupportedMergeFormatError extends Error {
 export type AzureTtsSynthesisError =
   | AzureTtsError
   | MergeError
+  | AudioFormatMismatchError
   | UnsupportedMergeFormatError
   | SynthesisCancelledError
   | SynthesisTimeoutError;
 
 export function toSynthesisError(
   error: unknown,
-): AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError {
+):
+  | AzureTtsError
+  | MergeError
+  | AudioFormatMismatchError
+  | UnsupportedMergeFormatError
+  | SynthesisCancelledError
+  | SynthesisTimeoutError {
   if (
     error instanceof AzureTtsError ||
     error instanceof MergeError ||
+    error instanceof AudioFormatMismatchError ||
     error instanceof UnsupportedMergeFormatError ||
     error instanceof SynthesisCancelledError ||
     error instanceof SynthesisTimeoutError
@@ -103,3 +166,4 @@ export function createSpeechSdkError(error: unknown): AzureTtsSdkError {
   const message = error instanceof Error ? error.message : String(error);
   return new AzureTtsSdkError(message);
 }
+import type { AudioSpecification } from "./types.ts";

package/src/index.ts

@@ -5,6 +5,8 @@
 export type {
   AzureTtsClientOptions,
   AzureTtsLogger,
+  AudioSpecification,
+  MappingStatus,
   MergedSynthesisResult,
   SsmlSynthesisBookmark,
   SsmlSynthesisBoundary,
@@ -14,15 +16,25 @@ export type {
   SynthesisProgressEvent,
   SynthesizeChunksOptions,
   SynthesisChunkStatus,
+  RetryOptions,
+  SynthesisTimeouts,
+  SynthesizedChunk,
+  PartialChunkSynthesisResult,
+  PartialSynthesisResult,
+  CustomMergerContext,
+  CustomAudioMerger,
+  PostMergeValidator,
   TtsConfig,
 } from "./types.ts";
 export {
   AzureTtsError,
   AzureTtsSdkError,
+  AudioFormatMismatchError,
   MergeError,
   SynthesisCancelledError,
   SynthesisTimeoutError,
   UnsupportedMergeFormatError,
+  getRetryAfterDelayMs,
 } from "./errors.ts";
 export type { AzureTtsSynthesisError, SynthesisErrorKind } from "./errors.ts";
 export { AzureTtsClient } from "./client.ts";
@@ -32,13 +44,24 @@ export {
   canMergeAudioFormat,
   mergeAudioBuffers,
   mergeSynthesisResults,
+  inspectAudioSpecification,
   resolveMergeAudioFormat,
   synthesizeSsmlChunks,
 } from "./synthesis.ts";
-export type { MergeAudioFormat, MergeAudioOptions, MergeSynthesisOptions } from "./synthesis.ts";
+export type {
+  InputAudioSpecs,
+  MergeAudioFormat,
+  MergeAudioOptions,
+  MergeSynthesisOptions,
+} 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,
@@ -51,6 +74,7 @@ export type {
   SsmlSynthesisChunksSafeResult,
   SynthesizeSsmlChunksSafeOptions,
   ValidationErrorResult,
+  ChunkDiagnostics,
 } from "./safe.ts";
 export { fetchAzureVoiceCatalog } from "./voiceCatalog.ts";
 export type {