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

package/src/types.ts

@@ -4,6 +4,7 @@ import type { AzureTtsOutputFormat } from "./outputFormats.ts";
 export interface TtsConfig {
   signal?: AbortSignal;
   timeoutMs?: number;
+  timeouts?: SynthesisTimeouts;
   endpoint?: string;
   subscriptionKey: string;
   region: string;
@@ -18,6 +19,43 @@ export interface TtsConfig {
   /** Exact source text segments used to map individual Azure events. */
   sourceTextSegments?: SsmlSourceTextSegment[];
   sourceMarkers?: SsmlSourceMarker[];
+  concurrency?: number;
+  retryOptions?: RetryOptions;
+  cancelOnFailure?: boolean;
+  resumeChunks?: readonly SynthesizedChunk[];
+  resumeChunkIndices?: readonly number[];
+  customMerger?: CustomAudioMerger;
+  outputMimeType?: string;
+  postMergeValidator?: PostMergeValidator;
+}
+
+export type MappingStatus = "exact" | "fallback" | "unmapped";
+
+export interface AudioSpecification {
+  format: string;
+  mimeType: string;
+  codec: "pcm" | "mp3" | "opus" | "silk" | "unknown";
+  sampleRate: number;
+  channels: number;
+  bitrate?: number;
+  bitDepth?: number;
+  container?: string;
+  isVbr?: boolean;
+  isCompressed: boolean;
+}
+
+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";
@@ -36,6 +74,7 @@ export interface SsmlSynthesisBoundary {
   /** Audio offset within the originating chunk before merge. */
   chunkAudioOffsetMs?: number;
   requestId?: string;
+  mappingStatus: MappingStatus;
 }
 
 export interface SsmlSynthesisViseme {
@@ -47,6 +86,7 @@ export interface SsmlSynthesisViseme {
   originalTextRange?: SsmlTextRange;
   chunkAudioOffsetMs?: number;
   requestId?: string;
+  mappingStatus: MappingStatus;
 }
 
 export interface SsmlSynthesisBookmark {
@@ -58,6 +98,7 @@ export interface SsmlSynthesisBookmark {
   originalTextRange?: SsmlTextRange;
   chunkAudioOffsetMs?: number;
   requestId?: string;
+  mappingStatus: MappingStatus;
 }
 
 /** Audio and Azure Speech synchronization events emitted for one SSML request. */
@@ -77,6 +118,7 @@ export interface SsmlSynthesisResult {
   textRange?: { start: number; end: number };
   /** MIME type of a result produced by an explicit merge operation. */
   mimeType?: string;
+  audioSpec?: AudioSpecification;
 }
 
 export interface MergedSynthesisResult extends SsmlSynthesisResult {
@@ -96,9 +138,50 @@ 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;
+}
+
+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;
+}
+
+export interface PartialChunkSynthesisResult {
+  synthesizedChunks: readonly SynthesizedChunk[];
+  completedChunks: readonly SynthesizedChunk[];
+  pendingChunkIndices: readonly number[];
+  failedChunkIndices: readonly number[];
+  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;
@@ -109,6 +192,9 @@ export interface SynthesisProgressEvent {
   status: SynthesisChunkStatus;
   durationMs: number;
   error?: unknown;
+  retryAttempt?: number;
+  nextRetryDelayMs?: number;
+  isRetrying?: boolean;
 }
 
 export interface AzureTtsLogger {
@@ -121,10 +207,13 @@ export interface AzureTtsLogger {
 export interface AzureTtsClientOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
+  timeouts?: SynthesisTimeouts;
   subscriptionKey: string;
   region: string;
   endpoint?: string;
   outputFormat?: string;
   logger?: AzureTtsLogger;
   onProgress?: (event: SynthesisProgressEvent) => void;
+  concurrency?: number;
+  retryOptions?: RetryOptions;
 }

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/v216-pipeline.test.ts

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  AudioFormatMismatchError,
+  AzureTtsError,
+  mergeAudioBuffers,
+  mergeSynthesisResults,
+  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>`;
+
+function wav(data: number[], sampleRate: number): ArrayBuffer {
+  const output = new Uint8Array(44 + data.length + (data.length & 1));
+  const view = new DataView(output.buffer);
+  output.set(new TextEncoder().encode("RIFF"), 0);
+  output.set(new TextEncoder().encode("WAVEfmt "), 8);
+  view.setUint32(4, output.length - 8, true);
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  output.set(new TextEncoder().encode("data"), 36);
+  view.setUint32(40, data.length, true);
+  output.set(data, 44);
+  return output.buffer;
+}
+
+test("chunk merging rejects incompatible WAV sample rates", () => {
+  assert.throws(
+    () => mergeAudioBuffers([wav([1, 2], 16_000), wav([3, 4], 24_000)], { format: "riff-16khz-16bit-mono-pcm" }),
+    (error: unknown) => error instanceof AudioFormatMismatchError,
+  );
+});
+
+test("safe chunk synthesis retries transient errors and preserves chunk order", async () => {
+  let attempts = 0;
+  let oneAttempts = 0;
+  let active = 0;
+  let maximumActive = 0;
+  const completed: string[] = [];
+  const retryEvents: number[] = [];
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async (ssml) => {
+        attempts += 1;
+        active += 1;
+        maximumActive = Math.max(maximumActive, active);
+        await new Promise((resolve) => setTimeout(resolve, ssml.includes("one") ? 5 : 1));
+        active -= 1;
+        if (ssml.includes("one")) {
+          oneAttempts += 1;
+          if (oneAttempts < 3) throw new AzureTtsError(503, "Unavailable", "", null);
+        }
+        completed.push(ssml.includes("one") ? "one" : "two");
+        return { audioData: Uint8Array.of(ssml.includes("one") ? 1 : 2).buffer, durationMs: 10 };
+      },
+    },
+    [validSsml("one"), validSsml("two")],
+    {
+      concurrency: 2,
+      retryOptions: { maxRetries: 2, initialDelayMs: 0, maxDelayMs: 0 },
+      onProgress: (event) => {
+        if (event.isRetrying && event.retryAttempt) retryEvents.push(event.retryAttempt);
+      },
+    },
+  );
+  assert.equal(result.ok, true);
+  assert.equal(maximumActive, 2);
+  assert.deepEqual(retryEvents, [1, 2]);
+  assert.equal(attempts, 4);
+  if (result.ok) assert.deepEqual([...new Uint8Array(result.value.audioData)], [1, 2]);
+});
+
+test("safe chunk synthesis does not retry permanent HTTP errors", async () => {
+  let calls = 0;
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async () => {
+        calls += 1;
+        throw new AzureTtsError(400, "Bad Request", "", null);
+      },
+    },
+    [validSsml("bad")],
+    { retryOptions: { maxRetries: 3, initialDelayMs: 0, maxDelayMs: 0 } },
+  );
+  assert.equal(result.ok, false);
+  assert.equal(calls, 1);
+});
+
+test("custom mergers receive input specifications and cancellation", async () => {
+  const controller = new AbortController();
+  let received: { format: string; inputSpecs: unknown[]; signal: AbortSignal } | undefined;
+  const result = await mergeSynthesisResults([{ audioData: Uint8Array.of(1).buffer, durationMs: 1 }], {
+    format: "webm-24khz-16bit-mono-opus",
+    signal: controller.signal,
+    customMerger: (buffers, context) => {
+      received = { format: context.format, inputSpecs: context.inputSpecs, signal: context.signal };
+      return buffers[0] ?? new ArrayBuffer(0);
+    },
+  });
+  assert.equal(result.mimeType, "audio/webm");
+  assert.equal(received?.format, "webm-24khz-16bit-mono-opus");
+  assert.equal(received?.inputSpecs.length, 1);
+  assert.equal(received?.signal, controller.signal);
+});

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");
+});