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

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { SsmlSourceMarker, SsmlSourceTextSegment, SsmlTextRange } from "@ssml-builder-js/ssml-core";
 import type { AzureTtsOutputFormat } from "./outputFormats.ts";
+import type { SerializedChunkError } from "./errors.ts";
 
 export interface TtsConfig {
   signal?: AbortSignal;
@@ -9,6 +10,8 @@ export interface TtsConfig {
   subscriptionKey: string;
   region: string;
   outputFormat?: string;
+  customHeaders?: Readonly<Record<string, string>>;
+  fingerprintSchemaVersion?: string;
   /** Original plain-text range represented by this synthesis request. */
   sourceTextRange?: { start: number; end: number };
   /** Reports chunk lifecycle events when using chunk synthesis. */
@@ -27,6 +30,7 @@ export interface TtsConfig {
   customMerger?: CustomAudioMerger;
   outputMimeType?: string;
   postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
 }
 
 export type MappingStatus = "exact" | "fallback" | "unmapped";
@@ -34,7 +38,7 @@ 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;
@@ -44,6 +48,8 @@ export interface AudioSpecification {
   isCompressed: boolean;
 }
 
+export type ResumeValidationMode = "strict" | "disabled";
+
 export interface SynthesisTimeouts {
   urlValidationMs?: number;
   perChunkMs?: number;
@@ -136,6 +142,8 @@ export interface SsmlSynthesisChunk {
 export interface SynthesizeChunksOptions {
   onProgress?: (event: SynthesisProgressEvent) => void;
   outputFormat?: AzureTtsOutputFormat | string;
+  customHeaders?: Readonly<Record<string, string>>;
+  fingerprintSchemaVersion?: string;
   signal?: AbortSignal;
   timeoutMs?: number;
   timeouts?: SynthesisTimeouts;
@@ -148,6 +156,7 @@ export interface SynthesizeChunksOptions {
   customMerger?: CustomAudioMerger;
   outputMimeType?: string;
   postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
 }
 
 export interface CustomMergerContext {
@@ -169,6 +178,19 @@ export type PostMergeValidator = (
 
 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?: SerializedChunkError;
+  isOriginalFailure?: boolean;
+  canResume: boolean;
+  result?: SsmlSynthesisResult;
 }
 
 export interface PartialChunkSynthesisResult {
@@ -176,6 +198,8 @@ export interface PartialChunkSynthesisResult {
   completedChunks: readonly SynthesizedChunk[];
   pendingChunkIndices: readonly number[];
   failedChunkIndices: readonly number[];
+  cancelledChunkIndices: readonly number[];
+  chunkStates: readonly ChunkExecutionState[];
   totalChunks: number;
 }
 
@@ -212,8 +236,15 @@ export interface AzureTtsClientOptions {
   region: string;
   endpoint?: string;
   outputFormat?: string;
+  customHeaders?: Readonly<Record<string, string>>;
+  fingerprintSchemaVersion?: string;
   logger?: AzureTtsLogger;
   onProgress?: (event: SynthesisProgressEvent) => void;
   concurrency?: number;
   retryOptions?: RetryOptions;
+  cancelOnFailure?: boolean;
+  customMerger?: CustomAudioMerger;
+  outputMimeType?: string;
+  postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
 }

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

package/test/v219-pipeline.test.ts

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  IncompleteChunkSetError,
+  inspectAudioSpecification,
+  synthesizeSsmlChunksSafe,
+  synthesizeSsmlSafe,
+  computeChunkFingerprint,
+} 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 ebmlSize(size: number): Uint8Array {
+  if (size < 0x7f) return Uint8Array.of(0x80 | size);
+  if (size < 0x3fff) return Uint8Array.of(0x40 | (size >> 8), size & 0xff);
+  throw new Error("Test fixture is too large.");
+}
+
+function ebmlElement(id: readonly number[], data: Uint8Array): Uint8Array {
+  return Uint8Array.from([...id, ...ebmlSize(data.byteLength), ...data]);
+}
+
+function concatBytes(...parts: Uint8Array[]): Uint8Array {
+  return Uint8Array.from(parts.flatMap((part) => [...part]));
+}
+
+function oggOpus(): ArrayBuffer {
+  const payload = new Uint8Array(19);
+  payload.set(new TextEncoder().encode("OpusHead"));
+  payload[8] = 1;
+  payload[9] = 1;
+  new DataView(payload.buffer).setUint32(12, 16_000, true);
+  const page = new Uint8Array(27 + 1 + payload.byteLength);
+  page.set(new TextEncoder().encode("OggS"));
+  page[26] = 1;
+  page[27] = payload.byteLength;
+  page.set(payload, 28);
+  return page.buffer;
+}
+
+function webmOpus(): ArrayBuffer {
+  const sampling = new ArrayBuffer(8);
+  new DataView(sampling).setFloat64(0, 24_000, false);
+  const audio = ebmlElement(
+    [0xe1],
+    concatBytes(ebmlElement([0xb5], new Uint8Array(sampling)), ebmlElement([0x9f], Uint8Array.of(1))),
+  );
+  const track = ebmlElement(
+    [0xae],
+    Uint8Array.from([
+      ...ebmlElement([0xd7], Uint8Array.of(1)),
+      ...ebmlElement([0x83], Uint8Array.of(2)),
+      ...ebmlElement([0x86], new TextEncoder().encode("A_OPUS")),
+      ...audio,
+    ]),
+  );
+  const tracks = ebmlElement([0x16, 0x54, 0xae, 0x6b], track);
+  const ebml = ebmlElement([0x1a, 0x45, 0xdf, 0xa3], ebmlElement([0x42, 0x82], new TextEncoder().encode("webm")));
+  const segment = ebmlElement([0x18, 0x53, 0x80, 0x67], tracks);
+  return Uint8Array.from([...ebml, ...segment]).buffer;
+}
+
+test("fingerprints include the complete synthesis environment", () => {
+  const base = computeChunkFingerprint(validSsml("hello"), "audio-16khz-128kbitrate-mono-mp3", {
+    region: "eastus",
+    endpoint: "https://eastus.example.test/tts",
+    customHeaders: { "x-tenant": "a" },
+    fingerprintSchemaVersion: "2",
+  });
+  assert.notEqual(
+    base,
+    computeChunkFingerprint(validSsml("hello"), "audio-16khz-128kbitrate-mono-mp3", {
+      region: "japaneast",
+      endpoint: "https://japaneast.example.test/tts",
+      customHeaders: { "x-tenant": "a" },
+      fingerprintSchemaVersion: "2",
+    }),
+  );
+  assert.notEqual(
+    base,
+    computeChunkFingerprint(validSsml("hello"), "audio-16khz-128kbitrate-mono-mp3", {
+      region: "eastus",
+      endpoint: "https://eastus.example.test/tts",
+      customHeaders: { "x-tenant": "b" },
+      fingerprintSchemaVersion: "2",
+    }),
+  );
+});
+
+test("refuses to merge when resumeChunkIndices leave a chunk missing", async () => {
+  const fingerprint = computeChunkFingerprint(validSsml("one"));
+  const result = await synthesizeSsmlChunksSafe(
+    { synthesizeSsml: async () => ({ audioData: Uint8Array.of(1).buffer, durationMs: 1 }) },
+    [validSsml("one"), validSsml("two")],
+    {
+      resumeChunks: [{ chunkIndex: 0, fingerprint, audioData: Uint8Array.of(1).buffer, durationMs: 1 }],
+      resumeChunkIndices: [0],
+    },
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) assert.ok(result.error instanceof IncompleteChunkSetError);
+});
+
+test("applies totalJobMs to one safe synthesis before the client resolves", async () => {
+  const result = await synthesizeSsmlSafe(
+    {
+      synthesizeSsml: async (_ssml, options) =>
+        new Promise((resolve, reject) => {
+          const timer = setTimeout(() => resolve({ audioData: new ArrayBuffer(0), durationMs: 0 }), 100);
+          options?.signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new Error("Speech synthesis was cancelled."));
+          });
+        }),
+    },
+    validSsml("slow"),
+    { timeouts: { totalJobMs: 10 } },
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) assert.equal(result.error.kind, "timeout");
+});
+
+test("validates Ogg and WebM codec headers", () => {
+  assert.equal(inspectAudioSpecification(oggOpus(), "ogg-16khz-16bit-mono-opus").codec, "opus");
+  assert.equal(inspectAudioSpecification(webmOpus(), "webm-24khz-16bit-mono-opus").container, "webm");
+  assert.throws(() =>
+    inspectAudioSpecification(Uint8Array.of(0x4f, 0x67, 0x67, 0x53).buffer, "ogg-16khz-16bit-mono-opus"),
+  );
+  assert.throws(() => inspectAudioSpecification(Uint8Array.of(0x1a, 0x45, 0xdf).buffer, "webm-24khz-16bit-mono-opus"));
+});