ssml-builder-js 2.8.0 → 2.9.0

package/dist/core.d.mts

@@ -99,11 +99,44 @@ interface MsttsVisemeElement extends SsmlElementBase {
     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;
+}
+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";
+}
+interface MsttsEmbeddingElement extends SsmlElementBase {
+    type: "mstts:embedding";
+}
+interface MsttsVoiceConversionElement extends SsmlElementBase {
+    type: "mstts:voiceconversion";
+}
+type SsmlTtsEmbeddingNode = MsttsTtsEmbeddingElement;
+type SsmlEmbeddingNode = MsttsEmbeddingElement;
+type SsmlVoiceConversionNode = MsttsVoiceConversionElement;
 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 | CustomElement;
+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;
@@ -171,9 +204,51 @@ interface MapSsmlTextNodesOptions {
 declare function extractSsmlText(ssml: string): string[];
 declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
 
+interface ExtractSsmlTranslatableTextOptions {
+    /** Element names whose descendants are not translation targets. */
+    skipTags?: readonly string[];
+    /** Include indentation and whitespace-only text nodes. Defaults to false. */
+    includeWhitespace?: boolean;
+    /** Further restrict text nodes after the skip-tag check. */
+    filter?: (context: SsmlTextNodeContext) => boolean;
+}
+interface FromPlainTextToSsmlOptions {
+    version?: string;
+    lang?: string;
+    /** Alias for lang, useful when options come from an application form. */
+    language?: string;
+    /** Wrap generated paragraphs in a voice element. */
+    voice?: string;
+    /** Alias for voice. */
+    voiceName?: string;
+    /** Generate sentence elements inside paragraphs. Defaults to true. */
+    includeSentences?: boolean;
+    /** Alias for includeSentences. */
+    splitSentences?: boolean;
+}
+interface SsmlStructureMismatch {
+    kind: "element" | "attribute" | "parse";
+    path: string;
+    original?: string;
+    translated?: string;
+    message: string;
+}
+interface SsmlStructureIntegrityResult {
+    isValid: boolean;
+    /** Alias for isValid for callers that prefer a shorter result property. */
+    valid: boolean;
+    errors: string[];
+    mismatches: SsmlStructureMismatch[];
+    /** Element or attribute names involved in each mismatch. */
+    mismatchedTags: string[];
+}
+declare function extractSsmlTranslatableText(ssml: string, options?: ExtractSsmlTranslatableTextOptions): string[];
+declare function fromPlainTextToSsml(text: string, options?: FromPlainTextToSsmlOptions): string;
+declare function validateSsmlStructureIntegrity(originalSsml: string, translatedSsml: string): SsmlStructureIntegrityResult;
+
 type SsmlDiagnosticSeverity = "error" | "warning";
 type SsmlDiagnosticSource = "ssml-static-validator";
-type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch";
+type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch" | "azure-unsupported-tag-for-voice" | "azure-unsupported-model-for-voice";
 interface SsmlDiagnostic {
     code?: AzureDiagnosticCode;
     line: number;
@@ -187,6 +262,9 @@ interface AzureVoiceDefinition {
     locale: string;
     secondaryLocales?: readonly string[];
     styles?: readonly string[];
+    supportedTags?: readonly string[];
+    unsupportedTags?: readonly string[];
+    models?: readonly string[];
 }
 /** Alias retained for consumers that prefer the metadata terminology. */
 interface AzureVoiceMetadata extends AzureVoiceDefinition {
@@ -199,6 +277,8 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
+    /** Optional model identifier used to validate a voice's model compatibility. */
+    model?: string;
     normalizeLanguage?: (lang: string) => string;
     unknownVoicePolicy?: "error" | "warn" | "ignore";
     unsupportedStylePolicy?: "error" | "warn" | "ignore";
@@ -209,10 +289,24 @@ interface AzureValidationOptions {
 type AzureLanguageNormalizationOptions = Pick<AzureValidationOptions, "languageAliases" | "normalizeLanguage">;
 /** @deprecated Use AzureValidationOptions instead. */
 type AzureSsmlValidationOptions = AzureValidationOptions;
+/** Returns whether a value is a positive Azure SSML audio duration. */
+declare function isValidAzureAudioDuration(value: string): boolean;
 /** Normalizes an Azure language tag using BCP 47 and the configured aliases. */
 declare function normalizeAzureLanguage(language: string, options?: AzureLanguageNormalizationOptions): string;
 /** Compares two Azure language tags after BCP 47 and alias normalization. */
 declare function areAzureLanguagesEquivalent(first: string, second: string, options?: AzureLanguageNormalizationOptions): boolean;
 declare function validateAzureSsml(ssml: string, options?: AzureValidationOptions): SsmlDiagnostic[];
 
-export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureValidationOptions, type AzureVoiceDefinition, type AzureVoiceMetadata, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type LangElement, type LexiconElement, type MapSsmlTextNodesOptions, type MarkElement, type MsttsSilenceElement, type MsttsVisemeElement, type NamedElement, type ParagraphElement, type PhonemeElement, type ProsodyElement, type SayAsElement, type SentenceElement, type SsmlAttributeValue, type SsmlAttributes, type SsmlBreakElement, type SsmlDiagnostic, type SsmlDiagnosticSeverity, type SsmlDiagnosticSource, type SsmlDocument, type SsmlElement, type SsmlElementBase, type SsmlExpressAsElement, type SsmlNode, type SsmlPartialContext, type SsmlPartialProsody, type SsmlPartialVoice, type SsmlPhonemeElement, type SsmlProsodyElement, type SsmlSayAsElement, type SsmlText, type SsmlTextNodeContext, type SsmlValidationError, type SsmlVoiceElement, type SubElement, type VoiceElement, type WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, validateAzureSsml, validateSsml };
+interface AzureVoiceCatalogMetadata {
+    apiVersion: string;
+    generatedAt: string;
+    regions: readonly string[];
+    voiceCount: number;
+}
+
+/** Returns metadata for the built-in Azure voice catalog snapshot. */
+declare function getAzureVoiceCatalogMetadata(): AzureVoiceCatalogMetadata;
+/** Alias for consumers that refer to the bundled catalog as the built-in catalog. */
+declare const getBuiltInVoiceCatalogMetadata: typeof getAzureVoiceCatalogMetadata;
+
+export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureValidationOptions, type AzureVoiceCatalogMetadata, type AzureVoiceDefinition, type AzureVoiceMetadata, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type ExtractSsmlTranslatableTextOptions, type FromPlainTextToSsmlOptions, type LangElement, type LexiconElement, type MapSsmlTextNodesOptions, type MarkElement, type MsttsAudioDurationElement, type MsttsEmbeddingElement, type MsttsSilenceElement, type MsttsTtsEmbeddingElement, type MsttsVisemeElement, type MsttsVoiceConversionElement, type NamedElement, type ParagraphElement, type PhonemeElement, type ProsodyElement, type SayAsElement, type SentenceElement, type SsmlAttributeValue, type SsmlAttributes, type SsmlBackgroundAudioNode, type SsmlBreakElement, type SsmlDiagnostic, type SsmlDiagnosticSeverity, type SsmlDiagnosticSource, type SsmlDialogNode, type SsmlDocument, type SsmlElement, type SsmlElementBase, type SsmlEmbeddingNode, type SsmlExpressAsElement, type SsmlNode, type SsmlPartialContext, type SsmlPartialProsody, type SsmlPartialVoice, type SsmlPhonemeElement, type SsmlProsodyElement, type SsmlSayAsElement, type SsmlStructureIntegrityResult, type SsmlStructureMismatch, type SsmlText, type SsmlTextNodeContext, type SsmlTtsEmbeddingNode, type SsmlTurnNode, type SsmlValidationError, type SsmlVoiceConversionNode, type SsmlVoiceElement, type SubElement, type VoiceElement, type WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };

package/dist/core.d.ts

@@ -99,11 +99,44 @@ interface MsttsVisemeElement extends SsmlElementBase {
     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;
+}
+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";
+}
+interface MsttsEmbeddingElement extends SsmlElementBase {
+    type: "mstts:embedding";
+}
+interface MsttsVoiceConversionElement extends SsmlElementBase {
+    type: "mstts:voiceconversion";
+}
+type SsmlTtsEmbeddingNode = MsttsTtsEmbeddingElement;
+type SsmlEmbeddingNode = MsttsEmbeddingElement;
+type SsmlVoiceConversionNode = MsttsVoiceConversionElement;
 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 | CustomElement;
+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;
@@ -171,9 +204,51 @@ interface MapSsmlTextNodesOptions {
 declare function extractSsmlText(ssml: string): string[];
 declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
 
+interface ExtractSsmlTranslatableTextOptions {
+    /** Element names whose descendants are not translation targets. */
+    skipTags?: readonly string[];
+    /** Include indentation and whitespace-only text nodes. Defaults to false. */
+    includeWhitespace?: boolean;
+    /** Further restrict text nodes after the skip-tag check. */
+    filter?: (context: SsmlTextNodeContext) => boolean;
+}
+interface FromPlainTextToSsmlOptions {
+    version?: string;
+    lang?: string;
+    /** Alias for lang, useful when options come from an application form. */
+    language?: string;
+    /** Wrap generated paragraphs in a voice element. */
+    voice?: string;
+    /** Alias for voice. */
+    voiceName?: string;
+    /** Generate sentence elements inside paragraphs. Defaults to true. */
+    includeSentences?: boolean;
+    /** Alias for includeSentences. */
+    splitSentences?: boolean;
+}
+interface SsmlStructureMismatch {
+    kind: "element" | "attribute" | "parse";
+    path: string;
+    original?: string;
+    translated?: string;
+    message: string;
+}
+interface SsmlStructureIntegrityResult {
+    isValid: boolean;
+    /** Alias for isValid for callers that prefer a shorter result property. */
+    valid: boolean;
+    errors: string[];
+    mismatches: SsmlStructureMismatch[];
+    /** Element or attribute names involved in each mismatch. */
+    mismatchedTags: string[];
+}
+declare function extractSsmlTranslatableText(ssml: string, options?: ExtractSsmlTranslatableTextOptions): string[];
+declare function fromPlainTextToSsml(text: string, options?: FromPlainTextToSsmlOptions): string;
+declare function validateSsmlStructureIntegrity(originalSsml: string, translatedSsml: string): SsmlStructureIntegrityResult;
+
 type SsmlDiagnosticSeverity = "error" | "warning";
 type SsmlDiagnosticSource = "ssml-static-validator";
-type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch";
+type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch" | "azure-unsupported-tag-for-voice" | "azure-unsupported-model-for-voice";
 interface SsmlDiagnostic {
     code?: AzureDiagnosticCode;
     line: number;
@@ -187,6 +262,9 @@ interface AzureVoiceDefinition {
     locale: string;
     secondaryLocales?: readonly string[];
     styles?: readonly string[];
+    supportedTags?: readonly string[];
+    unsupportedTags?: readonly string[];
+    models?: readonly string[];
 }
 /** Alias retained for consumers that prefer the metadata terminology. */
 interface AzureVoiceMetadata extends AzureVoiceDefinition {
@@ -199,6 +277,8 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
+    /** Optional model identifier used to validate a voice's model compatibility. */
+    model?: string;
     normalizeLanguage?: (lang: string) => string;
     unknownVoicePolicy?: "error" | "warn" | "ignore";
     unsupportedStylePolicy?: "error" | "warn" | "ignore";
@@ -209,10 +289,24 @@ interface AzureValidationOptions {
 type AzureLanguageNormalizationOptions = Pick<AzureValidationOptions, "languageAliases" | "normalizeLanguage">;
 /** @deprecated Use AzureValidationOptions instead. */
 type AzureSsmlValidationOptions = AzureValidationOptions;
+/** Returns whether a value is a positive Azure SSML audio duration. */
+declare function isValidAzureAudioDuration(value: string): boolean;
 /** Normalizes an Azure language tag using BCP 47 and the configured aliases. */
 declare function normalizeAzureLanguage(language: string, options?: AzureLanguageNormalizationOptions): string;
 /** Compares two Azure language tags after BCP 47 and alias normalization. */
 declare function areAzureLanguagesEquivalent(first: string, second: string, options?: AzureLanguageNormalizationOptions): boolean;
 declare function validateAzureSsml(ssml: string, options?: AzureValidationOptions): SsmlDiagnostic[];
 
-export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureValidationOptions, type AzureVoiceDefinition, type AzureVoiceMetadata, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type LangElement, type LexiconElement, type MapSsmlTextNodesOptions, type MarkElement, type MsttsSilenceElement, type MsttsVisemeElement, type NamedElement, type ParagraphElement, type PhonemeElement, type ProsodyElement, type SayAsElement, type SentenceElement, type SsmlAttributeValue, type SsmlAttributes, type SsmlBreakElement, type SsmlDiagnostic, type SsmlDiagnosticSeverity, type SsmlDiagnosticSource, type SsmlDocument, type SsmlElement, type SsmlElementBase, type SsmlExpressAsElement, type SsmlNode, type SsmlPartialContext, type SsmlPartialProsody, type SsmlPartialVoice, type SsmlPhonemeElement, type SsmlProsodyElement, type SsmlSayAsElement, type SsmlText, type SsmlTextNodeContext, type SsmlValidationError, type SsmlVoiceElement, type SubElement, type VoiceElement, type WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, validateAzureSsml, validateSsml };
+interface AzureVoiceCatalogMetadata {
+    apiVersion: string;
+    generatedAt: string;
+    regions: readonly string[];
+    voiceCount: number;
+}
+
+/** Returns metadata for the built-in Azure voice catalog snapshot. */
+declare function getAzureVoiceCatalogMetadata(): AzureVoiceCatalogMetadata;
+/** Alias for consumers that refer to the bundled catalog as the built-in catalog. */
+declare const getBuiltInVoiceCatalogMetadata: typeof getAzureVoiceCatalogMetadata;
+
+export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureValidationOptions, type AzureVoiceCatalogMetadata, type AzureVoiceDefinition, type AzureVoiceMetadata, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type ExtractSsmlTranslatableTextOptions, type FromPlainTextToSsmlOptions, type LangElement, type LexiconElement, type MapSsmlTextNodesOptions, type MarkElement, type MsttsAudioDurationElement, type MsttsEmbeddingElement, type MsttsSilenceElement, type MsttsTtsEmbeddingElement, type MsttsVisemeElement, type MsttsVoiceConversionElement, type NamedElement, type ParagraphElement, type PhonemeElement, type ProsodyElement, type SayAsElement, type SentenceElement, type SsmlAttributeValue, type SsmlAttributes, type SsmlBackgroundAudioNode, type SsmlBreakElement, type SsmlDiagnostic, type SsmlDiagnosticSeverity, type SsmlDiagnosticSource, type SsmlDialogNode, type SsmlDocument, type SsmlElement, type SsmlElementBase, type SsmlEmbeddingNode, type SsmlExpressAsElement, type SsmlNode, type SsmlPartialContext, type SsmlPartialProsody, type SsmlPartialVoice, type SsmlPhonemeElement, type SsmlProsodyElement, type SsmlSayAsElement, type SsmlStructureIntegrityResult, type SsmlStructureMismatch, type SsmlText, type SsmlTextNodeContext, type SsmlTtsEmbeddingNode, type SsmlTurnNode, type SsmlValidationError, type SsmlVoiceConversionNode, type SsmlVoiceElement, type SubElement, type VoiceElement, type WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };