ssml-builder-js 2.5.0 → 2.7.0

package/dist/core.d.mts

@@ -172,23 +172,45 @@ declare function extractSsmlText(ssml: string): string[];
 declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
 
 type SsmlDiagnosticSeverity = "error" | "warning";
+type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch";
 interface SsmlDiagnostic {
+    code?: AzureDiagnosticCode;
     line: number;
     column: number;
     message: string;
     severity: SsmlDiagnosticSeverity;
 }
+interface AzureVoiceDefinition {
+    name: string;
+    locale: string;
+    secondaryLocales?: readonly string[];
+    styles?: readonly string[];
+}
+/** Alias retained for consumers that prefer the metadata terminology. */
+interface AzureVoiceMetadata extends AzureVoiceDefinition {
+}
 interface AzureValidationOptions {
     allowedAudioOrigins?: readonly string[];
     allowExternalAudio?: boolean;
     allowHttpAudio?: boolean;
     customVoiceStyleMap?: Record<string, readonly string[]>;
+    customVoiceDefinitions?: readonly AzureVoiceDefinition[];
+    languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
+    normalizeLanguage?: (lang: string) => string;
     unknownVoicePolicy?: "error" | "warn" | "ignore";
+    unsupportedStylePolicy?: "error" | "warn" | "ignore";
     validateNestedVoices?: boolean;
+    voiceCatalog?: readonly AzureVoiceDefinition[];
+    voiceDefinitions?: readonly AzureVoiceDefinition[];
 }
+type AzureLanguageNormalizationOptions = Pick<AzureValidationOptions, "languageAliases" | "normalizeLanguage">;
 /** @deprecated Use AzureValidationOptions instead. */
 type AzureSsmlValidationOptions = AzureValidationOptions;
+/** 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 AzureSsmlValidationOptions, type AzureValidationOptions, 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 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, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, parseSsml, validateAzureSsml, validateSsml };
+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 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 };

package/dist/core.d.ts

@@ -172,23 +172,45 @@ declare function extractSsmlText(ssml: string): string[];
 declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
 
 type SsmlDiagnosticSeverity = "error" | "warning";
+type AzureDiagnosticCode = "azure-unknown-voice" | "azure-unsupported-style" | "azure-locale-mismatch";
 interface SsmlDiagnostic {
+    code?: AzureDiagnosticCode;
     line: number;
     column: number;
     message: string;
     severity: SsmlDiagnosticSeverity;
 }
+interface AzureVoiceDefinition {
+    name: string;
+    locale: string;
+    secondaryLocales?: readonly string[];
+    styles?: readonly string[];
+}
+/** Alias retained for consumers that prefer the metadata terminology. */
+interface AzureVoiceMetadata extends AzureVoiceDefinition {
+}
 interface AzureValidationOptions {
     allowedAudioOrigins?: readonly string[];
     allowExternalAudio?: boolean;
     allowHttpAudio?: boolean;
     customVoiceStyleMap?: Record<string, readonly string[]>;
+    customVoiceDefinitions?: readonly AzureVoiceDefinition[];
+    languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
+    normalizeLanguage?: (lang: string) => string;
     unknownVoicePolicy?: "error" | "warn" | "ignore";
+    unsupportedStylePolicy?: "error" | "warn" | "ignore";
     validateNestedVoices?: boolean;
+    voiceCatalog?: readonly AzureVoiceDefinition[];
+    voiceDefinitions?: readonly AzureVoiceDefinition[];
 }
+type AzureLanguageNormalizationOptions = Pick<AzureValidationOptions, "languageAliases" | "normalizeLanguage">;
 /** @deprecated Use AzureValidationOptions instead. */
 type AzureSsmlValidationOptions = AzureValidationOptions;
+/** 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 AzureSsmlValidationOptions, type AzureValidationOptions, 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 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, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, parseSsml, validateAzureSsml, validateSsml };
+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 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 };

package/dist/core.js

@@ -27,10 +27,12 @@ var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "
 // src/core.ts
 var core_exports = {};
 __export(core_exports, {
+  areAzureLanguagesEquivalent: () => areAzureLanguagesEquivalent,
   buildPartialSsml: () => buildPartialSsml,
   buildSsml: () => buildSsml,
   extractSsmlText: () => extractSsmlText,
   mapSsmlTextNodes: () => mapSsmlTextNodes,
+  normalizeAzureLanguage: () => normalizeAzureLanguage,
   parseSsml: () => parseSsml,
   validateAzureSsml: () => validateAzureSsml,
   validateSsml: () => validateSsml
@@ -1227,29 +1229,123 @@ function location(source, offset) {
   const line = before.split("\n").length;
   return { line, column: before.length - (before.lastIndexOf("\n") + 1) + 1 };
 }
-function addDiagnostic(diagnostics, source, offset, message, severity = "error") {
-  diagnostics.push({ ...location(source, offset), message, severity });
+function addDiagnostic(diagnostics, source, offset, message, severity = "error", code) {
+  diagnostics.push({ ...location(source, offset), message, severity, ...code ? { code } : {} });
 }
 function attr(token, name) {
   return token.attributes.get(name.toLowerCase());
 }
-function normalizeVoiceStyleMap(customVoiceStyleMap) {
-  const map = new Map(
-    Object.entries(EXPRESS_AS_STYLES).map(([voiceName, styles]) => [voiceName.toLowerCase(), styles])
-  );
-  for (const [voiceName, styles] of Object.entries(customVoiceStyleMap ?? {})) {
-    map.set(
-      voiceName.toLowerCase(),
-      styles.map((style) => style.toLowerCase())
-    );
+var ADDITIONAL_VOICE_DEFINITIONS = [
+  { name: "zh-TW-HsiaoChenNeural", locale: "zh-TW" },
+  { name: "es-ES-ElviraNeural", locale: "es-ES" },
+  { name: "th-TH-PremwadeeNeural", locale: "th-TH" },
+  { name: "fil-PH-AngeloNeural", locale: "fil-PH" },
+  { name: "vi-VN-HoaiMyNeural", locale: "vi-VN" },
+  { name: "id-ID-GadisNeural", locale: "id-ID" },
+  { name: "ms-MY-YasminNeural", locale: "ms-MY" }
+];
+var DEFAULT_LANGUAGE_ALIASES = {
+  "zh-CN": ["zh-Hans"],
+  "zh-TW": ["zh-Hant"]
+};
+function canonicalLanguageTag(language) {
+  const trimmed = language.trim();
+  if (!trimmed) return "";
+  try {
+    return new Intl.Locale(trimmed).toString().toLowerCase();
+  } catch {
+    return trimmed.toLowerCase();
   }
-  return map;
+}
+function createLanguageNormalizer(options) {
+  const aliases = /* @__PURE__ */ new Map();
+  const addAliasGroup = (canonical, values) => {
+    const normalizedCanonical = canonicalLanguageTag(canonical);
+    if (!normalizedCanonical) return;
+    aliases.set(normalizedCanonical, normalizedCanonical);
+    for (const value of values) {
+      const normalizedValue = canonicalLanguageTag(value);
+      if (normalizedValue) aliases.set(normalizedValue, normalizedCanonical);
+    }
+  };
+  for (const [canonical, values] of Object.entries(DEFAULT_LANGUAGE_ALIASES)) addAliasGroup(canonical, values);
+  for (const [canonical, valueOrValues] of Object.entries(options.languageAliases ?? {}))
+    addAliasGroup(canonical, typeof valueOrValues === "string" ? [valueOrValues] : valueOrValues);
+  return (language) => {
+    const customValue = options.normalizeLanguage ? options.normalizeLanguage(language) : language;
+    const normalized = canonicalLanguageTag(customValue);
+    return aliases.get(normalized) ?? normalized;
+  };
+}
+function normalizeAzureLanguage(language, options = {}) {
+  return createLanguageNormalizer(options)(language);
+}
+function areAzureLanguagesEquivalent(first, second, options = {}) {
+  const normalize = createLanguageNormalizer(options);
+  const normalizedFirst = normalize(first);
+  const normalizedSecond = normalize(second);
+  if (normalizedFirst === normalizedSecond) return true;
+  return normalizedFirst === languagePart(normalizedFirst) && languagePart(normalizedFirst) === languagePart(normalizedSecond);
+}
+function voiceLocalePrefix(voiceName) {
+  const match = /^(?<language>[A-Za-z]{2,3})-(?<region>[A-Za-z]{2}|\d{3})(?:-|$)/.exec(voiceName.trim());
+  if (!match?.groups) return void 0;
+  const tag = `${match.groups.language}-${match.groups.region}`;
+  return {
+    language: match.groups.language.toLowerCase(),
+    region: match.groups.region.toLowerCase(),
+    tag
+  };
+}
+function definitionFromStyleMap(voiceName, styles) {
+  return {
+    name: voiceName,
+    locale: voiceLocalePrefix(voiceName)?.tag ?? "",
+    styles
+  };
+}
+function normalizeVoiceCatalog(options) {
+  const definitions = /* @__PURE__ */ new Map();
+  for (const [name, styles] of Object.entries(EXPRESS_AS_STYLES)) {
+    definitions.set(name.toLowerCase(), definitionFromStyleMap(name, styles));
+  }
+  for (const definition of ADDITIONAL_VOICE_DEFINITIONS) definitions.set(definition.name.toLowerCase(), definition);
+  for (const definition of options.voiceCatalog ?? []) definitions.set(definition.name.toLowerCase(), definition);
+  for (const definition of options.voiceDefinitions ?? []) definitions.set(definition.name.toLowerCase(), definition);
+  for (const definition of options.customVoiceDefinitions ?? [])
+    definitions.set(definition.name.toLowerCase(), definition);
+  for (const [voiceName, styles] of Object.entries(options.customVoiceStyleMap ?? {})) {
+    const key = voiceName.toLowerCase();
+    const current = definitions.get(key);
+    definitions.set(key, {
+      ...current ?? definitionFromStyleMap(voiceName, styles),
+      name: current?.name ?? voiceName,
+      styles: styles.map((style) => style.toLowerCase())
+    });
+  }
+  return definitions;
 }
 function diagnosticSeverity(policy) {
   if (policy === "ignore") return void 0;
   return policy === "error" ? "error" : "warning";
 }
-function validateElement(token, source, diagnostics, voiceName, options, voiceStyleMap) {
+function languagePart(language) {
+  try {
+    return new Intl.Locale(language).language.toLowerCase();
+  } catch {
+    return language.split("-")[0]?.toLowerCase() ?? "";
+  }
+}
+function definitionMatchesLanguage(definition, voiceName, language, normalizeLanguage) {
+  const candidateLanguages = definition ? [definition.locale, ...definition.secondaryLocales ?? []].filter(Boolean) : [voiceLocalePrefix(voiceName)?.tag ?? ""];
+  if (candidateLanguages.length === 0 || !language.trim()) return void 0;
+  const normalizedLanguage = normalizeLanguage(language);
+  const normalizedCandidates = candidateLanguages.map(normalizeLanguage);
+  if (normalizedCandidates.includes(normalizedLanguage)) return true;
+  if (!normalizedLanguage || !normalizedCandidates.some(Boolean)) return void 0;
+  return normalizedLanguage === languagePart(normalizedLanguage) ? normalizedCandidates.some((candidate) => languagePart(candidate) === normalizedLanguage) : false;
+}
+function validateElement(token, source, diagnostics, voiceName, options, voiceCatalog) {
   const name = token.name.toLowerCase();
   if (name === "voice" && !attr(token, "name")?.trim())
     addDiagnostic(diagnostics, source, token.start, '<voice> requires a non-empty "name" attribute.');
@@ -1291,17 +1387,19 @@ function validateElement(token, source, diagnostics, voiceName, options, voiceSt
     const role = attr(token, "role");
     if (role && !ALLOWED_ROLES.has(role))
       addDiagnostic(diagnostics, source, token.start, `Unsupported <mstts:express-as role> value "${role}".`);
-    const supportedStyles = voiceName ? voiceStyleMap.get(voiceName.toLowerCase()) : void 0;
-    const severity = diagnosticSeverity(options.unknownVoicePolicy ?? "warn");
-    if (style && supportedStyles && !supportedStyles.includes(style.toLowerCase()) && severity)
+    const definition = voiceName ? voiceCatalog.get(voiceName.toLowerCase()) : void 0;
+    const supportedStyles = definition?.styles;
+    const severity = diagnosticSeverity(options.unsupportedStylePolicy ?? options.unknownVoicePolicy ?? "warn");
+    if (style && definition && !supportedStyles?.some((candidate) => candidate.toLowerCase() === style.toLowerCase()) && severity)
       addDiagnostic(
         diagnostics,
         source,
         token.start,
         `Unknown style "${style}" is not supported by voice "${voiceName}" according to the configured voice style map.`,
-        severity
+        severity,
+        "azure-unsupported-style"
       );
-    if (style && voiceName && !supportedStyles && severity)
+    if (style && voiceName && !definition && severity)
       addDiagnostic(
         diagnostics,
         source,
@@ -1406,32 +1504,47 @@ function validateAzureSsml(ssml, options = {}) {
       "Azure SSML requires at least one <voice> element under <speak>."
     );
   const voiceName = voices[0] ? attr(voices[0], "name") : void 0;
-  const voiceStyleMap = normalizeVoiceStyleMap(options.customVoiceStyleMap);
+  const voiceCatalog = normalizeVoiceCatalog(options);
+  const normalizeLanguage = createLanguageNormalizer(options);
   const policySeverity = diagnosticSeverity(options.unknownVoicePolicy ?? "warn");
   const voicesToValidate = options.validateNestedVoices === false ? voices.slice(0, 1) : voices;
   for (const token of voicesToValidate) {
     const name = attr(token, "name")?.trim();
-    if (name && !voiceStyleMap.has(name.toLowerCase()) && policySeverity)
+    const language = attr(token, "xml:lang")?.trim() || (speak ? attr(speak, "xml:lang")?.trim() : void 0);
+    const definition = name ? voiceCatalog.get(name.toLowerCase()) : void 0;
+    if (name && !definition && policySeverity)
+      addDiagnostic(
+        diagnostics,
+        ssml,
+        token.start,
+        `Unknown voice "${name}" is not registered in the voice catalog.`,
+        policySeverity,
+        "azure-unknown-voice"
+      );
+    if (name && language && definitionMatchesLanguage(definition, name, language, normalizeLanguage) === false)
       addDiagnostic(
         diagnostics,
         ssml,
         token.start,
-        `Unknown voice "${name}" is not registered in the voice style map.`,
-        policySeverity
+        `Voice "${name}" does not match language "${language}"; the voice name prefix indicates a different language or region.`,
+        "warning",
+        "azure-locale-mismatch"
       );
   }
   for (const token of tokens) {
     const tokenVoiceName = options.validateNestedVoices === false ? voiceName : token.parentVoiceName;
-    validateElement(token, ssml, diagnostics, tokenVoiceName, options, voiceStyleMap);
+    validateElement(token, ssml, diagnostics, tokenVoiceName, options, voiceCatalog);
   }
   return diagnostics;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  areAzureLanguagesEquivalent,
   buildPartialSsml,
   buildSsml,
   extractSsmlText,
   mapSsmlTextNodes,
+  normalizeAzureLanguage,
   parseSsml,
   validateAzureSsml,
   validateSsml