@ssml-builder-js/azure-tts-client 2.5.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ssml-builder-js/azure-tts-client",
+  "version": "2.5.0",
+  "description": "Azure Text-to-Speech client using the Microsoft Speech SDK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nitta-a/SSML-Builder.git",
+    "directory": "packages/azure-tts-client"
+  },
+  "bugs": {
+    "url": "https://github.com/nitta-a/SSML-Builder/issues"
+  },
+  "homepage": "https://github.com/nitta-a/SSML-Builder#azure-tts-client",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "microsoft-cognitiveservices-speech-sdk": "1.51.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,21 @@
+import { synthesizeSpeech } from "./synthesis.ts";
+import type { AzureTtsClientOptions } from "./types.ts";
+
+const ENDPOINT_TEMPLATE = "https://{region}.tts.speech.microsoft.com/cognitiveservices/v1";
+
+export class AzureTtsClient {
+  readonly #options: AzureTtsClientOptions;
+
+  constructor(options: AzureTtsClientOptions) {
+    this.#options = options;
+  }
+
+  async synthesize(ssml: string): Promise<ArrayBuffer> {
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = 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 };
+    return synthesizeSpeech(ssml, config);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,31 @@
+export class AzureTtsError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  readonly responseBody: string;
+  readonly requestId: string | null;
+
+  constructor(status: number, statusText: string, responseBody: string, requestId: string | null) {
+    super(`Azure TTS request failed: ${status} ${statusText}`);
+    this.name = "AzureTtsError";
+    this.status = status;
+    this.statusText = statusText;
+    this.responseBody = responseBody;
+    this.requestId = requestId;
+  }
+}
+
+export class AzureTtsSdkError extends AzureTtsError {
+  readonly errorDetails: string;
+
+  constructor(errorDetails: string) {
+    super(0, "Speech SDK", errorDetails, null);
+    this.name = "AzureTtsSdkError";
+    this.message = `Azure TTS synthesis failed: ${errorDetails}`;
+    this.errorDetails = errorDetails;
+  }
+}
+
+export function createSpeechSdkError(error: unknown): AzureTtsSdkError {
+  const message = error instanceof Error ? error.message : String(error);
+  return new AzureTtsSdkError(message);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * azure-tts-client: Azure Text-to-Speech client for SSML playback.
+ */
+
+export type { AzureTtsClientOptions, AzureTtsLogger, TtsConfig } from "./types.ts";
+export { AzureTtsError, AzureTtsSdkError } from "./errors.ts";
+export { AzureTtsClient } from "./client.ts";
+export { synthesizeSpeech } from "./synthesis.ts";

package/src/outputFormats.ts

@@ -0,0 +1,54 @@
+import * as SpeechSDK from "microsoft-cognitiveservices-speech-sdk";
+
+export const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
+
+const OUTPUT_FORMATS: Record<string, SpeechSDK.SpeechSynthesisOutputFormat> = {
+  "raw-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoMULaw,
+  "riff-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16KbpsMonoSiren,
+  "audio-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16KbpsMonoSiren,
+  "audio-16khz-32kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3,
+  "audio-16khz-128kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3,
+  "audio-16khz-64kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz64KBitRateMonoMp3,
+  "audio-24khz-48kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3,
+  "audio-24khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz96KBitRateMonoMp3,
+  "audio-24khz-160kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3,
+  "raw-16khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoTrueSilk,
+  "riff-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm,
+  "riff-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz16BitMonoPcm,
+  "riff-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm,
+  "riff-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoMULaw,
+  "raw-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoPcm,
+  "raw-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm,
+  "raw-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz16BitMonoPcm,
+  "ogg-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus,
+  "ogg-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus,
+  "raw-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw48Khz16BitMonoPcm,
+  "riff-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff48Khz16BitMonoPcm,
+  "audio-48khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz96KBitRateMonoMp3,
+  "audio-48khz-192kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz192KBitRateMonoMp3,
+  "ogg-48khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus,
+  "webm-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm16Khz16BitMonoOpus,
+  "webm-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16BitMonoOpus,
+  "webm-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16Bit24KbpsMonoOpus,
+  "raw-24khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoTrueSilk,
+  "raw-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoALaw,
+  "riff-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoALaw,
+  "audio-16khz-16bit-32kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16Bit32KbpsMonoOpus,
+  "audio-24khz-16bit-48kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit48KbpsMonoOpus,
+  "audio-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit24KbpsMonoOpus,
+  "raw-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw22050Hz16BitMonoPcm,
+  "riff-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff22050Hz16BitMonoPcm,
+  "raw-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw44100Hz16BitMonoPcm,
+  "riff-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff44100Hz16BitMonoPcm,
+  "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz,
+  "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps,
+};
+
+export function resolveOutputFormat(outputFormat: string): SpeechSDK.SpeechSynthesisOutputFormat {
+  const resolvedFormat = OUTPUT_FORMATS[outputFormat];
+  if (resolvedFormat === undefined) {
+    throw new Error(`Unsupported Azure Speech output format: ${outputFormat}`);
+  }
+
+  return resolvedFormat;
+}

package/src/speechConfig.ts

@@ -0,0 +1,17 @@
+import { SpeechConfig } from "microsoft-cognitiveservices-speech-sdk";
+import { DEFAULT_OUTPUT_FORMAT, resolveOutputFormat } from "./outputFormats.ts";
+import type { TtsConfig } from "./types.ts";
+
+export function resolveEndpoint(config: TtsConfig): string {
+  const endpoint = config.endpoint?.trim() || "https://{region}.tts.speech.microsoft.com/cognitiveservices/v1";
+  return endpoint.replace(/\{region\}/g, encodeURIComponent(config.region));
+}
+
+export function createSpeechConfig(config: TtsConfig): SpeechConfig {
+  const { outputFormat = DEFAULT_OUTPUT_FORMAT, subscriptionKey } = config;
+
+  const endpoint = new URL(resolveEndpoint(config));
+  const speechConfig = SpeechConfig.fromEndpoint(endpoint, subscriptionKey);
+  speechConfig.speechSynthesisOutputFormat = resolveOutputFormat(outputFormat);
+  return speechConfig;
+}

package/src/synthesis.ts

@@ -0,0 +1,76 @@
+import * as SpeechSDK from "microsoft-cognitiveservices-speech-sdk";
+import { createSpeechSdkError } from "./errors.ts";
+import { createSpeechConfig } from "./speechConfig.ts";
+import type { TtsConfig } from "./types.ts";
+
+function closeSpeechResources(speechConfig: SpeechSDK.SpeechConfig, synthesizer: SpeechSDK.SpeechSynthesizer): void {
+  try {
+    synthesizer.close();
+  } catch {}
+
+  try {
+    speechConfig.close();
+  } catch {}
+}
+
+export async function synthesizeSpeech(ssml: string, config: TtsConfig): Promise<ArrayBuffer> {
+  if (config.signal?.aborted) {
+    throw createSpeechSdkError("Speech synthesis was cancelled.");
+  }
+
+  const speechConfig = createSpeechConfig(config);
+  const synthesizer = new SpeechSDK.SpeechSynthesizer(speechConfig, null);
+
+  return await new Promise<ArrayBuffer>((resolve, reject) => {
+    let resourcesClosed = false;
+    let settled = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let abortHandler: (() => void) | undefined;
+    const cleanup = () => {
+      if (timeout) clearTimeout(timeout);
+      if (abortHandler) config.signal?.removeEventListener("abort", abortHandler);
+    };
+    const closeResources = () => {
+      if (resourcesClosed) return;
+      resourcesClosed = true;
+      closeSpeechResources(speechConfig, synthesizer);
+    };
+    const rejectWithError = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      closeResources();
+      reject(createSpeechSdkError(error));
+    };
+
+    const cb = (result: SpeechSDK.SpeechSynthesisResult) => {
+      if (settled) return;
+      const { reason, errorDetails } = result;
+      if (reason !== SpeechSDK.ResultReason.SynthesizingAudioCompleted) {
+        const err = errorDetails || `Speech synthesis failed with reason ${reason}.`;
+        rejectWithError(err);
+        return;
+      }
+      settled = true;
+      cleanup();
+      closeResources();
+      resolve(result.audioData);
+    };
+
+    try {
+      if (config.signal) {
+        abortHandler = () => rejectWithError("Speech synthesis was cancelled.");
+        config.signal.addEventListener("abort", abortHandler, { once: true });
+      }
+      if (config.timeoutMs !== undefined && config.timeoutMs > 0) {
+        timeout = setTimeout(
+          () => rejectWithError(`Speech synthesis timed out after ${config.timeoutMs} ms.`),
+          config.timeoutMs,
+        );
+      }
+      synthesizer.speakSsmlAsync(ssml, cb, rejectWithError);
+    } catch (error) {
+      rejectWithError(error);
+    }
+  });
+}

package/src/types.ts

@@ -0,0 +1,25 @@
+export interface TtsConfig {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  endpoint?: string;
+  subscriptionKey: string;
+  region: string;
+  outputFormat?: string;
+}
+
+export interface AzureTtsLogger {
+  debug?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+}
+
+export interface AzureTtsClientOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  subscriptionKey: string;
+  region: string;
+  endpoint?: string;
+  outputFormat?: string;
+  logger?: AzureTtsLogger;
+}

package/test/edge-cases.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import test, { type TestContext } from "node:test";
+import * as SpeechSDK from "microsoft-cognitiveservices-speech-sdk";
+import { AzureTtsClient, synthesizeSpeech } from "../src/index.ts";
+
+function installSuccessfulSpeechSdkMock(testContext: TestContext, audio: ArrayBuffer): { endpoint?: URL } {
+  const captured: { endpoint?: URL } = {};
+  const originalFromEndpoint = SpeechSDK.SpeechConfig.fromEndpoint;
+
+  testContext.mock.method(SpeechSDK.SpeechConfig, "fromEndpoint", (endpoint, subscriptionKey) => {
+    captured.endpoint = endpoint;
+    return originalFromEndpoint(endpoint, String(subscriptionKey));
+  });
+  testContext.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "speakSsmlAsync", (_ssml, callback) => {
+    callback?.({
+      audioData: audio,
+      errorDetails: "",
+      reason: SpeechSDK.ResultReason.SynthesizingAudioCompleted,
+    } as SpeechSDK.SpeechSynthesisResult);
+  });
+  testContext.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "close", () => {});
+
+  return captured;
+}
+
+test("synthesizeSpeech replaces every endpoint region placeholder", async (t) => {
+  const audio = new ArrayBuffer(1);
+  const speechSdkMock = installSuccessfulSpeechSdkMock(t, audio);
+
+  const result = await synthesizeSpeech("<speak>Hello</speak>", {
+    endpoint: "https://{region}.example.test/{region}",
+    subscriptionKey: "subscription-key",
+    region: "japan-east",
+  });
+
+  assert.equal(speechSdkMock.endpoint?.href, "https://japan-east.example.test/japan-east");
+  assert.strictEqual(result, audio);
+});
+
+test("synthesizeSpeech URL-encodes special regions in endpoint paths", async (t) => {
+  const audio = new ArrayBuffer(1);
+  const speechSdkMock = installSuccessfulSpeechSdkMock(t, audio);
+
+  await synthesizeSpeech("<speak>Hello</speak>", {
+    endpoint: "https://speech.example.test/{region}/{region}",
+    subscriptionKey: "subscription-key",
+    region: "japan east",
+  });
+
+  assert.equal(speechSdkMock.endpoint?.href, "https://speech.example.test/japan%20east/japan%20east");
+});
+
+test("AzureTtsClient reports Speech SDK callback failures", async (t) => {
+  const errorDetails = "network unavailable";
+  const originalFromEndpoint = SpeechSDK.SpeechConfig.fromEndpoint;
+
+  t.mock.method(SpeechSDK.SpeechConfig, "fromEndpoint", (endpoint, subscriptionKey) =>
+    originalFromEndpoint(endpoint, String(subscriptionKey)),
+  );
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "speakSsmlAsync", (_ssml, _callback, errorCallback) => {
+    errorCallback?.(errorDetails);
+  });
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "close", () => {});
+
+  await assert.rejects(
+    new AzureTtsClient({
+      endpoint: "https://speech.example.test/cognitiveservices/v1",
+      subscriptionKey: "subscription-key",
+      region: "japaneast",
+    }).synthesize("<speak>Hello</speak>"),
+    (error: unknown) => {
+      assert.equal(error instanceof Error ? error.message : error, "Azure TTS synthesis failed: network unavailable");
+      assert.ok(error instanceof Error);
+      assert.equal(error.name, "AzureTtsSdkError");
+      return true;
+    },
+  );
+});
+
+test("synthesizeSpeech aborts a timed-out synthesis and closes resources", async (t) => {
+  const originalFromEndpoint = SpeechSDK.SpeechConfig.fromEndpoint;
+  let closeCount = 0;
+  t.mock.method(SpeechSDK.SpeechConfig, "fromEndpoint", (endpoint, subscriptionKey) =>
+    originalFromEndpoint(endpoint, String(subscriptionKey)),
+  );
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "speakSsmlAsync", () => {});
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "close", () => {
+    closeCount += 1;
+  });
+
+  await assert.rejects(
+    synthesizeSpeech("<speak>Hello</speak>", {
+      endpoint: "https://speech.example.test/cognitiveservices/v1",
+      subscriptionKey: "subscription-key",
+      region: "japaneast",
+      timeoutMs: 10,
+    }),
+    /timed out after 10 ms/,
+  );
+  assert.equal(closeCount, 1);
+});
+
+test("synthesizeSpeech can be cancelled with an AbortSignal", async (t) => {
+  const originalFromEndpoint = SpeechSDK.SpeechConfig.fromEndpoint;
+  const controller = new AbortController();
+  t.mock.method(SpeechSDK.SpeechConfig, "fromEndpoint", (endpoint, subscriptionKey) =>
+    originalFromEndpoint(endpoint, String(subscriptionKey)),
+  );
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "speakSsmlAsync", () => {});
+  t.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "close", () => {});
+
+  const promise = synthesizeSpeech("<speak>Hello</speak>", {
+    endpoint: "https://speech.example.test/cognitiveservices/v1",
+    subscriptionKey: "subscription-key",
+    region: "japaneast",
+    signal: controller.signal,
+  });
+  controller.abort();
+
+  await assert.rejects(promise, /cancelled/);
+});

package/test/errors.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AzureTtsError, AzureTtsSdkError, createSpeechSdkError } from "../src/errors.ts";
+
+test("AzureTtsError exposes HTTP response metadata", () => {
+  const error = new AzureTtsError(401, "Unauthorized", '{"error":"invalid key"}', "request-id");
+
+  assert.ok(error instanceof Error);
+  assert.equal(error.name, "AzureTtsError");
+  assert.equal(error.message, "Azure TTS request failed: 401 Unauthorized");
+  assert.equal(error.status, 401);
+  assert.equal(error.statusText, "Unauthorized");
+  assert.equal(error.responseBody, '{"error":"invalid key"}');
+  assert.equal(error.requestId, "request-id");
+});
+
+test("AzureTtsSdkError preserves SDK error details", () => {
+  const error = new AzureTtsSdkError("The SSML is invalid.");
+
+  assert.ok(error instanceof AzureTtsError);
+  assert.equal(error.name, "AzureTtsSdkError");
+  assert.equal(error.message, "Azure TTS synthesis failed: The SSML is invalid.");
+  assert.equal(error.status, 0);
+  assert.equal(error.statusText, "Speech SDK");
+  assert.equal(error.responseBody, "The SSML is invalid.");
+  assert.equal(error.requestId, null);
+  assert.equal(error.errorDetails, "The SSML is invalid.");
+});
+
+test("createSpeechSdkError normalizes Error and unknown values", () => {
+  assert.equal(
+    createSpeechSdkError(new Error("network unavailable")).message,
+    "Azure TTS synthesis failed: network unavailable",
+  );
+  assert.equal(createSpeechSdkError("request failed").errorDetails, "request failed");
+});

package/test/index.test.ts

@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import test, { type TestContext } from "node:test";
+import * as SpeechSDK from "microsoft-cognitiveservices-speech-sdk";
+import { AzureTtsClient, AzureTtsError, AzureTtsSdkError, synthesizeSpeech } from "../src/index.ts";
+
+type SpeechSdkMock = {
+  endpoint?: URL;
+  subscriptionKey?: string;
+  speechConfig?: SpeechSDK.SpeechConfig;
+  ssml?: string;
+  closeCount: number;
+};
+
+function installSpeechSdkMock(testContext: TestContext, audio: ArrayBuffer): SpeechSdkMock {
+  const captured: SpeechSdkMock = { closeCount: 0 };
+  const originalFromEndpoint = SpeechSDK.SpeechConfig.fromEndpoint;
+
+  testContext.mock.method(SpeechSDK.SpeechConfig, "fromEndpoint", (endpoint, subscriptionKey) => {
+    captured.endpoint = endpoint;
+    captured.subscriptionKey = String(subscriptionKey);
+    const speechConfig = originalFromEndpoint(endpoint, String(subscriptionKey));
+    captured.speechConfig = speechConfig;
+    return speechConfig;
+  });
+  testContext.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "speakSsmlAsync", (ssml, callback) => {
+    captured.ssml = ssml;
+    callback?.({
+      audioData: audio,
+      errorDetails: "",
+      reason: SpeechSDK.ResultReason.SynthesizingAudioCompleted,
+    } as SpeechSDK.SpeechSynthesisResult);
+  });
+  testContext.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "close", () => {
+    captured.closeCount += 1;
+  });
+
+  return captured;
+}
+
+function installSpeechSdkErrorMock(testContext: TestContext, errorDetails: string): SpeechSdkMock {
+  const captured = installSpeechSdkMock(testContext, new ArrayBuffer(0));
+  testContext.mock.method(SpeechSDK.SpeechSynthesizer.prototype, "speakSsmlAsync", (ssml, _callback, errorCallback) => {
+    captured.ssml = ssml;
+    errorCallback?.(errorDetails);
+  });
+  return captured;
+}
+
+test("synthesizeSpeech sends SSML using the Speech SDK", async (t) => {
+  const mockAudio = new ArrayBuffer(3);
+  new Uint8Array(mockAudio).set([4, 5, 6]);
+  const speechSdkMock = installSpeechSdkMock(t, mockAudio);
+  const ssml = "<speak>Hello</speak>";
+
+  const audio = await synthesizeSpeech(ssml, {
+    endpoint: "https://speech.example.test/cognitiveservices/v1",
+    subscriptionKey: "subscription-key",
+    region: "japaneast",
+  });
+
+  assert.equal(speechSdkMock.endpoint?.href, "https://speech.example.test/cognitiveservices/v1");
+  assert.equal(speechSdkMock.subscriptionKey, "subscription-key");
+  assert.equal(speechSdkMock.ssml, ssml);
+  assert.equal(
+    speechSdkMock.speechConfig?.speechSynthesisOutputFormat,
+    SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3,
+  );
+  assert.strictEqual(audio, mockAudio);
+  assert.equal(speechSdkMock.closeCount, 1);
+});
+
+test("synthesize uses the configured output format", async (t) => {
+  const mockAudio = new ArrayBuffer(3);
+  const speechSdkMock = installSpeechSdkMock(t, mockAudio);
+  const ssml = "<speak>Hello</speak>";
+
+  const audio = await new AzureTtsClient({
+    subscriptionKey: "subscription-key",
+    region: "japaneast",
+    outputFormat: "audio-24khz-160kbitrate-mono-mp3",
+  }).synthesize(ssml);
+
+  assert.equal(
+    speechSdkMock.speechConfig?.speechSynthesisOutputFormat,
+    SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3,
+  );
+  assert.strictEqual(audio, mockAudio);
+});
+
+test("synthesize sends SSML to the regional Azure endpoint", async (t) => {
+  const mockAudio = new ArrayBuffer(3);
+  const speechSdkMock = installSpeechSdkMock(t, mockAudio);
+  const ssml = "<speak>Hello</speak>";
+
+  const audio = await new AzureTtsClient({
+    subscriptionKey: "subscription-key",
+    region: "japaneast",
+  }).synthesize(ssml);
+
+  assert.equal(speechSdkMock.endpoint?.href, "https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1");
+  assert.equal(speechSdkMock.ssml, ssml);
+  assert.strictEqual(audio, mockAudio);
+});
+
+test("synthesize falls back when endpoint is an empty string", async (t) => {
+  const mockAudio = new ArrayBuffer(1);
+  const speechSdkMock = installSpeechSdkMock(t, mockAudio);
+
+  await new AzureTtsClient({
+    endpoint: "  ",
+    subscriptionKey: "subscription-key",
+    region: "japaneast",
+  }).synthesize("<speak>Hello</speak>");
+
+  assert.equal(speechSdkMock.endpoint?.href, "https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1");
+});
+
+test("synthesize reports Speech SDK synthesis errors", async (t) => {
+  const errorDetails = "The SSML is invalid.";
+  installSpeechSdkErrorMock(t, errorDetails);
+
+  await assert.rejects(
+    new AzureTtsClient({
+      subscriptionKey: "subscription-key",
+      region: "japaneast",
+    }).synthesize("<speak>Hello</speak>"),
+    (error: unknown) => {
+      assert.ok(error instanceof AzureTtsError);
+      assert.ok(error instanceof AzureTtsSdkError);
+      assert.equal(error.message, "Azure TTS synthesis failed: The SSML is invalid.");
+      assert.equal(error.status, 0);
+      assert.equal(error.statusText, "Speech SDK");
+      assert.equal(error.responseBody, errorDetails);
+      assert.equal(error.requestId, null);
+      assert.equal(error.errorDetails, errorDetails);
+      return true;
+    },
+  );
+});

package/test/output-formats.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import * as SpeechSDK from "microsoft-cognitiveservices-speech-sdk";
+import { DEFAULT_OUTPUT_FORMAT, resolveOutputFormat } from "../src/outputFormats.ts";
+
+test("defines the default Azure Speech output format", () => {
+  assert.equal(DEFAULT_OUTPUT_FORMAT, "audio-16khz-128kbitrate-mono-mp3");
+  assert.equal(
+    resolveOutputFormat(DEFAULT_OUTPUT_FORMAT),
+    SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3,
+  );
+});
+
+test("resolves supported output formats", () => {
+  assert.equal(
+    resolveOutputFormat("audio-16khz-32kbitrate-mono-mp3"),
+    SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3,
+  );
+  assert.equal(
+    resolveOutputFormat("audio-24khz-48kbitrate-mono-mp3"),
+    SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3,
+  );
+  assert.equal(
+    resolveOutputFormat("audio-24khz-160kbitrate-mono-mp3"),
+    SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3,
+  );
+  assert.equal(
+    resolveOutputFormat("ogg-48khz-16bit-mono-opus"),
+    SpeechSDK.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus,
+  );
+});
+
+test("rejects unsupported output formats", () => {
+  assert.throws(
+    () => resolveOutputFormat("unsupported-format"),
+    new Error("Unsupported Azure Speech output format: unsupported-format"),
+  );
+});