ssml-builder-js 2.17.0 → 2.19.0

package/README.md

@@ -919,6 +919,10 @@ v2.16.0 では `concurrency` と `retryOptions`（429/5xx・ネットワーク
 
 v2.17.0 では `customMerger`、`outputMimeType`、`postMergeValidator` をチャンク合成の末尾まで構成でき、`BatchChunkValidationError` が全チャンクの診断と総エラー数を返します。`cancelOnFailure` と `resumeChunks` により成功済みバイナリを再利用でき、`timeouts`（URL 検証、チャンク、リトライ込みチャンク、ジョブ全体）を個別に設定できます。429 の `Retry-After` は指数バックオフより優先されます。`AudioSpecification` には `bitDepth`、`container`、`isVbr` が追加され、同期 `mappingStatus` は JSON 化後も保持されます。
 
+v2.18.0 では `resumeChunks` に SSML・音声設定・出力形式のフィンガープリントを付与し、不一致のキャッシュを自動的に再合成します。`PartialChunkSynthesisResult.chunkStates` は成功、直接失敗、連鎖キャンセル、未実行を区別します。`totalJobMs` は単一合成にも適用され、上限を超える `Retry-After` は待機せずタイムアウトになります。`AzureTtsClient` の既定値として再試行、キャンセル、結合器、MIME、結合後検証、再開検証を注入できます。RAW 音声はサンプリング周波数、ビット深度、codec、フレーム境界を検証します。
+
+v2.19.0 では、再開フィンガープリントに SSML、voice、言語、出力形式、リージョン、endpoint、custom headers、スキーマバージョンを含め、環境の異なるキャッシュの再利用を防ぎます。`resumeChunkIndices` の欠落は `IncompleteChunkSetError` で結合前に拒否され、`ChunkExecutionState.error` は JSON 化可能な `SerializedChunkError` になります。単一合成を含む URL 検証、再試行、チャンク合成、結合は絶対 deadline で制限され、Ogg/WebM/RAW Opus/SILK の実体ヘッダーも検証します。Visual editor は `expressAs` などの別名を正規化し、neural-HD の非対応タグを表示します。
+
 `validateAzureSsml` の `urlValidation` オプションは URL の重複排除、キャッシュ、`concurrency`、`signal`、`timeoutMs` を制御します。
 
 For long documents, use `synthesizeSsmlChunks` or `AzureTtsClient.synthesizeChunks`; `onProgress` reports completed chunks while audio and synchronization offsets are merged. `synthesizeSsmlSafe(client, ssml, { validation })` validates before synthesis and returns a discriminated result without calling Azure when static validation fails.
@@ -929,6 +933,10 @@ In v2.16.0, use `concurrency` and `retryOptions` to control chunk synthesis; onl
 
 In v2.17.0, configure `customMerger`, `outputMimeType`, and `postMergeValidator` through the chunk synthesis pipeline. `BatchChunkValidationError` aggregates diagnostics and the total error count for every invalid chunk. `cancelOnFailure` and `resumeChunks` allow successful binary chunks to be reused, while `timeouts` independently bounds URL validation, individual chunks, retries, and the total job. HTTP 429 `Retry-After` takes priority over exponential backoff. `AudioSpecification` now includes `bitDepth`, `container`, and `isVbr`, and `mappingStatus` remains present after JSON serialization.
 
+In v2.18.0, `resumeChunks` carries a fingerprint of the SSML, voice settings, and output format; stale cache entries are automatically re-synthesized. `PartialChunkSynthesisResult.chunkStates` distinguishes succeeded, directly failed, chained-cancelled, and pending chunks. `totalJobMs` also bounds single synthesis, and an over-budget `Retry-After` fails immediately without sleeping. `AzureTtsClient` accepts retry, cancellation, merger, MIME, post-merge validation, and resume-validation defaults. RAW audio now validates sample rate, bit depth, codec, and frame alignment.
+
+In v2.19.0, resume fingerprints include SSML, voice, language, output format, region, endpoint, custom headers, and schema version so cached chunks cannot cross synthesis environments. Missing `resumeChunkIndices` are rejected before merge with `IncompleteChunkSetError`, and `ChunkExecutionState.error` is a JSON-serializable `SerializedChunkError`. URL validation, retries, chunk synthesis, and merging share an absolute deadline, including single synthesis. Ogg/WebM/RAW Opus/SILK payloads receive concrete container or header validation, and the visual editor normalizes aliases such as `expressAs` while showing neural-HD unsupported tags.
+
 The `urlValidation` option of `validateAzureSsml` provides URL deduplication, in-memory caching, bounded `concurrency`, `signal`, and `timeoutMs` controls.
 
 The public updater CLI is `npx ssml-builder sync-voices --region eastus --output ./azure-voices.json`. It reads the key from `AZURE_SPEECH_KEY` (or `--key`) and regions from `AZURE_SPEECH_REGION(S)` (or `--region(s)`).

package/dist/{index.d-tpKoP1jl.d.mts → index.d-4kqVuH29.d.mts}

@@ -275,4 +275,4 @@ interface AzureVoiceCatalogMetadata {
     regionDiffs?: Readonly<Record<string, readonly string[]>>;
 }
 
-export type { AzureValidationOptions as A, SsmlTextRange as S, SsmlSourceTextSegment as a, SsmlSourceMarker as b, SsmlDiagnostic as c, SsmlDocument as d, SsmlElement as e, AzureVoiceCatalogMetadata as f };
+export type { AzureVoiceCatalogMetadata as A, SsmlDocument as S, SsmlElement as a, SsmlTextRange as b, SsmlSourceTextSegment as c, SsmlSourceMarker as d, SsmlDiagnostic as e, AzureValidationOptions as f };

package/dist/{index.d-tpKoP1jl.d.ts → index.d-4kqVuH29.d.ts}

@@ -275,4 +275,4 @@ interface AzureVoiceCatalogMetadata {
     regionDiffs?: Readonly<Record<string, readonly string[]>>;
 }
 
-export type { AzureValidationOptions as A, SsmlTextRange as S, SsmlSourceTextSegment as a, SsmlSourceMarker as b, SsmlDiagnostic as c, SsmlDocument as d, SsmlElement as e, AzureVoiceCatalogMetadata as f };
+export type { AzureVoiceCatalogMetadata as A, SsmlDocument as S, SsmlElement as a, SsmlTextRange as b, SsmlSourceTextSegment as c, SsmlSourceMarker as d, SsmlDiagnostic as e, AzureValidationOptions as f };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidationRunnerOptions, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, Diagnostic, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SplitSsmlOptions, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlChunk, SsmlChunkContext, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlSourceMap, SsmlSourceMarker, SsmlSourceTextSegment, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, getSsmlSourceMap, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateAzureSsmlChunks, validateSsml, validateSsmlStructureIntegrity } from './core.mjs';
-import { S as SsmlTextRange, a as SsmlSourceTextSegment, b as SsmlSourceMarker, c as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-tpKoP1jl.mjs';
+import { b as SsmlTextRange, c as SsmlSourceTextSegment, d as SsmlSourceMarker, e as SsmlDiagnostic, f as AzureValidationOptions } from './index.d-4kqVuH29.mjs';
 import * as SpeechSDK from 'microsoft-cognitiveservices-speech-sdk';
 
 declare const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
@@ -47,6 +47,68 @@ declare const OUTPUT_FORMATS: {
 type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
 declare function resolveMimeType(outputFormat: string): string;
 
+type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "audio-format-mismatch" | "unsupported-format-error" | "cancelled" | "timeout" | "incomplete-chunk-set";
+type SerializedChunkErrorCode = "VALIDATION_ERROR" | "AZURE_API_ERROR" | "TIMEOUT" | "CANCELLED" | "MERGE_ERROR" | "FORMAT_MISMATCH";
+interface SerializedChunkError {
+    code: SerializedChunkErrorCode;
+    phase: "url-validation" | "synthesis" | "merge";
+    message: string;
+    isOriginalFailure: boolean;
+    isRetryable: boolean;
+    httpStatus?: number;
+    details?: Record<string, unknown>;
+}
+/** Backward-compatible name used by persisted execution-state consumers. */
+type SerializedExecutionError = SerializedChunkError;
+declare class AzureTtsError extends Error {
+    readonly kind: "azure-api-error";
+    readonly status: number;
+    readonly statusText: string;
+    readonly responseBody: string;
+    readonly requestId: string | null;
+    readonly retryAfterMs?: number;
+    constructor(status: number, statusText: string, responseBody: string, requestId: string | null, responseHeaders?: Headers | Readonly<Record<string, string>>);
+}
+/** Reads Retry-After from an error-like value, returning milliseconds when present. */
+declare function getRetryAfterDelayMs(error: unknown): number | undefined;
+declare class AzureTtsSdkError extends AzureTtsError {
+    readonly errorDetails: string;
+    constructor(errorDetails: string);
+}
+declare class SynthesisCancelledError extends Error {
+    readonly kind: "cancelled";
+    constructor(message?: string);
+}
+declare class SynthesisTimeoutError extends Error {
+    readonly kind: "timeout";
+    constructor(message: string);
+}
+declare class IncompleteChunkSetError extends Error {
+    readonly kind: "incomplete-chunk-set";
+    readonly totalChunks: number;
+    readonly missingChunkIndices: readonly number[];
+    constructor(totalChunks: number, missingChunkIndices: readonly number[]);
+}
+declare class MergeError extends Error {
+    readonly kind: "merge-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 | AudioFormatMismatchError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError | IncompleteChunkSetError;
+declare function serializeChunkError(error: unknown, phase: SerializedChunkError["phase"], isOriginalFailure: boolean): SerializedChunkError;
+
 interface TtsConfig {
     signal?: AbortSignal;
     timeoutMs?: number;
@@ -55,6 +117,8 @@ 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;
@@ -76,12 +140,13 @@ interface TtsConfig {
     customMerger?: CustomAudioMerger;
     outputMimeType?: string;
     postMergeValidator?: PostMergeValidator;
+    resumeValidation?: ResumeValidationMode;
 }
 type MappingStatus = "exact" | "fallback" | "unmapped";
 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;
@@ -90,6 +155,7 @@ interface AudioSpecification {
     isVbr?: boolean;
     isCompressed: boolean;
 }
+type ResumeValidationMode = "strict" | "disabled";
 interface SynthesisTimeouts {
     urlValidationMs?: number;
     perChunkMs?: number;
@@ -188,6 +254,8 @@ interface SsmlSynthesisChunk {
 interface SynthesizeChunksOptions {
     onProgress?: (event: SynthesisProgressEvent) => void;
     outputFormat?: AzureTtsOutputFormat | string;
+    customHeaders?: Readonly<Record<string, string>>;
+    fingerprintSchemaVersion?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
     timeouts?: SynthesisTimeouts;
@@ -200,6 +268,7 @@ interface SynthesizeChunksOptions {
     customMerger?: CustomAudioMerger;
     outputMimeType?: string;
     postMergeValidator?: PostMergeValidator;
+    resumeValidation?: ResumeValidationMode;
 }
 interface CustomMergerContext {
     format: string;
@@ -211,12 +280,25 @@ type CustomAudioMerger = (buffers: ArrayBuffer[], context: CustomMergerContext)
 type PostMergeValidator = (result: MergedSynthesisResult, context: CustomMergerContext) => boolean | undefined | Promise<boolean | undefined>;
 interface SynthesizedChunk extends SsmlSynthesisResult {
     chunkIndex: number;
+    /** Fingerprint of the SSML and synthesis settings used to create this chunk. */
+    fingerprint: string;
+}
+type ChunkExecutionStatus = "succeeded" | "failed" | "cancelled" | "pending";
+interface ChunkExecutionState {
+    chunkIndex: number;
+    status: ChunkExecutionStatus;
+    error?: SerializedChunkError;
+    isOriginalFailure?: boolean;
+    canResume: boolean;
+    result?: SsmlSynthesisResult;
 }
 interface PartialChunkSynthesisResult {
     synthesizedChunks: readonly SynthesizedChunk[];
     completedChunks: readonly SynthesizedChunk[];
     pendingChunkIndices: readonly number[];
     failedChunkIndices: readonly number[];
+    cancelledChunkIndices: readonly number[];
+    chunkStates: readonly ChunkExecutionState[];
     totalChunks: number;
 }
 /** Alias for applications that use the shorter result name. */
@@ -249,54 +331,31 @@ 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;
 }
 
-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;
-    readonly statusText: string;
-    readonly responseBody: string;
-    readonly requestId: string | null;
-    readonly retryAfterMs?: number;
-    constructor(status: number, statusText: string, responseBody: string, requestId: string | null, responseHeaders?: Headers | Readonly<Record<string, string>>);
-}
-/** Reads Retry-After from an error-like value, returning milliseconds when present. */
-declare function getRetryAfterDelayMs(error: unknown): number | undefined;
-declare class AzureTtsSdkError extends AzureTtsError {
-    readonly errorDetails: string;
-    constructor(errorDetails: string);
-}
-declare class SynthesisCancelledError extends Error {
-    readonly kind: "cancelled";
-    constructor(message?: string);
-}
-declare class SynthesisTimeoutError extends Error {
-    readonly kind: "timeout";
-    constructor(message: string);
-}
-declare class MergeError extends Error {
-    readonly kind: "merge-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);
+/** Coordinates one absolute deadline across validation, synthesis, retries, and merging. */
+declare class DeadlineController {
+    #private;
+    readonly deadlineAtMs: number | undefined;
+    readonly signal: AbortSignal;
+    constructor(totalJobMs: number | undefined, parent?: AbortSignal);
+    get timedOut(): boolean;
+    get remainingMs(): number;
+    throwIfExpired(): void;
+    abort(): void;
+    dispose(): void;
 }
-type AzureTtsSynthesisError = AzureTtsError | MergeError | AudioFormatMismatchError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
 
 interface SsmlValidationError {
     readonly kind: "validation-error";
@@ -361,6 +420,8 @@ interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
 interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     validation?: AzureValidationOptions;
     outputFormat?: string;
+    customHeaders?: Readonly<Record<string, string>>;
+    fingerprintSchemaVersion?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
     timeouts?: SynthesisTimeouts;
@@ -374,6 +435,7 @@ interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     customMerger?: CustomAudioMerger;
     outputMimeType?: string;
     postMergeValidator?: PostMergeValidator;
+    resumeValidation?: ResumeValidationMode;
 }
 type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, BatchChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
 interface SynthesisClient {
@@ -403,9 +465,26 @@ interface MergeAudioOptions {
     outputMimeType?: string;
 }
 type InputAudioSpecs = AudioSpecification[];
+/**
+ * Creates a deterministic, runtime-independent fingerprint for a synthesis chunk.
+ * The complete SSML is included so changes to voice, language, prosody, or text
+ * invalidate a cached result even when those settings are nested in the markup.
+ */
+interface ChunkFingerprintOptions {
+    outputFormat?: string;
+    region?: string;
+    endpoint?: string;
+    voice?: string;
+    lang?: string;
+    schemaVersion?: string;
+    fingerprintSchemaVersion?: string;
+    customHeaders?: Readonly<Record<string, string>>;
+}
+declare function computeChunkFingerprint(ssml: string, outputFormat?: string, options?: Omit<ChunkFingerprintOptions, "outputFormat">): string;
 interface MergeSynthesisOptions extends MergeAudioOptions {
     customMerger?: CustomAudioMerger;
     postMergeValidator?: PostMergeValidator;
+    deadline?: DeadlineController;
 }
 type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
     customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
@@ -417,6 +496,7 @@ declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | und
 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;
+/** Synthesizes one SSML document, optionally retrying transient failures within the job deadline. */
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
 /** Synthesizes chunks with bounded concurrency, retries transient failures, and merges in chunk order. */
 declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
@@ -456,4 +536,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 { AudioFormatMismatchError, type AudioSpecification, type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, BatchChunkValidationError, type ChunkDiagnostics, ChunkValidationError, type CustomAudioMerger, type CustomMergerContext, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type InputAudioSpecs, type MappingStatus, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type PartialChunkSynthesisResult, type PartialSynthesisResult, type PostMergeValidator, 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 SynthesisTimeouts, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type SynthesizedChunk, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, getRetryAfterDelayMs, inspectAudioSpecification, 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, BatchChunkValidationError, type ChunkDiagnostics, type ChunkExecutionState, type ChunkExecutionStatus, type ChunkFingerprintOptions, ChunkValidationError, type CustomAudioMerger, type CustomMergerContext, DEFAULT_OUTPUT_FORMAT, DeadlineController, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, IncompleteChunkSetError, type InputAudioSpecs, type MappingStatus, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type PartialChunkSynthesisResult, type PartialSynthesisResult, type PostMergeValidator, type Result, type ResumeValidationMode, type RetryOptions, type SerializedChunkError, type SerializedChunkErrorCode, type SerializedExecutionError, 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 SynthesisTimeouts, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type SynthesizedChunk, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, computeChunkFingerprint, fetchAzureVoiceCatalog, getRetryAfterDelayMs, inspectAudioSpecification, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, serializeChunkError, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidationRunnerOptions, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, Diagnostic, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SplitSsmlOptions, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlChunk, SsmlChunkContext, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlSourceMap, SsmlSourceMarker, SsmlSourceTextSegment, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, getSsmlSourceMap, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateAzureSsmlChunks, validateSsml, validateSsmlStructureIntegrity } from './core.js';
-import { S as SsmlTextRange, a as SsmlSourceTextSegment, b as SsmlSourceMarker, c as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-tpKoP1jl.js';
+import { b as SsmlTextRange, c as SsmlSourceTextSegment, d as SsmlSourceMarker, e as SsmlDiagnostic, f as AzureValidationOptions } from './index.d-4kqVuH29.js';
 import * as SpeechSDK from 'microsoft-cognitiveservices-speech-sdk';
 
 declare const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
@@ -47,6 +47,68 @@ declare const OUTPUT_FORMATS: {
 type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
 declare function resolveMimeType(outputFormat: string): string;
 
+type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "audio-format-mismatch" | "unsupported-format-error" | "cancelled" | "timeout" | "incomplete-chunk-set";
+type SerializedChunkErrorCode = "VALIDATION_ERROR" | "AZURE_API_ERROR" | "TIMEOUT" | "CANCELLED" | "MERGE_ERROR" | "FORMAT_MISMATCH";
+interface SerializedChunkError {
+    code: SerializedChunkErrorCode;
+    phase: "url-validation" | "synthesis" | "merge";
+    message: string;
+    isOriginalFailure: boolean;
+    isRetryable: boolean;
+    httpStatus?: number;
+    details?: Record<string, unknown>;
+}
+/** Backward-compatible name used by persisted execution-state consumers. */
+type SerializedExecutionError = SerializedChunkError;
+declare class AzureTtsError extends Error {
+    readonly kind: "azure-api-error";
+    readonly status: number;
+    readonly statusText: string;
+    readonly responseBody: string;
+    readonly requestId: string | null;
+    readonly retryAfterMs?: number;
+    constructor(status: number, statusText: string, responseBody: string, requestId: string | null, responseHeaders?: Headers | Readonly<Record<string, string>>);
+}
+/** Reads Retry-After from an error-like value, returning milliseconds when present. */
+declare function getRetryAfterDelayMs(error: unknown): number | undefined;
+declare class AzureTtsSdkError extends AzureTtsError {
+    readonly errorDetails: string;
+    constructor(errorDetails: string);
+}
+declare class SynthesisCancelledError extends Error {
+    readonly kind: "cancelled";
+    constructor(message?: string);
+}
+declare class SynthesisTimeoutError extends Error {
+    readonly kind: "timeout";
+    constructor(message: string);
+}
+declare class IncompleteChunkSetError extends Error {
+    readonly kind: "incomplete-chunk-set";
+    readonly totalChunks: number;
+    readonly missingChunkIndices: readonly number[];
+    constructor(totalChunks: number, missingChunkIndices: readonly number[]);
+}
+declare class MergeError extends Error {
+    readonly kind: "merge-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 | AudioFormatMismatchError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError | IncompleteChunkSetError;
+declare function serializeChunkError(error: unknown, phase: SerializedChunkError["phase"], isOriginalFailure: boolean): SerializedChunkError;
+
 interface TtsConfig {
     signal?: AbortSignal;
     timeoutMs?: number;
@@ -55,6 +117,8 @@ 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;
@@ -76,12 +140,13 @@ interface TtsConfig {
     customMerger?: CustomAudioMerger;
     outputMimeType?: string;
     postMergeValidator?: PostMergeValidator;
+    resumeValidation?: ResumeValidationMode;
 }
 type MappingStatus = "exact" | "fallback" | "unmapped";
 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;
@@ -90,6 +155,7 @@ interface AudioSpecification {
     isVbr?: boolean;
     isCompressed: boolean;
 }
+type ResumeValidationMode = "strict" | "disabled";
 interface SynthesisTimeouts {
     urlValidationMs?: number;
     perChunkMs?: number;
@@ -188,6 +254,8 @@ interface SsmlSynthesisChunk {
 interface SynthesizeChunksOptions {
     onProgress?: (event: SynthesisProgressEvent) => void;
     outputFormat?: AzureTtsOutputFormat | string;
+    customHeaders?: Readonly<Record<string, string>>;
+    fingerprintSchemaVersion?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
     timeouts?: SynthesisTimeouts;
@@ -200,6 +268,7 @@ interface SynthesizeChunksOptions {
     customMerger?: CustomAudioMerger;
     outputMimeType?: string;
     postMergeValidator?: PostMergeValidator;
+    resumeValidation?: ResumeValidationMode;
 }
 interface CustomMergerContext {
     format: string;
@@ -211,12 +280,25 @@ type CustomAudioMerger = (buffers: ArrayBuffer[], context: CustomMergerContext)
 type PostMergeValidator = (result: MergedSynthesisResult, context: CustomMergerContext) => boolean | undefined | Promise<boolean | undefined>;
 interface SynthesizedChunk extends SsmlSynthesisResult {
     chunkIndex: number;
+    /** Fingerprint of the SSML and synthesis settings used to create this chunk. */
+    fingerprint: string;
+}
+type ChunkExecutionStatus = "succeeded" | "failed" | "cancelled" | "pending";
+interface ChunkExecutionState {
+    chunkIndex: number;
+    status: ChunkExecutionStatus;
+    error?: SerializedChunkError;
+    isOriginalFailure?: boolean;
+    canResume: boolean;
+    result?: SsmlSynthesisResult;
 }
 interface PartialChunkSynthesisResult {
     synthesizedChunks: readonly SynthesizedChunk[];
     completedChunks: readonly SynthesizedChunk[];
     pendingChunkIndices: readonly number[];
     failedChunkIndices: readonly number[];
+    cancelledChunkIndices: readonly number[];
+    chunkStates: readonly ChunkExecutionState[];
     totalChunks: number;
 }
 /** Alias for applications that use the shorter result name. */
@@ -249,54 +331,31 @@ 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;
 }
 
-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;
-    readonly statusText: string;
-    readonly responseBody: string;
-    readonly requestId: string | null;
-    readonly retryAfterMs?: number;
-    constructor(status: number, statusText: string, responseBody: string, requestId: string | null, responseHeaders?: Headers | Readonly<Record<string, string>>);
-}
-/** Reads Retry-After from an error-like value, returning milliseconds when present. */
-declare function getRetryAfterDelayMs(error: unknown): number | undefined;
-declare class AzureTtsSdkError extends AzureTtsError {
-    readonly errorDetails: string;
-    constructor(errorDetails: string);
-}
-declare class SynthesisCancelledError extends Error {
-    readonly kind: "cancelled";
-    constructor(message?: string);
-}
-declare class SynthesisTimeoutError extends Error {
-    readonly kind: "timeout";
-    constructor(message: string);
-}
-declare class MergeError extends Error {
-    readonly kind: "merge-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);
+/** Coordinates one absolute deadline across validation, synthesis, retries, and merging. */
+declare class DeadlineController {
+    #private;
+    readonly deadlineAtMs: number | undefined;
+    readonly signal: AbortSignal;
+    constructor(totalJobMs: number | undefined, parent?: AbortSignal);
+    get timedOut(): boolean;
+    get remainingMs(): number;
+    throwIfExpired(): void;
+    abort(): void;
+    dispose(): void;
 }
-type AzureTtsSynthesisError = AzureTtsError | MergeError | AudioFormatMismatchError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
 
 interface SsmlValidationError {
     readonly kind: "validation-error";
@@ -361,6 +420,8 @@ interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
 interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     validation?: AzureValidationOptions;
     outputFormat?: string;
+    customHeaders?: Readonly<Record<string, string>>;
+    fingerprintSchemaVersion?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
     timeouts?: SynthesisTimeouts;
@@ -374,6 +435,7 @@ interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
     customMerger?: CustomAudioMerger;
     outputMimeType?: string;
     postMergeValidator?: PostMergeValidator;
+    resumeValidation?: ResumeValidationMode;
 }
 type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, BatchChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
 interface SynthesisClient {
@@ -403,9 +465,26 @@ interface MergeAudioOptions {
     outputMimeType?: string;
 }
 type InputAudioSpecs = AudioSpecification[];
+/**
+ * Creates a deterministic, runtime-independent fingerprint for a synthesis chunk.
+ * The complete SSML is included so changes to voice, language, prosody, or text
+ * invalidate a cached result even when those settings are nested in the markup.
+ */
+interface ChunkFingerprintOptions {
+    outputFormat?: string;
+    region?: string;
+    endpoint?: string;
+    voice?: string;
+    lang?: string;
+    schemaVersion?: string;
+    fingerprintSchemaVersion?: string;
+    customHeaders?: Readonly<Record<string, string>>;
+}
+declare function computeChunkFingerprint(ssml: string, outputFormat?: string, options?: Omit<ChunkFingerprintOptions, "outputFormat">): string;
 interface MergeSynthesisOptions extends MergeAudioOptions {
     customMerger?: CustomAudioMerger;
     postMergeValidator?: PostMergeValidator;
+    deadline?: DeadlineController;
 }
 type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
     customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
@@ -417,6 +496,7 @@ declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | und
 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;
+/** Synthesizes one SSML document, optionally retrying transient failures within the job deadline. */
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
 /** Synthesizes chunks with bounded concurrency, retries transient failures, and merges in chunk order. */
 declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
@@ -456,4 +536,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 { AudioFormatMismatchError, type AudioSpecification, type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, BatchChunkValidationError, type ChunkDiagnostics, ChunkValidationError, type CustomAudioMerger, type CustomMergerContext, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type InputAudioSpecs, type MappingStatus, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type PartialChunkSynthesisResult, type PartialSynthesisResult, type PostMergeValidator, 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 SynthesisTimeouts, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type SynthesizedChunk, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, getRetryAfterDelayMs, inspectAudioSpecification, 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, BatchChunkValidationError, type ChunkDiagnostics, type ChunkExecutionState, type ChunkExecutionStatus, type ChunkFingerprintOptions, ChunkValidationError, type CustomAudioMerger, type CustomMergerContext, DEFAULT_OUTPUT_FORMAT, DeadlineController, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, IncompleteChunkSetError, type InputAudioSpecs, type MappingStatus, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type PartialChunkSynthesisResult, type PartialSynthesisResult, type PostMergeValidator, type Result, type ResumeValidationMode, type RetryOptions, type SerializedChunkError, type SerializedChunkErrorCode, type SerializedExecutionError, 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 SynthesisTimeouts, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type SynthesizedChunk, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, computeChunkFingerprint, fetchAzureVoiceCatalog, getRetryAfterDelayMs, inspectAudioSpecification, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, serializeChunkError, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };