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

package/src/types.ts

@@ -1,9 +1,12 @@
 import type { SsmlSourceMarker, SsmlSourceTextSegment, SsmlTextRange } from "@ssml-builder-js/ssml-core";
 import type { AzureTtsOutputFormat } from "./outputFormats.ts";
+import type { AzureTtsError } from "./errors.ts";
+import type { SsmlValidationError } from "./safe.ts";
 
 export interface TtsConfig {
   signal?: AbortSignal;
   timeoutMs?: number;
+  timeouts?: SynthesisTimeouts;
   endpoint?: string;
   subscriptionKey: string;
   region: string;
@@ -20,6 +23,13 @@ export interface TtsConfig {
   sourceMarkers?: SsmlSourceMarker[];
   concurrency?: number;
   retryOptions?: RetryOptions;
+  cancelOnFailure?: boolean;
+  resumeChunks?: readonly SynthesizedChunk[];
+  resumeChunkIndices?: readonly number[];
+  customMerger?: CustomAudioMerger;
+  outputMimeType?: string;
+  postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
 }
 
 export type MappingStatus = "exact" | "fallback" | "unmapped";
@@ -27,17 +37,30 @@ export type MappingStatus = "exact" | "fallback" | "unmapped";
 export interface AudioSpecification {
   format: string;
   mimeType: string;
-  codec: "pcm" | "mp3" | "opus" | "silk" | "unknown";
+  codec: "pcm" | "mulaw" | "alaw" | "siren" | "mp3" | "opus" | "silk" | "unknown";
   sampleRate: number;
   channels: number;
   bitrate?: number;
+  bitDepth?: number;
+  container?: string;
+  isVbr?: boolean;
   isCompressed: boolean;
 }
 
+export type ResumeValidationMode = "strict" | "disabled";
+
+export interface SynthesisTimeouts {
+  urlValidationMs?: number;
+  perChunkMs?: number;
+  chunkWithRetriesMs?: number;
+  totalJobMs?: number;
+}
+
 export interface RetryOptions {
   maxRetries: number;
   initialDelayMs: number;
   maxDelayMs: number;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
 }
 
 export type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
@@ -120,11 +143,66 @@ export interface SynthesizeChunksOptions {
   outputFormat?: AzureTtsOutputFormat | string;
   signal?: AbortSignal;
   timeoutMs?: number;
+  timeouts?: SynthesisTimeouts;
   sourceNodePath?: string[];
   concurrency?: number;
   retryOptions?: RetryOptions;
+  cancelOnFailure?: boolean;
+  resumeChunks?: readonly SynthesizedChunk[];
+  resumeChunkIndices?: readonly number[];
+  customMerger?: CustomAudioMerger;
+  outputMimeType?: string;
+  postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
+}
+
+export interface CustomMergerContext {
+  format: string;
+  outputMimeType: string;
+  inputSpecs: readonly AudioSpecification[];
+  signal: AbortSignal;
 }
 
+export type CustomAudioMerger = (
+  buffers: ArrayBuffer[],
+  context: CustomMergerContext,
+) => Promise<ArrayBuffer> | ArrayBuffer;
+
+export type PostMergeValidator = (
+  result: MergedSynthesisResult,
+  context: CustomMergerContext,
+) => boolean | undefined | Promise<boolean | undefined>;
+
+export interface SynthesizedChunk extends SsmlSynthesisResult {
+  chunkIndex: number;
+  /** Fingerprint of the SSML and synthesis settings used to create this chunk. */
+  fingerprint: string;
+}
+
+export type ChunkExecutionStatus = "succeeded" | "failed" | "cancelled" | "pending";
+
+export interface ChunkExecutionState {
+  chunkIndex: number;
+  status: ChunkExecutionStatus;
+  error?: AzureTtsError | SsmlValidationError;
+  isOriginalFailure?: boolean;
+  canResume: boolean;
+  result?: SsmlSynthesisResult;
+}
+
+export interface PartialChunkSynthesisResult {
+  synthesizedChunks: readonly SynthesizedChunk[];
+  completedChunks: readonly SynthesizedChunk[];
+  pendingChunkIndices: readonly number[];
+  failedChunkIndices: readonly number[];
+  cancelledChunkIndices: readonly number[];
+  chunkStates: readonly ChunkExecutionState[];
+  totalChunks: number;
+}
+
+/** Alias for applications that use the shorter result name. */
+export type PartialSynthesisResult = PartialChunkSynthesisResult;
+
 export interface SynthesisProgressEvent {
   /** 1-based completed chunk count retained for backward compatibility. */
   currentChunk: number;
@@ -150,6 +228,7 @@ export interface AzureTtsLogger {
 export interface AzureTtsClientOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
+  timeouts?: SynthesisTimeouts;
   subscriptionKey: string;
   region: string;
   endpoint?: string;
@@ -158,4 +237,9 @@ export interface AzureTtsClientOptions {
   onProgress?: (event: SynthesisProgressEvent) => void;
   concurrency?: number;
   retryOptions?: RetryOptions;
+  cancelOnFailure?: boolean;
+  customMerger?: CustomAudioMerger;
+  outputMimeType?: string;
+  postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
 }

package/src/voiceCatalog.ts

@@ -22,6 +22,8 @@ export interface FetchedAzureVoiceCatalogMetadata {
   generatedAt: string;
   apiVersion: string;
   regions: readonly string[];
+  expiresAt?: string;
+  regionDiffs?: Readonly<Record<string, readonly string[]>>;
 }
 
 export interface AzureVoiceCatalog {
@@ -130,6 +132,8 @@ export async function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOpti
       generatedAt: new Date().toISOString(),
       apiVersion: AZURE_VOICE_API_VERSION,
       regions,
+      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+      regionDiffs: {},
     },
   };
 }

package/test/v217-pipeline.test.ts

@@ -0,0 +1,125 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  AzureTtsError,
+  BatchChunkValidationError,
+  getRetryAfterDelayMs,
+  synthesizeSsmlChunksSafe,
+} from "../src/index.ts";
+
+const validSsml = (text: string) =>
+  `<speak version="1.0" xml:lang="en-US"><voice name="en-US-JennyNeural">${text}</voice></speak>`;
+
+test("aggregates every invalid chunk and every diagnostic before synthesis", async () => {
+  let calls = 0;
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async () => {
+        calls += 1;
+        return { audioData: new ArrayBuffer(0), durationMs: 0 };
+      },
+    },
+    ["<speak>", "<speak>", validSsml("ok")],
+  );
+
+  assert.equal(result.ok, false);
+  assert.equal(calls, 0);
+  if (!result.ok) {
+    assert.ok(result.error instanceof BatchChunkValidationError);
+    assert.deepEqual(
+      result.error.chunkDiagnostics.map(({ chunkIndex }) => chunkIndex),
+      [0, 1],
+    );
+    assert.equal(result.error.totalErrorCount, 2);
+  }
+});
+
+test("custom merger and post-merge validation are part of safe chunk synthesis", async () => {
+  let validated = false;
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async (ssml) => ({
+        audioData: Uint8Array.of(ssml.includes("one") ? 1 : 2).buffer,
+        durationMs: 10,
+      }),
+    },
+    [validSsml("one"), validSsml("two")],
+    {
+      concurrency: 2,
+      outputMimeType: "audio/custom",
+      customMerger: (buffers) => {
+        const output = new Uint8Array(buffers.reduce((total, buffer) => total + buffer.byteLength, 0));
+        let offset = 0;
+        for (const buffer of buffers) {
+          output.set(new Uint8Array(buffer), offset);
+          offset += buffer.byteLength;
+        }
+        return output.buffer;
+      },
+      postMergeValidator: (merged) => {
+        validated = merged.mimeType === "audio/custom";
+      },
+    },
+  );
+
+  assert.equal(result.ok, true);
+  assert.equal(validated, true);
+  if (result.ok) assert.equal(result.value.mimeType, "audio/custom");
+});
+
+test("cancels remaining work and resumes from the partial chunk cache", async () => {
+  let calls = 0;
+  let failFirstAttempt = true;
+  const client = {
+    synthesizeSsml: async (ssml: string, options?: { signal?: AbortSignal }) => {
+      calls += 1;
+      if (ssml.includes("fail") && failFirstAttempt) {
+        failFirstAttempt = false;
+        throw new AzureTtsError(503, "Unavailable", "", null);
+      }
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(resolve, ssml.includes("one") ? 1 : 50);
+        options?.signal?.addEventListener(
+          "abort",
+          () => {
+            clearTimeout(timer);
+            reject(new Error("aborted"));
+          },
+          { once: true },
+        );
+      });
+      return { audioData: Uint8Array.of(calls).buffer, durationMs: 10 };
+    },
+  };
+  const chunks = [validSsml("one"), validSsml("fail"), validSsml("three")];
+  const first = await synthesizeSsmlChunksSafe(client, chunks, { concurrency: 2 });
+  assert.equal(first.ok, false);
+  assert.ok(first.partialResult);
+  if (!first.ok && first.partialResult) {
+    const resumed = await synthesizeSsmlChunksSafe(client, chunks, {
+      concurrency: 2,
+      resumeChunks: first.partialResult.synthesizedChunks,
+      resumeChunkIndices: first.partialResult.pendingChunkIndices,
+    });
+    assert.equal(resumed.ok, true);
+  }
+  assert.ok(calls < 6);
+});
+
+test("prioritizes Retry-After and supports structured per-chunk timeouts", async () => {
+  const retryAfter = new AzureTtsError(429, "Too Many Requests", "", null, { "retry-after": "2" });
+  assert.equal(getRetryAfterDelayMs(retryAfter), 2_000);
+
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async (_ssml, options) =>
+        new Promise((_resolve, reject) =>
+          options?.signal?.addEventListener("abort", () => reject(new Error("aborted")), { once: true }),
+        ),
+    },
+    [validSsml("slow")],
+    { timeouts: { perChunkMs: 5 } },
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) assert.equal(result.error.kind, "timeout");
+});

package/test/v218-pipeline.test.ts

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AzureTtsError, inspectAudioSpecification, synthesizeSsmlChunksSafe } from "../src/index.ts";
+
+const validSsml = (text: string) =>
+  `<speak version="1.0" xml:lang="en-US"><voice name="en-US-JennyNeural"><prosody rate="+5%" pitch="+2st">${text}</prosody></voice></speak>`;
+
+test("invalidates a resume chunk when its SSML fingerprint changes", async () => {
+  let calls = 0;
+  let failSecondChunk = true;
+  const client = {
+    synthesizeSsml: async (ssml: string) => {
+      calls += 1;
+      if (ssml.includes("two") && failSecondChunk) {
+        failSecondChunk = false;
+        throw new Error("temporary failure");
+      }
+      return { audioData: Uint8Array.of(calls).buffer, durationMs: 1 };
+    },
+  };
+  const first = await synthesizeSsmlChunksSafe(client, [validSsml("one"), validSsml("two")], {
+    concurrency: 1,
+  });
+  assert.equal(first.ok, false);
+  assert.ok(first.partialResult);
+  if (first.ok || !first.partialResult) return;
+
+  const resumed = await synthesizeSsmlChunksSafe(client, [validSsml("changed"), validSsml("two")], {
+    concurrency: 1,
+    resumeChunks: first.partialResult.synthesizedChunks,
+    resumeChunkIndices: first.partialResult.pendingChunkIndices,
+  });
+  assert.equal(resumed.ok, true);
+  assert.equal(calls, 4);
+  assert.match(first.partialResult.synthesizedChunks[0]?.fingerprint ?? "", /^fnv1a64-/);
+});
+
+test("separates the original failure from chained cancellations", async () => {
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async () => {
+        throw new Error("direct failure");
+      },
+    },
+    [validSsml("fail"), validSsml("cancelled")],
+    { concurrency: 1 },
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.deepEqual(result.partialResult?.failedChunkIndices, [0]);
+    assert.deepEqual(result.partialResult?.cancelledChunkIndices, [1]);
+    assert.equal(result.partialResult?.chunkStates[0]?.status, "failed");
+    assert.equal(result.partialResult?.chunkStates[0]?.isOriginalFailure, true);
+    assert.equal(result.partialResult?.chunkStates[1]?.status, "cancelled");
+    assert.equal(result.partialResult?.chunkStates[1]?.isOriginalFailure, false);
+  }
+});
+
+test("does not wait for Retry-After beyond the retry budget", async () => {
+  let calls = 0;
+  const startedAt = Date.now();
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async () => {
+        calls += 1;
+        throw new AzureTtsError(429, "Too Many Requests", "", null, { "retry-after": "10" });
+      },
+    },
+    [validSsml("retry")],
+    { retryOptions: { maxRetries: 2, initialDelayMs: 1, maxDelayMs: 5 } },
+  );
+  assert.equal(result.ok, false);
+  assert.equal(calls, 1);
+  assert.ok(Date.now() - startedAt < 100);
+  if (!result.ok) assert.equal(result.error.kind, "timeout");
+});
+
+test("maps headerless RAW formats to strict codec specifications", () => {
+  const mulaw = inspectAudioSpecification(new ArrayBuffer(8), "raw-8khz-8bit-mono-mulaw");
+  assert.deepEqual(
+    {
+      sampleRate: mulaw.sampleRate,
+      channels: mulaw.channels,
+      bitDepth: mulaw.bitDepth,
+      codec: mulaw.codec,
+      mimeType: mulaw.mimeType,
+    },
+    { sampleRate: 8_000, channels: 1, bitDepth: 8, codec: "mulaw", mimeType: "audio/basic" },
+  );
+  assert.throws(() => inspectAudioSpecification(new ArrayBuffer(1), "raw-16khz-16bit-mono-pcm"));
+});