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

package/src/voiceCatalog.ts

@@ -10,6 +10,9 @@ export interface AzureVoiceCatalogVoice {
   locale: string;
   secondaryLocales?: readonly string[];
   styles?: readonly string[];
+  supportedTags?: readonly string[];
+  unsupportedTags?: readonly string[];
+  models?: readonly string[];
   regions: readonly string[];
   status?: "ga" | "preview" | "deprecated";
 }
@@ -33,6 +36,9 @@ interface AzureVoiceApiRecord {
   ShortName?: unknown;
   Status?: unknown;
   StyleList?: unknown;
+  SupportedTags?: unknown;
+  UnsupportedTags?: unknown;
+  Models?: unknown;
 }
 
 function stringValue(value: unknown): string | undefined {
@@ -92,6 +98,9 @@ export async function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOpti
       const secondaryLocales = stringList(record.SecondaryLocaleList);
       const styles = stringList(record.StyleList);
       const status = normalizeStatus(record.Status);
+      const supportedTags = stringList(record.SupportedTags);
+      const unsupportedTags = stringList(record.UnsupportedTags);
+      const models = stringList(record.Models);
       const merged: AzureVoiceCatalogVoice = {
         name: existing?.name ?? name,
         locale: existing?.locale ?? locale,
@@ -101,6 +110,12 @@ export async function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOpti
       if (mergedSecondaryLocales.length > 0) merged.secondaryLocales = mergedSecondaryLocales;
       const mergedStyles = [...new Set([...(existing?.styles ?? []), ...styles])];
       if (mergedStyles.length > 0) merged.styles = mergedStyles;
+      const mergedSupportedTags = [...new Set([...(existing?.supportedTags ?? []), ...supportedTags])];
+      if (mergedSupportedTags.length > 0) merged.supportedTags = mergedSupportedTags;
+      const mergedUnsupportedTags = [...new Set([...(existing?.unsupportedTags ?? []), ...unsupportedTags])];
+      if (mergedUnsupportedTags.length > 0) merged.unsupportedTags = mergedUnsupportedTags;
+      const mergedModels = [...new Set([...(existing?.models ?? []), ...models])];
+      if (mergedModels.length > 0) merged.models = mergedModels;
       if (status) merged.status = status;
       else if (existing?.status) merged.status = existing.status;
       voices.set(key, merged);

package/test/synthesis.test.ts

@@ -90,6 +90,70 @@ test("synthesizeSsml returns word boundaries, visemes, bookmarks, and duration",
   assert.equal(result.durationMs, 400);
 });
 
+test("synthesizeSsml maps each synchronization event to its source range and node", async (t) => {
+  const originalFromEndpoint = SpeechSDK.SpeechConfig.fromEndpoint;
+  t.mock.method(SpeechSDK.SpeechConfig, "fromEndpoint", (speechEndpoint, key) =>
+    originalFromEndpoint(speechEndpoint, String(key)),
+  );
+  t.mock.method(
+    SpeechSDK.SpeechSynthesizer.prototype,
+    "speakSsmlAsync",
+    function (this: SpeechSDK.SpeechSynthesizer, _ssml, callback) {
+      this.wordBoundary?.(this, {
+        text: "Hello",
+        textOffset: 7,
+        audioOffset: 0,
+        duration: 100_000,
+      } as SpeechSDK.SpeechSynthesisWordBoundaryEventArgs);
+      this.visemeReceived?.(this, {
+        visemeId: 3,
+        textOffset: 7,
+        audioOffset: 100_000,
+      } as SpeechSDK.SpeechSynthesisVisemeEventArgs);
+      this.bookmarkReached?.(this, {
+        text: "chapter",
+        audioOffset: 200_000,
+      } as SpeechSDK.SpeechSynthesisBookmarkEventArgs);
+      callback?.({
+        audioData: new ArrayBuffer(1),
+        audioDuration: 300_000,
+        errorDetails: "",
+        reason: SpeechSDK.ResultReason.SynthesizingAudioCompleted,
+      } as SpeechSDK.SpeechSynthesisResult);
+    },
+  );
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "close", () => undefined);
+
+  const result = await synthesizeSsml(
+    '<speak version="1.0" xml:lang="en-US"><voice name="en-US-JennyNeural">prefix <prosody rate="slow">Hello</prosody><bookmark mark="chapter"/></voice></speak>',
+    {
+      endpoint,
+      subscriptionKey,
+      region,
+      sourceTextRange: { start: 100, end: 112 },
+      sourceTextSegments: [
+        { text: "prefix ", range: { start: 100, end: 107 }, sourceNodePath: ["speak", "voice[0]"] },
+        { text: "Hello", range: { start: 107, end: 112 }, sourceNodePath: ["speak", "voice[0]", "prosody[1]"] },
+      ],
+      sourceMarkers: [
+        {
+          kind: "bookmark",
+          name: "chapter",
+          originalTextRange: { start: 112, end: 112 },
+          sourceNodePath: ["speak", "voice[0]", "bookmark[2]"],
+        },
+      ],
+    },
+  );
+
+  assert.deepEqual(result.boundaries?.[0]?.originalTextRange, { start: 107, end: 112 });
+  assert.deepEqual(result.boundaries?.[0]?.sourceNodePath, ["speak", "voice[0]", "prosody[1]"]);
+  assert.deepEqual(result.visemes?.[0]?.originalTextRange, { start: 107, end: 107 });
+  assert.deepEqual(result.visemes?.[0]?.sourceNodePath, ["speak", "voice[0]", "prosody[1]"]);
+  assert.deepEqual(result.bookmarks?.[0]?.originalTextRange, { start: 112, end: 112 });
+  assert.deepEqual(result.bookmarks?.[0]?.sourceNodePath, ["speak", "voice[0]", "bookmark[2]"]);
+});
+
 test("synthesizeSpeech aborts the SDK request on timeout and settles its promise", async (t) => {
   let closeCount = 0;
   let resultCallback: ((result: SpeechSDK.SpeechSynthesisResult) => void) | undefined;

package/test/v213-pipeline.test.ts

@@ -5,22 +5,29 @@ import { mergeSynthesisResults, synthesizeSsmlSafe } from "../src/index.ts";
 const audio = (values: number[]): ArrayBuffer => Uint8Array.from(values).buffer;
 
 test("mergeSynthesisResults concatenates audio and offsets synchronization events", () => {
-  const result = mergeSynthesisResults([
-    {
-      audioData: audio([1, 2]),
-      durationMs: 100,
-      boundaries: [{ text: "one", audioOffsetMs: 20, durationMs: 30, textRange: { start: 0, end: 3 }, requestId: "a" }],
-      visemes: [{ visemeId: 1, audioOffsetMs: 40 }],
-      bookmarks: [{ name: "first", audioOffsetMs: 50 }],
-    },
-    {
-      audioData: audio([3, 4, 5]),
-      durationMs: 250,
-      boundaries: [{ text: "two", audioOffsetMs: 10, durationMs: 20, textRange: { start: 3, end: 6 }, requestId: "b" }],
-      visemes: [{ visemeId: 2, audioOffsetMs: 15 }],
-      bookmarks: [{ name: "second", audioOffsetMs: 25 }],
-    },
-  ]);
+  const result = mergeSynthesisResults(
+    [
+      {
+        audioData: audio([1, 2]),
+        durationMs: 100,
+        boundaries: [
+          { text: "one", audioOffsetMs: 20, durationMs: 30, textRange: { start: 0, end: 3 }, requestId: "a" },
+        ],
+        visemes: [{ visemeId: 1, audioOffsetMs: 40 }],
+        bookmarks: [{ name: "first", audioOffsetMs: 50 }],
+      },
+      {
+        audioData: audio([3, 4, 5]),
+        durationMs: 250,
+        boundaries: [
+          { text: "two", audioOffsetMs: 10, durationMs: 20, textRange: { start: 3, end: 6 }, requestId: "b" },
+        ],
+        visemes: [{ visemeId: 2, audioOffsetMs: 15 }],
+        bookmarks: [{ name: "second", audioOffsetMs: 25 }],
+      },
+    ],
+    { format: "audio-16khz-128kbitrate-mono-mp3" },
+  );
 
   assert.deepEqual([...new Uint8Array(result.audioData)], [1, 2, 3, 4, 5]);
   assert.equal(result.durationMs, 350);
@@ -37,6 +44,10 @@ test("mergeSynthesisResults concatenates audio and offsets synchronization event
     [50, 125],
   );
   assert.deepEqual(result.boundaries?.[1]?.textRange, { start: 3, end: 6 });
+  assert.equal(result.boundaries?.[0]?.chunkIndex, 0);
+  assert.equal(result.boundaries?.[1]?.chunkIndex, 1);
+  assert.equal(result.boundaries?.[1]?.chunkAudioOffsetMs, 10);
+  assert.deepEqual(result.boundaries?.[1]?.originalTextRange, { start: 3, end: 6 });
 });
 
 test("synthesizeSsmlSafe blocks invalid SSML without calling the client", async () => {

package/test/v214-pipeline.test.ts

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  ChunkValidationError,
+  UnsupportedMergeFormatError,
+  mergeAudioBuffers,
+  synthesizeSsmlChunksSafe,
+} from "../src/index.ts";
+
+function wav(data: number[], sampleRate = 16_000): ArrayBuffer {
+  const pcm = Uint8Array.from(data);
+  const output = new Uint8Array(44 + pcm.length + (pcm.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, pcm.length, true);
+  output.set(pcm, 44);
+  return output.buffer;
+}
+
+const validSsml = (text: string) =>
+  `<speak version="1.0" xml:lang="en-US"><voice name="en-US-JennyNeural">${text}</voice></speak>`;
+
+test("mergeAudioBuffers rebuilds one valid WAV header", () => {
+  const merged = mergeAudioBuffers([wav([1, 2]), wav([3, 4, 5])], { format: "riff-16khz-16bit-mono-pcm" });
+  const bytes = new Uint8Array(merged);
+  const view = new DataView(merged);
+  assert.equal(new TextDecoder().decode(bytes.slice(0, 4)), "RIFF");
+  assert.equal(new TextDecoder().decode(bytes.slice(8, 12)), "WAVE");
+  assert.equal(view.getUint32(4, true), merged.byteLength - 8);
+  assert.equal(view.getUint32(40, true), 5);
+  assert.deepEqual([...bytes.slice(44, 49)], [1, 2, 3, 4, 5]);
+  assert.equal(bytes[49], 0);
+});
+
+test("mergeAudioBuffers removes per-buffer ID3 tags from MP3 streams", () => {
+  const tag = Uint8Array.from([0x49, 0x44, 0x33, 4, 0, 0, 0, 0, 0, 0]);
+  const first = new Uint8Array(tag.length + 2);
+  first.set(tag);
+  first.set([1, 2], tag.length);
+  const second = new Uint8Array(tag.length + 1);
+  second.set(tag);
+  second[tag.length] = 3;
+  assert.deepEqual(
+    [
+      ...new Uint8Array(
+        mergeAudioBuffers([first.buffer, second.buffer], { format: "audio-16khz-128kbitrate-mono-mp3" }),
+      ),
+    ],
+    [1, 2, 3],
+  );
+});
+
+test("mergeAudioBuffers rejects container formats that require remultiplexing", () => {
+  assert.throws(
+    () => mergeAudioBuffers([new ArrayBuffer(1)], { format: "webm-24khz-16bit-mono-opus" }),
+    (error: unknown) => error instanceof UnsupportedMergeFormatError,
+  );
+});
+
+test("synthesizeSsmlChunksSafe validates all chunks before calling Azure", async () => {
+  let calls = 0;
+  const progress: string[] = [];
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async () => {
+        calls += 1;
+        return { audioData: new ArrayBuffer(0), durationMs: 0 };
+      },
+    },
+    [validSsml("ok"), "<speak>"],
+    { onProgress: (event) => progress.push(`${event.chunkIndex}:${event.status}`) },
+  );
+  assert.equal(result.ok, false);
+  assert.equal(result.status, "validation-error");
+  if (!result.ok) {
+    assert.ok(result.error instanceof ChunkValidationError);
+    assert.equal(result.error.chunkIndex, 1);
+  }
+  assert.equal(calls, 0);
+  assert.deepEqual(progress, ["0:pending", "1:pending", "1:failed"]);
+});
+
+test("synthesizeSsmlChunksSafe reports structured lifecycle progress", async () => {
+  const progress: Array<{ chunkIndex: number; status: string; durationMs: number }> = [];
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async () => ({ audioData: Uint8Array.of(1).buffer, durationMs: 20 }),
+    },
+    [
+      { ssml: validSsml("one"), originalTextRange: { start: 0, end: 3 }, sourceNodePath: ["speak", "voice[0]"] },
+      { ssml: validSsml("two"), originalTextRange: { start: 3, end: 6 }, sourceNodePath: ["speak", "voice[0]"] },
+    ],
+    {
+      onProgress: (event) =>
+        progress.push({ chunkIndex: event.chunkIndex, status: event.status, durationMs: event.durationMs }),
+    },
+  );
+  assert.equal(result.ok, true);
+  assert.deepEqual(
+    progress.map(({ chunkIndex, status }) => `${chunkIndex}:${status}`),
+    ["0:pending", "1:pending", "0:synthesizing", "0:success", "1:synthesizing", "1:success"],
+  );
+  assert.ok(progress.every(({ durationMs }) => durationMs >= 0));
+});

package/test/v215-pipeline.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  AzureTtsError,
+  SynthesisCancelledError,
+  SynthesisTimeoutError,
+  UnsupportedMergeFormatError,
+  mergeSynthesisResults,
+  synthesizeSsmlChunksSafe,
+  synthesizeSsmlSafe,
+} from "../src/index.ts";
+
+const audio = (values: number[]): ArrayBuffer => Uint8Array.from(values).buffer;
+const validSsml = (text: string) =>
+  `<speak version="1.0" xml:lang="en-US"><voice name="en-US-JennyNeural">${text}</voice></speak>`;
+
+test("merge APIs require a format at runtime and expose MIME metadata", async () => {
+  assert.throws(
+    () => mergeSynthesisResults([{ audioData: audio([1]), durationMs: 1 }], undefined as never),
+    (error: unknown) => error instanceof UnsupportedMergeFormatError && error.kind === "unsupported-format-error",
+  );
+  const merged = mergeSynthesisResults([{ audioData: audio([1]), durationMs: 1 }], {
+    format: "webm-24khz-16bit-mono-opus",
+    customMerger: (buffers) => buffers[0] ?? new ArrayBuffer(0),
+  });
+  assert.equal((await merged).mimeType, "audio/webm");
+});
+
+test("safe synthesis returns each discriminated error kind", async () => {
+  const validation = await synthesizeSsmlSafe(
+    { synthesizeSsml: async () => ({ audioData: new ArrayBuffer(0), durationMs: 0 }) },
+    "<speak>",
+  );
+  assert.equal(validation.ok, false);
+  if (!validation.ok) assert.equal(validation.error.kind, "validation-error");
+
+  const azure = await synthesizeSsmlSafe(
+    {
+      synthesizeSsml: async () => {
+        throw new AzureTtsError(429, "Too Many Requests", "{}", "req");
+      },
+    },
+    validSsml("hello"),
+  );
+  assert.equal(azure.ok, false);
+  if (!azure.ok) {
+    assert.equal(azure.error.kind, "azure-api-error");
+    assert.equal(azure.error.status, 429);
+  }
+
+  for (const error of [new SynthesisTimeoutError("timed out"), new SynthesisCancelledError()]) {
+    const result = await synthesizeSsmlChunksSafe(
+      {
+        synthesizeSsml: async () => {
+          throw error;
+        },
+      },
+      [validSsml("hello")],
+      { outputFormat: "audio-16khz-128kbitrate-mono-mp3" },
+    );
+    assert.equal(result.ok, false);
+    if (!result.ok) assert.equal(result.error.kind, error.kind);
+  }
+});
+
+test("chunk safe synthesis propagates output, cancellation, timeout, and source path settings", async () => {
+  const controller = new AbortController();
+  const calls: Array<{ options?: Record<string, unknown> }> = [];
+  let validatorSignal: AbortSignal | undefined;
+  let validatorPath: readonly string[] | undefined;
+  const result = await synthesizeSsmlChunksSafe(
+    {
+      synthesizeSsml: async (_ssml, options) => {
+        calls.push({ options: options as Record<string, unknown> });
+        return { audioData: new ArrayBuffer(0), durationMs: 0 };
+      },
+    },
+    [
+      {
+        ssml: `${validSsml("hello").replace("</voice>", '<audio src="https://example.test/a.mp3"/></voice>')}`,
+        originalTextRange: { start: 10, end: 15 },
+      },
+    ],
+    {
+      allowExternalAudio: true,
+      outputFormat: "audio-16khz-128kbitrate-mono-mp3",
+      signal: controller.signal,
+      timeoutMs: 1234,
+      sourceNodePath: ["speak", "voice[0]"],
+      urlValidator: async (_url, context, signal) => {
+        validatorPath = context.sourceNodePath;
+        validatorSignal = signal;
+        return true;
+      },
+    },
+  );
+  assert.equal(result.ok, true);
+  assert.equal(calls[0]?.options?.outputFormat, "audio-16khz-128kbitrate-mono-mp3");
+  assert.equal(calls[0]?.options?.signal, controller.signal);
+  assert.equal(calls[0]?.options?.timeoutMs, 1234);
+  assert.deepEqual(calls[0]?.options?.sourceNodePath, ["speak", "voice[0]"]);
+  assert.equal(validatorSignal, controller.signal);
+  assert.deepEqual(validatorPath, ["speak", "voice[0]"]);
+});