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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @ssml-builder-js/azure-tts-client
 
+## 2.16.0
+
+### Minor Changes
+
+- Add shared URL validation for SSML chunks, transient retry and bounded parallel synthesis, structured diagnostics and synchronization mapping status, audio header/specification validation, and the stricter custom audio merger context.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ssml-builder-js/ssml-core@2.16.0
+
 ## 2.15.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -66,6 +66,23 @@ interface TtsConfig {
     /** Exact source text segments used to map individual Azure events. */
     sourceTextSegments?: SsmlSourceTextSegment[];
     sourceMarkers?: SsmlSourceMarker[];
+    concurrency?: number;
+    retryOptions?: RetryOptions;
+}
+type MappingStatus = "exact" | "fallback" | "unmapped";
+interface AudioSpecification {
+    format: string;
+    mimeType: string;
+    codec: "pcm" | "mp3" | "opus" | "silk" | "unknown";
+    sampleRate: number;
+    channels: number;
+    bitrate?: number;
+    isCompressed: boolean;
+}
+interface RetryOptions {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
 }
 type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
 interface SsmlSynthesisBoundary {
@@ -85,6 +102,7 @@ interface SsmlSynthesisBoundary {
     /** Audio offset within the originating chunk before merge. */
     chunkAudioOffsetMs?: number;
     requestId?: string;
+    mappingStatus: MappingStatus;
 }
 interface SsmlSynthesisViseme {
     visemeId: number;
@@ -98,6 +116,7 @@ interface SsmlSynthesisViseme {
     originalTextRange?: SsmlTextRange;
     chunkAudioOffsetMs?: number;
     requestId?: string;
+    mappingStatus: MappingStatus;
 }
 interface SsmlSynthesisBookmark {
     name: string;
@@ -111,6 +130,7 @@ interface SsmlSynthesisBookmark {
     originalTextRange?: SsmlTextRange;
     chunkAudioOffsetMs?: number;
     requestId?: string;
+    mappingStatus: MappingStatus;
 }
 /** Audio and Azure Speech synchronization events emitted for one SSML request. */
 interface SsmlSynthesisResult {
@@ -132,6 +152,7 @@ interface SsmlSynthesisResult {
     };
     /** MIME type of a result produced by an explicit merge operation. */
     mimeType?: string;
+    audioSpec?: AudioSpecification;
 }
 interface MergedSynthesisResult extends SsmlSynthesisResult {
     mimeType: string;
@@ -152,6 +173,8 @@ interface SynthesizeChunksOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
     sourceNodePath?: string[];
+    concurrency?: number;
+    retryOptions?: RetryOptions;
 }
 interface SynthesisProgressEvent {
     /** 1-based completed chunk count retained for backward compatibility. */
@@ -163,6 +186,9 @@ interface SynthesisProgressEvent {
     status: SynthesisChunkStatus;
     durationMs: number;
     error?: unknown;
+    retryAttempt?: number;
+    nextRetryDelayMs?: number;
+    isRetrying?: boolean;
 }
 interface AzureTtsLogger {
     debug?: (...args: unknown[]) => void;
@@ -179,9 +205,11 @@ interface AzureTtsClientOptions {
     outputFormat?: string;
     logger?: AzureTtsLogger;
     onProgress?: (event: SynthesisProgressEvent) => void;
+    concurrency?: number;
+    retryOptions?: RetryOptions;
 }
 
-type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "unsupported-format-error" | "cancelled" | "timeout";
+type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "audio-format-mismatch" | "unsupported-format-error" | "cancelled" | "timeout";
 declare class AzureTtsError extends Error {
     readonly kind: "azure-api-error";
     readonly status: number;
@@ -207,13 +235,19 @@ declare class MergeError extends Error {
     readonly cause: unknown;
     constructor(message: string, cause?: unknown);
 }
+/** Thrown when chunk headers describe incompatible audio streams. */
+declare class AudioFormatMismatchError extends Error {
+    readonly kind: "audio-format-mismatch";
+    readonly inputSpecs: readonly AudioSpecification[];
+    constructor(message: string, inputSpecs?: readonly AudioSpecification[]);
+}
 /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
 declare class UnsupportedMergeFormatError extends Error {
     readonly kind: "unsupported-format-error";
     readonly format: string;
     constructor(format: string);
 }
-type AzureTtsSynthesisError = AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
+type AzureTtsSynthesisError = AzureTtsError | MergeError | AudioFormatMismatchError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
 
 interface SsmlValidationError {
     readonly kind: "validation-error";
@@ -268,6 +302,8 @@ interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     timeoutMs?: number;
     sourceNodePath?: string[];
     onProgress?: (event: SynthesisProgressEvent) => void;
+    concurrency?: number;
+    retryOptions?: RetryOptions;
 }
 type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
 interface SynthesisClient {
@@ -293,20 +329,31 @@ declare class AzureTtsClient {
 type MergeAudioFormat = "wav" | "mp3" | "raw";
 interface MergeAudioOptions {
     format: AzureTtsOutputFormat;
+    signal?: AbortSignal;
+    outputMimeType?: string;
+}
+type InputAudioSpecs = AudioSpecification[];
+interface CustomMergerContext {
+    format: string;
+    outputMimeType: string;
+    inputSpecs: InputAudioSpecs;
+    signal: AbortSignal;
 }
 interface MergeSynthesisOptions extends MergeAudioOptions {
-    customMerger?: (buffers: ArrayBuffer[], format: string) => Promise<ArrayBuffer> | ArrayBuffer;
+    customMerger?: (buffers: ArrayBuffer[], context: CustomMergerContext) => Promise<ArrayBuffer> | ArrayBuffer;
 }
 type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
     customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
 };
+/** Extracts the stream specification from a WAV/MP3 header and output-format fallback. */
+declare function inspectAudioSpecification(buffer: ArrayBuffer, format: string): AudioSpecification;
 /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
 declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined;
 declare function canMergeAudioFormat(format: string): boolean;
 /** Merges audio buffers while preserving the invariants of supported containers. */
 declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], options: MergeAudioOptions): ArrayBuffer;
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
-/** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
+/** Synthesizes chunks with bounded concurrency, retries transient failures, and merges in chunk order. */
 declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
 declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: AsyncMergeSynthesisOptions): Promise<MergedSynthesisResult>;
 declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: MergeAudioOptions): MergedSynthesisResult;
@@ -341,4 +388,4 @@ interface AzureVoiceCatalog {
 /** Fetches and deduplicates the current Azure Speech voice catalog for one or more regions. */
 declare function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOptions): Promise<AzureVoiceCatalog>;
 
-export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
+export { AudioFormatMismatchError, type AudioSpecification, type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, type CustomMergerContext, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type InputAudioSpecs, type MappingStatus, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type RetryOptions, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, inspectAudioSpecification, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };

package/dist/index.d.ts

@@ -66,6 +66,23 @@ interface TtsConfig {
     /** Exact source text segments used to map individual Azure events. */
     sourceTextSegments?: SsmlSourceTextSegment[];
     sourceMarkers?: SsmlSourceMarker[];
+    concurrency?: number;
+    retryOptions?: RetryOptions;
+}
+type MappingStatus = "exact" | "fallback" | "unmapped";
+interface AudioSpecification {
+    format: string;
+    mimeType: string;
+    codec: "pcm" | "mp3" | "opus" | "silk" | "unknown";
+    sampleRate: number;
+    channels: number;
+    bitrate?: number;
+    isCompressed: boolean;
+}
+interface RetryOptions {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
 }
 type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
 interface SsmlSynthesisBoundary {
@@ -85,6 +102,7 @@ interface SsmlSynthesisBoundary {
     /** Audio offset within the originating chunk before merge. */
     chunkAudioOffsetMs?: number;
     requestId?: string;
+    mappingStatus: MappingStatus;
 }
 interface SsmlSynthesisViseme {
     visemeId: number;
@@ -98,6 +116,7 @@ interface SsmlSynthesisViseme {
     originalTextRange?: SsmlTextRange;
     chunkAudioOffsetMs?: number;
     requestId?: string;
+    mappingStatus: MappingStatus;
 }
 interface SsmlSynthesisBookmark {
     name: string;
@@ -111,6 +130,7 @@ interface SsmlSynthesisBookmark {
     originalTextRange?: SsmlTextRange;
     chunkAudioOffsetMs?: number;
     requestId?: string;
+    mappingStatus: MappingStatus;
 }
 /** Audio and Azure Speech synchronization events emitted for one SSML request. */
 interface SsmlSynthesisResult {
@@ -132,6 +152,7 @@ interface SsmlSynthesisResult {
     };
     /** MIME type of a result produced by an explicit merge operation. */
     mimeType?: string;
+    audioSpec?: AudioSpecification;
 }
 interface MergedSynthesisResult extends SsmlSynthesisResult {
     mimeType: string;
@@ -152,6 +173,8 @@ interface SynthesizeChunksOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
     sourceNodePath?: string[];
+    concurrency?: number;
+    retryOptions?: RetryOptions;
 }
 interface SynthesisProgressEvent {
     /** 1-based completed chunk count retained for backward compatibility. */
@@ -163,6 +186,9 @@ interface SynthesisProgressEvent {
     status: SynthesisChunkStatus;
     durationMs: number;
     error?: unknown;
+    retryAttempt?: number;
+    nextRetryDelayMs?: number;
+    isRetrying?: boolean;
 }
 interface AzureTtsLogger {
     debug?: (...args: unknown[]) => void;
@@ -179,9 +205,11 @@ interface AzureTtsClientOptions {
     outputFormat?: string;
     logger?: AzureTtsLogger;
     onProgress?: (event: SynthesisProgressEvent) => void;
+    concurrency?: number;
+    retryOptions?: RetryOptions;
 }
 
-type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "unsupported-format-error" | "cancelled" | "timeout";
+type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "audio-format-mismatch" | "unsupported-format-error" | "cancelled" | "timeout";
 declare class AzureTtsError extends Error {
     readonly kind: "azure-api-error";
     readonly status: number;
@@ -207,13 +235,19 @@ declare class MergeError extends Error {
     readonly cause: unknown;
     constructor(message: string, cause?: unknown);
 }
+/** Thrown when chunk headers describe incompatible audio streams. */
+declare class AudioFormatMismatchError extends Error {
+    readonly kind: "audio-format-mismatch";
+    readonly inputSpecs: readonly AudioSpecification[];
+    constructor(message: string, inputSpecs?: readonly AudioSpecification[]);
+}
 /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
 declare class UnsupportedMergeFormatError extends Error {
     readonly kind: "unsupported-format-error";
     readonly format: string;
     constructor(format: string);
 }
-type AzureTtsSynthesisError = AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
+type AzureTtsSynthesisError = AzureTtsError | MergeError | AudioFormatMismatchError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
 
 interface SsmlValidationError {
     readonly kind: "validation-error";
@@ -268,6 +302,8 @@ interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     timeoutMs?: number;
     sourceNodePath?: string[];
     onProgress?: (event: SynthesisProgressEvent) => void;
+    concurrency?: number;
+    retryOptions?: RetryOptions;
 }
 type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
 interface SynthesisClient {
@@ -293,20 +329,31 @@ declare class AzureTtsClient {
 type MergeAudioFormat = "wav" | "mp3" | "raw";
 interface MergeAudioOptions {
     format: AzureTtsOutputFormat;
+    signal?: AbortSignal;
+    outputMimeType?: string;
+}
+type InputAudioSpecs = AudioSpecification[];
+interface CustomMergerContext {
+    format: string;
+    outputMimeType: string;
+    inputSpecs: InputAudioSpecs;
+    signal: AbortSignal;
 }
 interface MergeSynthesisOptions extends MergeAudioOptions {
-    customMerger?: (buffers: ArrayBuffer[], format: string) => Promise<ArrayBuffer> | ArrayBuffer;
+    customMerger?: (buffers: ArrayBuffer[], context: CustomMergerContext) => Promise<ArrayBuffer> | ArrayBuffer;
 }
 type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
     customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
 };
+/** Extracts the stream specification from a WAV/MP3 header and output-format fallback. */
+declare function inspectAudioSpecification(buffer: ArrayBuffer, format: string): AudioSpecification;
 /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
 declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined;
 declare function canMergeAudioFormat(format: string): boolean;
 /** Merges audio buffers while preserving the invariants of supported containers. */
 declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], options: MergeAudioOptions): ArrayBuffer;
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
-/** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
+/** Synthesizes chunks with bounded concurrency, retries transient failures, and merges in chunk order. */
 declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
 declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: AsyncMergeSynthesisOptions): Promise<MergedSynthesisResult>;
 declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: MergeAudioOptions): MergedSynthesisResult;
@@ -341,4 +388,4 @@ interface AzureVoiceCatalog {
 /** Fetches and deduplicates the current Azure Speech voice catalog for one or more regions. */
 declare function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOptions): Promise<AzureVoiceCatalog>;
 
-export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
+export { AudioFormatMismatchError, type AudioSpecification, type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, type CustomMergerContext, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type InputAudioSpecs, type MappingStatus, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type RetryOptions, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, inspectAudioSpecification, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };