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

package/src/index.ts

@@ -5,6 +5,9 @@
 export type {
   AzureTtsClientOptions,
   AzureTtsLogger,
+  AudioSpecification,
+  MappingStatus,
+  MergedSynthesisResult,
   SsmlSynthesisBookmark,
   SsmlSynthesisBoundary,
   SsmlSynthesisResult,
@@ -13,9 +16,19 @@ export type {
   SynthesisProgressEvent,
   SynthesizeChunksOptions,
   SynthesisChunkStatus,
+  RetryOptions,
   TtsConfig,
 } from "./types.ts";
-export { AzureTtsError, AzureTtsSdkError, UnsupportedMergeFormatError } from "./errors.ts";
+export {
+  AzureTtsError,
+  AzureTtsSdkError,
+  AudioFormatMismatchError,
+  MergeError,
+  SynthesisCancelledError,
+  SynthesisTimeoutError,
+  UnsupportedMergeFormatError,
+} from "./errors.ts";
+export type { AzureTtsSynthesisError, SynthesisErrorKind } from "./errors.ts";
 export { AzureTtsClient } from "./client.ts";
 export { synthesizeSpeech } from "./synthesis.ts";
 export { synthesizeSsml } from "./synthesis.ts";
@@ -23,15 +36,25 @@ export {
   canMergeAudioFormat,
   mergeAudioBuffers,
   mergeSynthesisResults,
+  inspectAudioSpecification,
   resolveMergeAudioFormat,
   synthesizeSsmlChunks,
 } from "./synthesis.ts";
-export type { MergeAudioFormat } from "./synthesis.ts";
+export type {
+  CustomMergerContext,
+  InputAudioSpecs,
+  MergeAudioFormat,
+  MergeAudioOptions,
+  MergeSynthesisOptions,
+} from "./synthesis.ts";
+export { DEFAULT_OUTPUT_FORMAT, resolveMimeType } from "./outputFormats.ts";
+export type { AzureTtsOutputFormat } from "./outputFormats.ts";
 export { ChunkValidationError, synthesizeSsmlChunksSafe, synthesizeSsmlSafe } from "./safe.ts";
 export type {
   AzureApiErrorResult,
   Result,
   SsmlSynthesisSafeResult,
+  SsmlSynthesisError,
   SsmlValidationError as AzureSsmlValidationError,
   Success,
   SynthesisResult,

package/src/outputFormats.ts

@@ -2,7 +2,7 @@ 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> = {
+const OUTPUT_FORMATS = {
   "raw-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoMULaw,
   "riff-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16KbpsMonoSiren,
   "audio-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16KbpsMonoSiren,
@@ -42,10 +42,21 @@ const OUTPUT_FORMATS: Record<string, SpeechSDK.SpeechSynthesisOutputFormat> = {
   "riff-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff44100Hz16BitMonoPcm,
   "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz,
   "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps,
-};
+} satisfies Record<string, SpeechSDK.SpeechSynthesisOutputFormat>;
+
+export type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
+
+export function resolveMimeType(outputFormat: string): string {
+  if (/(?:wav|wave|riff)/i.test(outputFormat)) return "audio/wav";
+  if (/(?:mp3|mpeg)/i.test(outputFormat)) return "audio/mpeg";
+  if (/ogg/i.test(outputFormat)) return "audio/ogg";
+  if (/webm/i.test(outputFormat)) return "audio/webm";
+  if (/raw/i.test(outputFormat)) return "audio/L16";
+  return "application/octet-stream";
+}
 
 export function resolveOutputFormat(outputFormat: string): SpeechSDK.SpeechSynthesisOutputFormat {
-  const resolvedFormat = OUTPUT_FORMATS[outputFormat];
+  const resolvedFormat = (OUTPUT_FORMATS as Record<string, SpeechSDK.SpeechSynthesisOutputFormat>)[outputFormat];
   if (resolvedFormat === undefined) {
     throw new Error(`Unsupported Azure Speech output format: ${outputFormat}`);
   }

package/src/safe.ts

@@ -1,17 +1,37 @@
-import { validateAzureSsml, type AzureValidationOptions, type SsmlDiagnostic } from "@ssml-builder-js/ssml-core";
-import { AzureTtsError, createSpeechSdkError } from "./errors.ts";
+import {
+  createAzureUrlValidatorRunner,
+  validateAzureSsml,
+  type AzureUrlValidator,
+  type AzureValidationOptions,
+  type SsmlDiagnostic,
+} from "@ssml-builder-js/ssml-core";
+import {
+  type AzureTtsError,
+  type AzureTtsSynthesisError,
+  type SynthesisErrorKind,
+  toSynthesisError,
+} from "./errors.ts";
 import type { AzureTtsClient } from "./client.ts";
 import { mergeSynthesisResults } from "./synthesis.ts";
-import type { SsmlSynthesisChunk, SsmlSynthesisResult, SynthesisProgressEvent } from "./types.ts";
+import type {
+  SsmlSynthesisChunk,
+  SsmlSynthesisResult,
+  SynthesisProgressEvent,
+  SynthesizeChunksOptions,
+  RetryOptions,
+} from "./types.ts";
+import type { AzureTtsOutputFormat } from "./outputFormats.ts";
 
 export interface SsmlValidationError {
-  readonly kind: "validation";
+  readonly kind: "validation-error";
   readonly message: string;
   readonly diagnostics: readonly SsmlDiagnostic[];
 }
 
+export type SsmlSynthesisError = SsmlValidationError | AzureTtsSynthesisError;
+
 export class ChunkValidationError extends Error {
-  readonly kind = "chunk-validation" as const;
+  readonly kind = "validation-error" as const;
   readonly chunkIndex: number;
   readonly diagnostics: readonly SsmlDiagnostic[];
 
@@ -25,15 +45,26 @@ export class ChunkValidationError extends Error {
 
 export type Result<T, E> =
   | { readonly ok: true; readonly success: true; readonly status: "success"; readonly value: T }
-  | {
-      readonly ok: false;
-      readonly success: false;
-      readonly status: "validation-error" | "azure-api-error";
-      readonly error: E;
-    };
+  | (E extends { readonly kind: infer Kind extends SynthesisErrorKind }
+      ? {
+          readonly ok: false;
+          readonly success: false;
+          readonly status: Kind;
+          readonly error: E;
+        }
+      : {
+          readonly ok: false;
+          readonly success: false;
+          readonly status: SynthesisErrorKind;
+          readonly error: E;
+        });
 
 export type SynthesisResult<T, E> = Result<T, E>;
 
+function failure<E extends { readonly kind: SynthesisErrorKind }>(error: E): Result<never, E> {
+  return { ok: false, success: false, status: error.kind, error } as Result<never, E>;
+}
+
 export type Success<T> = Extract<Result<T, never>, { readonly ok: true }>;
 export type ValidationErrorResult = Extract<
   Result<never, SsmlValidationError>,
@@ -44,59 +75,147 @@ export type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, { readon
 export type SsmlSynthesisSafeResult =
   | Result<SsmlSynthesisResult, never>
   | Result<never, SsmlValidationError>
-  | Result<never, AzureTtsError>;
+  | Result<never, SsmlSynthesisError>;
 
 export interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
   /** Optional nested form for callers that want to keep validation settings grouped. */
   validation?: AzureValidationOptions;
+  signal?: AbortSignal;
 }
 
 export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
   validation?: AzureValidationOptions;
   outputFormat?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  sourceNodePath?: string[];
   onProgress?: (event: SynthesisProgressEvent) => void;
+  concurrency?: number;
+  retryOptions?: RetryOptions;
 }
 
 export type SsmlSynthesisChunksSafeResult =
   | Result<SsmlSynthesisResult, never>
   | Result<never, ChunkValidationError>
-  | Result<never, AzureTtsError>;
+  | Result<never, SsmlSynthesisError | ChunkValidationError>;
 
 interface SynthesisClient {
-  synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
+  synthesizeSsml(ssml: string, options?: Partial<SynthesizeChunksOptions>): Promise<SsmlSynthesisResult>;
   synthesizeChunks?(
     chunks: readonly (SsmlSynthesisChunk | string)[],
-    options?: { onProgress?: (event: SynthesisProgressEvent) => void },
+    options?: SynthesizeChunksOptions,
   ): Promise<SsmlSynthesisResult>;
 }
 
+function isRetryable(error: unknown): boolean {
+  if (error instanceof Error && /cancel|abort|tim(?:e|ed) ?out/i.test(error.message)) return false;
+  const status =
+    error && typeof error === "object" && "status" in error ? (error as { status?: unknown }).status : undefined;
+  if (typeof status === "number" && status !== 0) return status === 429 || (status >= 500 && status < 600);
+  const message = error instanceof Error ? error.message : String(error);
+  if (/\b4\d{2}\b/.test(message)) return false;
+  return /network|connection|connect|socket|fetch failed|econn|etimedout|temporar|transient|unavailable/i.test(message);
+}
+
+function delayForRetry(options: RetryOptions, attempt: number): number {
+  const maxDelay = Math.max(0, options.maxDelayMs);
+  const base = Math.min(maxDelay, Math.max(0, options.initialDelayMs) * 2 ** Math.max(0, attempt - 1));
+  return Math.floor(Math.random() * (base + 1));
+}
+
+function resolveConcurrency(value: number | undefined, total: number): number {
+  if (value === undefined) return 1;
+  if (value === Infinity) return Math.max(1, total);
+  return Number.isFinite(value) ? Math.max(1, Math.floor(value)) : 1;
+}
+
+async function retryableSynthesis(
+  synthesize: () => Promise<SsmlSynthesisResult>,
+  options: RetryOptions | undefined,
+  signal: AbortSignal | undefined,
+  onRetry: (attempt: number, delayMs: number) => void,
+): Promise<SsmlSynthesisResult> {
+  const retry = options
+    ? {
+        maxRetries: Math.max(0, Math.floor(options.maxRetries)),
+        initialDelayMs: options.initialDelayMs,
+        maxDelayMs: options.maxDelayMs,
+      }
+    : undefined;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) throw new Error("Speech synthesis was cancelled.");
+    try {
+      return await synthesize();
+    } catch (error) {
+      if (!retry || attempt >= retry.maxRetries || !isRetryable(error)) throw error;
+      attempt += 1;
+      const delayMs = delayForRetry(retry, attempt);
+      onRetry(attempt, delayMs);
+      if (delayMs > 0)
+        await new Promise<void>((resolve, reject) => {
+          const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+          }, delayMs);
+          const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(new Error("Speech synthesis was cancelled."));
+          };
+          signal?.addEventListener("abort", abort, { once: true });
+        });
+    }
+  }
+}
+
+function sharedValidationOptions(options: AzureValidationOptions, signal?: AbortSignal): AzureValidationOptions {
+  const validator = options.urlValidator ?? options.customUrlValidator;
+  if (!validator) return signal ? withValidationSignal(options, signal) : options;
+  const runner = createAzureUrlValidatorRunner(validator as AzureUrlValidator, {
+    ...(options.urlValidation ?? {}),
+    ...(options.urlValidatorConcurrency !== undefined ? { concurrency: options.urlValidatorConcurrency } : {}),
+    ...(options.urlValidatorTimeoutMs !== undefined ? { timeoutMs: options.urlValidatorTimeoutMs } : {}),
+    ...(signal ? { signal } : {}),
+    ...(options.urlValidatorCache ? { cache: options.urlValidatorCache } : {}),
+  });
+  return {
+    ...withValidationSignal(options, signal),
+    urlValidatorRunner: runner,
+  };
+}
+
 /** Validates SSML before invoking Azure and converts validation/API failures to one result shape. */
 export async function synthesizeSsmlSafe(
   client: Pick<AzureTtsClient, "synthesizeSsml"> | SynthesisClient,
   ssml: string,
   options: SynthesizeSsmlSafeOptions = {},
 ): Promise<SsmlSynthesisSafeResult> {
-  const validationOptions = options.validation ?? options;
+  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
   const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
   if (errors.length > 0) {
-    return {
-      ok: false,
-      success: false,
-      status: "validation-error",
-      error: {
-        kind: "validation",
-        message: "SSML validation failed; the Azure Speech API was not called.",
-        diagnostics: errors,
-      },
-    };
+    return failure({
+      kind: "validation-error",
+      message: "SSML validation failed; the Azure Speech API was not called.",
+      diagnostics: errors,
+    });
   }
 
   try {
-    return { ok: true, success: true, status: "success", value: await client.synthesizeSsml(ssml) };
+    return {
+      ok: true,
+      success: true,
+      status: "success",
+      value: await client.synthesizeSsml(ssml, { signal: options.signal }),
+    };
   } catch (error) {
-    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
-    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+    const synthesisError = toSynthesisError(error);
+    return failure(synthesisError);
   }
 }
 
@@ -106,7 +225,11 @@ export async function synthesizeSsmlChunksSafe(
   chunks: readonly (SsmlSynthesisChunk | string)[],
   options: SynthesizeSsmlChunksSafeOptions = {},
 ): Promise<SsmlSynthesisChunksSafeResult> {
-  const validationOptions = options.validation ?? options;
+  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   const pending = (index: number, status: SynthesisProgressEvent["status"], error?: unknown): void => {
     options.onProgress?.({
       currentChunk: status === "success" ? index + 1 : index,
@@ -124,77 +247,203 @@ export async function synthesizeSsmlChunksSafe(
     pending(index, "pending");
   });
   const validations = await Promise.all(
-    chunks.map(async (chunk) => {
+    chunks.map(async (chunk, index) => {
       const ssml = typeof chunk === "string" ? chunk : chunk.ssml;
-      const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
+      const sourceNodePath =
+        typeof chunk === "string" ? options.sourceNodePath : (chunk.sourceNodePath ?? options.sourceNodePath);
+      const diagnostics = await Promise.resolve(
+        validateAzureSsml(ssml, {
+          ...validationOptions,
+          ...(sourceNodePath ? { sourceNodePath } : {}),
+          chunkIndex: index,
+        }),
+      );
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     }),
   );
   const firstInvalidIndex = validations.findIndex((diagnostics) => diagnostics.length > 0);
+  if (options.signal?.aborted) {
+    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    return failure(error);
+  }
   if (firstInvalidIndex >= 0) {
     const error = new ChunkValidationError(firstInvalidIndex, validations[firstInvalidIndex] ?? []);
     pending(firstInvalidIndex, "failed", error);
-    return { ok: false, success: false, status: "validation-error", error };
+    return failure(error);
   }
 
   try {
     if (client.synthesizeChunks) {
-      const value = await client.synthesizeChunks(chunks, { onProgress: options.onProgress });
+      const normalizedChunks = chunks.map((chunk) => {
+        if (typeof chunk === "string" || chunk.sourceNodePath || !options.sourceNodePath) return chunk;
+        return { ...chunk, sourceNodePath: [...options.sourceNodePath] };
+      });
+      const value = await client.synthesizeChunks(normalizedChunks, {
+        onProgress: options.onProgress,
+        outputFormat: options.outputFormat,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+        sourceNodePath: options.sourceNodePath,
+        concurrency: options.concurrency,
+        retryOptions: options.retryOptions,
+      });
       return { ok: true, success: true, status: "success", value };
     }
-    const results: SsmlSynthesisResult[] = [];
-    for (const [index, chunk] of chunks.entries()) {
-      const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
-      const sourceNodePath = input.sourceNodePath;
-      pending(index, "synthesizing");
-      const startedAt = Date.now();
-      try {
-        const result = await client.synthesizeSsml(input.ssml);
-        results.push({
-          ...result,
-          ...(input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {}),
-          ...(sourceNodePath
-            ? {
-                boundaries: result.boundaries?.map((event) => ({
-                  ...event,
-                  sourceNodePath: [...sourceNodePath],
-                })),
-                visemes: result.visemes?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] })),
-                bookmarks: result.bookmarks?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] })),
-              }
-            : {}),
-        });
-        options.onProgress?.({
-          currentChunk: index + 1,
-          totalChunks: chunks.length,
-          percent: chunks.length === 0 ? 100 : Math.round(((index + 1) / chunks.length) * 100),
-          chunkIndex: index,
-          originalTextRange: input.originalTextRange,
-          status: "success",
-          durationMs: Date.now() - startedAt,
-        });
-      } catch (error) {
-        options.onProgress?.({
-          currentChunk: index,
-          totalChunks: chunks.length,
-          percent: chunks.length === 0 ? 100 : Math.round((index / chunks.length) * 100),
-          chunkIndex: index,
-          originalTextRange: input.originalTextRange,
-          status: "failed",
-          durationMs: Date.now() - startedAt,
-          error,
-        });
-        throw error;
+    const results: Array<SsmlSynthesisResult | undefined> = new Array(chunks.length);
+    let completed = 0;
+    let nextIndex = 0;
+    const concurrency = resolveConcurrency(options.concurrency, chunks.length);
+    const worker = async (): Promise<void> => {
+      while (true) {
+        const index = nextIndex++;
+        if (index >= chunks.length) return;
+        const chunk = chunks[index];
+        const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
+        const sourceNodePath = input.sourceNodePath;
+        const originalTextRange = input.originalTextRange;
+        pending(index, "synthesizing");
+        const startedAt = Date.now();
+        try {
+          const result = await retryableSynthesis(
+            () =>
+              client.synthesizeSsml(input.ssml, {
+                outputFormat: options.outputFormat,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+                sourceNodePath: input.sourceNodePath ?? options.sourceNodePath,
+              }),
+            options.retryOptions,
+            options.signal,
+            (retryAttempt, nextRetryDelayMs) =>
+              options.onProgress?.({
+                currentChunk: completed,
+                totalChunks: chunks.length,
+                percent: chunks.length === 0 ? 100 : Math.round((completed / chunks.length) * 100),
+                chunkIndex: index,
+                originalTextRange: input.originalTextRange,
+                status: "synthesizing",
+                durationMs: Date.now() - startedAt,
+                retryAttempt,
+                nextRetryDelayMs,
+                isRetrying: true,
+              }),
+          );
+          results[index] = {
+            ...result,
+            ...(input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {}),
+            ...(sourceNodePath
+              ? {
+                  boundaries: result.boundaries?.map((event) => ({
+                    ...event,
+                    sourceNodePath: [...sourceNodePath],
+                    ...(event.originalTextRange
+                      ? { originalTextRange: { ...event.originalTextRange } }
+                      : input.originalTextRange
+                        ? { originalTextRange: { ...input.originalTextRange } }
+                        : {}),
+                  })),
+                  visemes: result.visemes?.map((event) => ({
+                    ...event,
+                    sourceNodePath: [...sourceNodePath],
+                    ...(event.originalTextRange
+                      ? { originalTextRange: { ...event.originalTextRange } }
+                      : input.originalTextRange
+                        ? { originalTextRange: { ...input.originalTextRange } }
+                        : {}),
+                  })),
+                  bookmarks: result.bookmarks?.map((event) => ({
+                    ...event,
+                    sourceNodePath: [...sourceNodePath],
+                    ...(event.originalTextRange
+                      ? { originalTextRange: { ...event.originalTextRange } }
+                      : input.originalTextRange
+                        ? { originalTextRange: { ...input.originalTextRange } }
+                        : {}),
+                  })),
+                }
+              : {}),
+            ...(originalTextRange
+              ? {
+                  boundaries: result.boundaries?.map((event) => ({
+                    ...event,
+                    originalTextRange: event.originalTextRange
+                      ? { ...event.originalTextRange }
+                      : { ...originalTextRange },
+                  })),
+                  wordBoundary: result.wordBoundary?.map((event) => ({
+                    ...event,
+                    originalTextRange: event.originalTextRange
+                      ? { ...event.originalTextRange }
+                      : { ...originalTextRange },
+                  })),
+                  wordBoundaries: result.wordBoundaries?.map((event) => ({
+                    ...event,
+                    originalTextRange: event.originalTextRange
+                      ? { ...event.originalTextRange }
+                      : { ...originalTextRange },
+                  })),
+                  visemes: result.visemes?.map((event) => ({
+                    ...event,
+                    originalTextRange: event.originalTextRange
+                      ? { ...event.originalTextRange }
+                      : { ...originalTextRange },
+                  })),
+                  bookmarks: result.bookmarks?.map((event) => ({
+                    ...event,
+                    originalTextRange: event.originalTextRange
+                      ? { ...event.originalTextRange }
+                      : { ...originalTextRange },
+                  })),
+                }
+              : {}),
+          };
+          completed += 1;
+          options.onProgress?.({
+            currentChunk: completed,
+            totalChunks: chunks.length,
+            percent: chunks.length === 0 ? 100 : Math.round((completed / chunks.length) * 100),
+            chunkIndex: index,
+            originalTextRange: input.originalTextRange,
+            status: "success",
+            durationMs: Date.now() - startedAt,
+          });
+        } catch (error) {
+          options.onProgress?.({
+            currentChunk: completed,
+            totalChunks: chunks.length,
+            percent: chunks.length === 0 ? 100 : Math.round((index / chunks.length) * 100),
+            chunkIndex: index,
+            originalTextRange: input.originalTextRange,
+            status: "failed",
+            durationMs: Date.now() - startedAt,
+            error,
+          });
+          throw error;
+        }
       }
-    }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    const orderedResults = results.filter((result): result is SsmlSynthesisResult => result !== undefined);
     return {
       ok: true,
       success: true,
       status: "success",
-      value: mergeSynthesisResults(results, options.outputFormat),
+      value: mergeSynthesisResults(orderedResults, {
+        format: (options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3") as AzureTtsOutputFormat,
+        signal: options.signal,
+      }),
     };
   } catch (error) {
-    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
-    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+    const synthesisError = toSynthesisError(error);
+    return failure(synthesisError);
   }
 }
+
+function withValidationSignal(options: AzureValidationOptions, signal?: AbortSignal): AzureValidationOptions {
+  if (!signal) return options;
+  return {
+    ...options,
+    urlValidatorSignal: signal,
+    urlValidation: { ...(options.urlValidation ?? {}), signal },
+  };
+}