ssml-builder-js 2.12.0 → 2.13.0

package/dist/index.d-Xbr6ZWnK.d.mts

@@ -0,0 +1,214 @@
+type SsmlAttributeValue = string | number;
+type SsmlAttributes = Record<string, SsmlAttributeValue>;
+interface SsmlText {
+    type: "text";
+    value: string;
+}
+type SsmlNode = string | SsmlText | SsmlElement;
+interface SsmlElementBase {
+    children?: SsmlNode[];
+    attributes?: SsmlAttributes;
+}
+interface VoiceElement extends SsmlElementBase {
+    type: "voice";
+    name?: string;
+    effect?: string;
+}
+interface ProsodyElement extends SsmlElementBase {
+    type: "prosody";
+    rate?: SsmlAttributeValue;
+    pitch?: SsmlAttributeValue;
+    volume?: SsmlAttributeValue;
+    contour?: string;
+    range?: SsmlAttributeValue;
+}
+interface BreakElement extends SsmlElementBase {
+    type: "break";
+    time?: SsmlAttributeValue;
+    strength?: string;
+}
+interface ExpressAsElement extends SsmlElementBase {
+    type: "express-as" | "expressAs" | "mstts:express-as";
+    style?: string;
+    styleDegree?: SsmlAttributeValue;
+    role?: string;
+}
+interface SayAsElement extends SsmlElementBase {
+    type: "say-as" | "sayAs";
+    interpretAs?: string;
+    format?: string;
+    detail?: string;
+}
+interface PhonemeElement extends SsmlElementBase {
+    type: "phoneme";
+    alphabet?: string;
+    ph?: string;
+}
+interface EmphasisElement extends SsmlElementBase {
+    type: "emphasis";
+    level?: string;
+}
+interface AudioElement extends SsmlElementBase {
+    type: "audio";
+    src?: string;
+    desc?: string;
+    clipBegin?: SsmlAttributeValue;
+    clipEnd?: SsmlAttributeValue;
+    speed?: SsmlAttributeValue;
+    repeatCount?: SsmlAttributeValue;
+    repeatDuration?: SsmlAttributeValue;
+    soundLevel?: SsmlAttributeValue;
+}
+interface SubElement extends SsmlElementBase {
+    type: "sub";
+    alias?: string;
+}
+interface LangElement extends SsmlElementBase {
+    type: "lang";
+    lang?: string;
+}
+interface MarkElement extends SsmlElementBase {
+    type: "mark";
+    name?: string;
+}
+interface BookmarkElement extends SsmlElementBase {
+    type: "bookmark";
+    mark?: string;
+}
+interface LexiconElement extends SsmlElementBase {
+    type: "lexicon";
+    uri?: string;
+}
+interface ParagraphElement extends SsmlElementBase {
+    type: "p";
+}
+interface SentenceElement extends SsmlElementBase {
+    type: "s";
+}
+interface WordElement extends SsmlElementBase {
+    type: "w";
+}
+interface MsttsSilenceElement extends SsmlElementBase {
+    type: "mstts:silence" | "silence";
+    typeValue?: string;
+    silenceType?: string;
+    value?: SsmlAttributeValue;
+}
+interface MsttsVisemeElement extends SsmlElementBase {
+    type: "mstts:viseme" | "viseme";
+    typeValue?: string;
+    visemeType?: string;
+}
+interface MsttsAudioDurationElement extends SsmlElementBase {
+    type: "mstts:audioduration";
+    value?: SsmlAttributeValue;
+}
+interface SsmlDialogNode extends SsmlElementBase {
+    type: "mstts:dialog";
+}
+interface SsmlTurnNode extends SsmlElementBase {
+    type: "mstts:turn";
+    voice?: string;
+    speaker?: string;
+}
+interface SsmlBackgroundAudioNode extends SsmlElementBase {
+    type: "mstts:backgroundaudio";
+    src?: string;
+    volume?: SsmlAttributeValue;
+    fadeIn?: SsmlAttributeValue;
+    fadeOut?: SsmlAttributeValue;
+    /** XML spelling aliases retained for ergonomic object construction. */
+    fadein?: SsmlAttributeValue;
+    fadeout?: SsmlAttributeValue;
+}
+interface MsttsTtsEmbeddingElement extends SsmlElementBase {
+    type: "mstts:ttsembedding";
+    speakerProfileId?: string;
+}
+interface MsttsEmbeddingElement extends SsmlElementBase {
+    type: "mstts:embedding";
+    id?: string;
+    speakerProfileId?: string;
+}
+interface MsttsVoiceConversionElement extends SsmlElementBase {
+    type: "mstts:voiceconversion";
+    url?: string;
+    profile?: string;
+    speakerProfileId?: string;
+}
+interface CustomElement extends SsmlElementBase {
+    type: "custom" | "element";
+    name: string;
+}
+type SsmlElement = VoiceElement | ProsodyElement | BreakElement | ExpressAsElement | SayAsElement | PhonemeElement | EmphasisElement | AudioElement | SubElement | LangElement | MarkElement | BookmarkElement | LexiconElement | ParagraphElement | SentenceElement | WordElement | MsttsSilenceElement | MsttsVisemeElement | MsttsAudioDurationElement | SsmlDialogNode | SsmlTurnNode | SsmlBackgroundAudioNode | MsttsTtsEmbeddingElement | MsttsEmbeddingElement | MsttsVoiceConversionElement | CustomElement;
+interface SsmlDocument {
+    type?: "speak";
+    version: string;
+    lang: string;
+    children?: SsmlNode[];
+    /** @deprecated Use children to represent the document body. */
+    content?: string;
+    attributes?: SsmlAttributes;
+}
+
+type SsmlDiagnosticSeverity = "error" | "warning" | "info";
+type SsmlDiagnosticSource = "ssml-static-validator";
+type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch" | "azure-unsupported-tag-for-voice" | "azure-unsupported-model-for-voice" | "azure-preview-voice" | "azure-deprecated-voice" | "azure-preview-tag" | "azure-deprecated-tag";
+interface SsmlDiagnostic {
+    code?: AzureDiagnosticCode;
+    line: number;
+    column: number;
+    message: string;
+    severity: SsmlDiagnosticSeverity;
+    source: SsmlDiagnosticSource;
+}
+interface AzureVoiceDefinition {
+    name: string;
+    locale: string;
+    secondaryLocales?: readonly string[];
+    styles?: readonly string[];
+    supportedTags?: readonly string[];
+    unsupportedTags?: readonly string[];
+    models?: readonly string[];
+    regions?: readonly string[];
+    status?: "ga" | "preview" | "deprecated";
+}
+interface AzureValidationOptions {
+    allowedAudioOrigins?: readonly string[];
+    allowExternalAudio?: boolean;
+    allowHttpAudio?: boolean;
+    customVoiceStyleMap?: Record<string, readonly string[]>;
+    customVoiceDefinitions?: readonly AzureVoiceDefinition[];
+    /** Host-side validation hook for URL-bearing SSML attributes. */
+    urlValidator?: AzureUrlValidator;
+    /** Alias for urlValidator retained for applications that use the longer name. */
+    customUrlValidator?: AzureUrlValidator;
+    languageAliases?: Record<string, string | readonly string[]>;
+    maxLength?: number;
+    /** Maximum XML element nesting depth, counting `<speak>` as depth 1. */
+    maxXmlDepth?: number;
+    /** Optional model identifier used to validate a voice's model compatibility. */
+    model?: string;
+    normalizeLanguage?: (lang: string) => string;
+    /** Overrides the built-in preview tag list for this validation run. */
+    previewTags?: readonly string[];
+    /** Adds tags that should be reported as deprecated for this validation run. */
+    deprecatedTags?: readonly string[];
+    /** Explicit tag lifecycle metadata. This takes precedence over previewTags/deprecatedTags. */
+    tagStatuses?: Readonly<Record<string, "ga" | "preview" | "deprecated">>;
+    unknownVoicePolicy?: "error" | "warn" | "ignore";
+    unsupportedStylePolicy?: "error" | "warn" | "ignore";
+    validateNestedVoices?: boolean;
+    voiceCatalog?: readonly AzureVoiceDefinition[];
+    voiceDefinitions?: readonly AzureVoiceDefinition[];
+}
+type AzureUrlValidationResult = boolean | {
+    valid: boolean;
+    reason?: string;
+};
+type AzureUrlValidator = (url: string, context: {
+    tag: string;
+    attribute: string;
+}) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
+
+export type { AzureValidationOptions as A, SsmlDiagnostic as S, SsmlDocument as a, SsmlElement as b };

package/dist/index.d-Xbr6ZWnK.d.ts

@@ -0,0 +1,214 @@
+type SsmlAttributeValue = string | number;
+type SsmlAttributes = Record<string, SsmlAttributeValue>;
+interface SsmlText {
+    type: "text";
+    value: string;
+}
+type SsmlNode = string | SsmlText | SsmlElement;
+interface SsmlElementBase {
+    children?: SsmlNode[];
+    attributes?: SsmlAttributes;
+}
+interface VoiceElement extends SsmlElementBase {
+    type: "voice";
+    name?: string;
+    effect?: string;
+}
+interface ProsodyElement extends SsmlElementBase {
+    type: "prosody";
+    rate?: SsmlAttributeValue;
+    pitch?: SsmlAttributeValue;
+    volume?: SsmlAttributeValue;
+    contour?: string;
+    range?: SsmlAttributeValue;
+}
+interface BreakElement extends SsmlElementBase {
+    type: "break";
+    time?: SsmlAttributeValue;
+    strength?: string;
+}
+interface ExpressAsElement extends SsmlElementBase {
+    type: "express-as" | "expressAs" | "mstts:express-as";
+    style?: string;
+    styleDegree?: SsmlAttributeValue;
+    role?: string;
+}
+interface SayAsElement extends SsmlElementBase {
+    type: "say-as" | "sayAs";
+    interpretAs?: string;
+    format?: string;
+    detail?: string;
+}
+interface PhonemeElement extends SsmlElementBase {
+    type: "phoneme";
+    alphabet?: string;
+    ph?: string;
+}
+interface EmphasisElement extends SsmlElementBase {
+    type: "emphasis";
+    level?: string;
+}
+interface AudioElement extends SsmlElementBase {
+    type: "audio";
+    src?: string;
+    desc?: string;
+    clipBegin?: SsmlAttributeValue;
+    clipEnd?: SsmlAttributeValue;
+    speed?: SsmlAttributeValue;
+    repeatCount?: SsmlAttributeValue;
+    repeatDuration?: SsmlAttributeValue;
+    soundLevel?: SsmlAttributeValue;
+}
+interface SubElement extends SsmlElementBase {
+    type: "sub";
+    alias?: string;
+}
+interface LangElement extends SsmlElementBase {
+    type: "lang";
+    lang?: string;
+}
+interface MarkElement extends SsmlElementBase {
+    type: "mark";
+    name?: string;
+}
+interface BookmarkElement extends SsmlElementBase {
+    type: "bookmark";
+    mark?: string;
+}
+interface LexiconElement extends SsmlElementBase {
+    type: "lexicon";
+    uri?: string;
+}
+interface ParagraphElement extends SsmlElementBase {
+    type: "p";
+}
+interface SentenceElement extends SsmlElementBase {
+    type: "s";
+}
+interface WordElement extends SsmlElementBase {
+    type: "w";
+}
+interface MsttsSilenceElement extends SsmlElementBase {
+    type: "mstts:silence" | "silence";
+    typeValue?: string;
+    silenceType?: string;
+    value?: SsmlAttributeValue;
+}
+interface MsttsVisemeElement extends SsmlElementBase {
+    type: "mstts:viseme" | "viseme";
+    typeValue?: string;
+    visemeType?: string;
+}
+interface MsttsAudioDurationElement extends SsmlElementBase {
+    type: "mstts:audioduration";
+    value?: SsmlAttributeValue;
+}
+interface SsmlDialogNode extends SsmlElementBase {
+    type: "mstts:dialog";
+}
+interface SsmlTurnNode extends SsmlElementBase {
+    type: "mstts:turn";
+    voice?: string;
+    speaker?: string;
+}
+interface SsmlBackgroundAudioNode extends SsmlElementBase {
+    type: "mstts:backgroundaudio";
+    src?: string;
+    volume?: SsmlAttributeValue;
+    fadeIn?: SsmlAttributeValue;
+    fadeOut?: SsmlAttributeValue;
+    /** XML spelling aliases retained for ergonomic object construction. */
+    fadein?: SsmlAttributeValue;
+    fadeout?: SsmlAttributeValue;
+}
+interface MsttsTtsEmbeddingElement extends SsmlElementBase {
+    type: "mstts:ttsembedding";
+    speakerProfileId?: string;
+}
+interface MsttsEmbeddingElement extends SsmlElementBase {
+    type: "mstts:embedding";
+    id?: string;
+    speakerProfileId?: string;
+}
+interface MsttsVoiceConversionElement extends SsmlElementBase {
+    type: "mstts:voiceconversion";
+    url?: string;
+    profile?: string;
+    speakerProfileId?: string;
+}
+interface CustomElement extends SsmlElementBase {
+    type: "custom" | "element";
+    name: string;
+}
+type SsmlElement = VoiceElement | ProsodyElement | BreakElement | ExpressAsElement | SayAsElement | PhonemeElement | EmphasisElement | AudioElement | SubElement | LangElement | MarkElement | BookmarkElement | LexiconElement | ParagraphElement | SentenceElement | WordElement | MsttsSilenceElement | MsttsVisemeElement | MsttsAudioDurationElement | SsmlDialogNode | SsmlTurnNode | SsmlBackgroundAudioNode | MsttsTtsEmbeddingElement | MsttsEmbeddingElement | MsttsVoiceConversionElement | CustomElement;
+interface SsmlDocument {
+    type?: "speak";
+    version: string;
+    lang: string;
+    children?: SsmlNode[];
+    /** @deprecated Use children to represent the document body. */
+    content?: string;
+    attributes?: SsmlAttributes;
+}
+
+type SsmlDiagnosticSeverity = "error" | "warning" | "info";
+type SsmlDiagnosticSource = "ssml-static-validator";
+type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch" | "azure-unsupported-tag-for-voice" | "azure-unsupported-model-for-voice" | "azure-preview-voice" | "azure-deprecated-voice" | "azure-preview-tag" | "azure-deprecated-tag";
+interface SsmlDiagnostic {
+    code?: AzureDiagnosticCode;
+    line: number;
+    column: number;
+    message: string;
+    severity: SsmlDiagnosticSeverity;
+    source: SsmlDiagnosticSource;
+}
+interface AzureVoiceDefinition {
+    name: string;
+    locale: string;
+    secondaryLocales?: readonly string[];
+    styles?: readonly string[];
+    supportedTags?: readonly string[];
+    unsupportedTags?: readonly string[];
+    models?: readonly string[];
+    regions?: readonly string[];
+    status?: "ga" | "preview" | "deprecated";
+}
+interface AzureValidationOptions {
+    allowedAudioOrigins?: readonly string[];
+    allowExternalAudio?: boolean;
+    allowHttpAudio?: boolean;
+    customVoiceStyleMap?: Record<string, readonly string[]>;
+    customVoiceDefinitions?: readonly AzureVoiceDefinition[];
+    /** Host-side validation hook for URL-bearing SSML attributes. */
+    urlValidator?: AzureUrlValidator;
+    /** Alias for urlValidator retained for applications that use the longer name. */
+    customUrlValidator?: AzureUrlValidator;
+    languageAliases?: Record<string, string | readonly string[]>;
+    maxLength?: number;
+    /** Maximum XML element nesting depth, counting `<speak>` as depth 1. */
+    maxXmlDepth?: number;
+    /** Optional model identifier used to validate a voice's model compatibility. */
+    model?: string;
+    normalizeLanguage?: (lang: string) => string;
+    /** Overrides the built-in preview tag list for this validation run. */
+    previewTags?: readonly string[];
+    /** Adds tags that should be reported as deprecated for this validation run. */
+    deprecatedTags?: readonly string[];
+    /** Explicit tag lifecycle metadata. This takes precedence over previewTags/deprecatedTags. */
+    tagStatuses?: Readonly<Record<string, "ga" | "preview" | "deprecated">>;
+    unknownVoicePolicy?: "error" | "warn" | "ignore";
+    unsupportedStylePolicy?: "error" | "warn" | "ignore";
+    validateNestedVoices?: boolean;
+    voiceCatalog?: readonly AzureVoiceDefinition[];
+    voiceDefinitions?: readonly AzureVoiceDefinition[];
+}
+type AzureUrlValidationResult = boolean | {
+    valid: boolean;
+    reason?: string;
+};
+type AzureUrlValidator = (url: string, context: {
+    tag: string;
+    attribute: string;
+}) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
+
+export type { AzureValidationOptions as A, SsmlDiagnostic as S, SsmlDocument as a, SsmlElement as b };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, ExtractSsmlTranslatableTextOptions, FromPlainTextToSsmlOptions, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsAudioDurationElement, MsttsEmbeddingElement, MsttsSilenceElement, MsttsTtsEmbeddingElement, MsttsVisemeElement, MsttsVoiceConversionElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SsmlAttributeValue, SsmlAttributes, SsmlBackgroundAudioNode, SsmlBreakElement, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDiagnosticSource, SsmlDialogNode, SsmlDocument, SsmlElement, SsmlElementBase, SsmlEmbeddingNode, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity } from './core.mjs';
+export { AudioElement, AzureDiagnosticCode, AzureLanguageNormalizationOptions, AzureSsmlValidationOptions, AzureUrlValidationResult, AzureUrlValidator, AzureValidationOptions, AzureVoiceCatalogMetadata, AzureVoiceDefinition, AzureVoiceMetadata, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, 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, SsmlStructureIntegrityResult, SsmlStructureMismatch, SsmlText, SsmlTextNodeContext, SsmlTextRange, SsmlTtsEmbeddingNode, SsmlTurnNode, SsmlValidationError, SsmlVoiceConversionNode, SsmlVoiceElement, SubElement, VoiceElement, WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity } from './core.mjs';
+import { S as SsmlDiagnostic, A as AzureValidationOptions } from './index.d-Xbr6ZWnK.mjs';
 
 interface TtsConfig {
     signal?: AbortSignal;
@@ -7,19 +8,45 @@ interface TtsConfig {
     subscriptionKey: string;
     region: string;
     outputFormat?: string;
+    /** Original plain-text range represented by this synthesis request. */
+    sourceTextRange?: {
+        start: number;
+        end: number;
+    };
+    /** Reports completion of a chunk when using synthesizeSsmlChunks. */
+    onProgress?: (event: {
+        currentChunk: number;
+        totalChunks: number;
+        percent: number;
+    }) => void;
 }
 interface SsmlSynthesisBoundary {
     text: string;
     audioOffsetMs: number;
     durationMs: number;
+    textRange?: {
+        start: number;
+        end: number;
+    };
+    requestId?: string;
 }
 interface SsmlSynthesisViseme {
     visemeId: number;
     audioOffsetMs: number;
+    textRange?: {
+        start: number;
+        end: number;
+    };
+    requestId?: string;
 }
 interface SsmlSynthesisBookmark {
     name: string;
     audioOffsetMs: number;
+    textRange?: {
+        start: number;
+        end: number;
+    };
+    requestId?: string;
 }
 /** Audio and Azure Speech synchronization events emitted for one SSML request. */
 interface SsmlSynthesisResult {
@@ -32,6 +59,28 @@ interface SsmlSynthesisResult {
     wordBoundaries?: SsmlSynthesisBoundary[];
     visemes?: SsmlSynthesisViseme[];
     bookmarks?: SsmlSynthesisBookmark[];
+    /** Request identifier returned by Azure Speech, when available. */
+    requestId?: string;
+    /** Original plain-text range represented by the result. */
+    textRange?: {
+        start: number;
+        end: number;
+    };
+}
+interface SsmlSynthesisChunk {
+    ssml: string;
+    originalTextRange?: {
+        start: number;
+        end: number;
+    };
+}
+interface SynthesizeChunksOptions {
+    onProgress?: (event: SynthesisProgressEvent) => void;
+}
+interface SynthesisProgressEvent {
+    currentChunk: number;
+    totalChunks: number;
+    percent: number;
 }
 interface AzureTtsLogger {
     debug?: (...args: unknown[]) => void;
@@ -47,6 +96,7 @@ interface AzureTtsClientOptions {
     endpoint?: string;
     outputFormat?: string;
     logger?: AzureTtsLogger;
+    onProgress?: (event: SynthesisProgressEvent) => void;
 }
 
 declare class AzureTtsError extends Error {
@@ -61,14 +111,57 @@ declare class AzureTtsSdkError extends AzureTtsError {
     constructor(errorDetails: string);
 }
 
+interface SsmlValidationError {
+    readonly kind: "validation";
+    readonly message: string;
+    readonly diagnostics: readonly SsmlDiagnostic[];
+}
+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;
+};
+type SynthesisResult<T, E> = Result<T, E>;
+type Success<T> = Extract<Result<T, never>, {
+    readonly ok: true;
+}>;
+type ValidationErrorResult = Extract<Result<never, SsmlValidationError>, {
+    readonly status: "validation-error";
+}>;
+type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, {
+    readonly status: "azure-api-error";
+}>;
+type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, AzureTtsError>;
+interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
+    /** Optional nested form for callers that want to keep validation settings grouped. */
+    validation?: AzureValidationOptions;
+}
+interface SynthesisClient {
+    synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
+}
+/** Validates SSML before invoking Azure and converts validation/API failures to one result shape. */
+declare function synthesizeSsmlSafe(client: Pick<AzureTtsClient, "synthesizeSsml"> | SynthesisClient, ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
+
 declare class AzureTtsClient {
     #private;
     constructor(options: AzureTtsClientOptions);
     synthesize(ssml: string): Promise<ArrayBuffer>;
     synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
+    synthesizeChunks(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
+    synthesizeSsmlSafe(ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
 }
 
 declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
+/** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
+declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
+/** Concatenates audio buffers and shifts all synchronization events by prior chunk durations. */
+declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[]): SsmlSynthesisResult;
 /** Backward-compatible audio-only synthesis helper. */
 declare function synthesizeSpeech(ssml: string, config: TtsConfig): Promise<ArrayBuffer>;
 
@@ -97,4 +190,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 { AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, AzureTtsSdkError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisResult, type SsmlSynthesisViseme, type TtsConfig, fetchAzureVoiceCatalog, synthesizeSpeech, synthesizeSsml };
+export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, AzureTtsSdkError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, type SynthesisProgressEvent, type SynthesisResult, type SynthesizeChunksOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, type ValidationErrorResult, fetchAzureVoiceCatalog, mergeSynthesisResults, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlSafe };