ssml-builder-js 2.4.0 → 2.5.0

package/dist/core.d.mts

@@ -158,10 +158,18 @@ declare function validateSsml(xmlString: string): SsmlValidationError | null;
 
 interface SsmlTextNodeContext {
     parentTag: string;
+    parentAttributes: Record<string, string>;
+    ancestorTags: string[];
     path: string[];
 }
+interface MapSsmlTextNodesOptions {
+    /** Element names whose text should not be passed to the transform. */
+    skipTags?: readonly string[];
+    /** Decides whether an individual text node should be passed to the transform. */
+    filter?: (context: SsmlTextNodeContext) => boolean;
+}
 declare function extractSsmlText(ssml: string): string[];
-declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>): Promise<string>;
+declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
 
 type SsmlDiagnosticSeverity = "error" | "warning";
 interface SsmlDiagnostic {
@@ -170,11 +178,17 @@ interface SsmlDiagnostic {
     message: string;
     severity: SsmlDiagnosticSeverity;
 }
-interface AzureSsmlValidationOptions {
+interface AzureValidationOptions {
     allowedAudioOrigins?: readonly string[];
+    allowExternalAudio?: boolean;
     allowHttpAudio?: boolean;
+    customVoiceStyleMap?: Record<string, readonly string[]>;
     maxLength?: number;
+    unknownVoicePolicy?: "error" | "warn" | "ignore";
+    validateNestedVoices?: boolean;
 }
-declare function validateAzureSsml(ssml: string, options?: AzureSsmlValidationOptions): SsmlDiagnostic[];
+/** @deprecated Use AzureValidationOptions instead. */
+type AzureSsmlValidationOptions = AzureValidationOptions;
+declare function validateAzureSsml(ssml: string, options?: AzureValidationOptions): SsmlDiagnostic[];
 
-export { type AudioElement, type AzureSsmlValidationOptions, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type LangElement, type LexiconElement, 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 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 };

package/dist/core.d.ts

@@ -158,10 +158,18 @@ declare function validateSsml(xmlString: string): SsmlValidationError | null;
 
 interface SsmlTextNodeContext {
     parentTag: string;
+    parentAttributes: Record<string, string>;
+    ancestorTags: string[];
     path: string[];
 }
+interface MapSsmlTextNodesOptions {
+    /** Element names whose text should not be passed to the transform. */
+    skipTags?: readonly string[];
+    /** Decides whether an individual text node should be passed to the transform. */
+    filter?: (context: SsmlTextNodeContext) => boolean;
+}
 declare function extractSsmlText(ssml: string): string[];
-declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>): Promise<string>;
+declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
 
 type SsmlDiagnosticSeverity = "error" | "warning";
 interface SsmlDiagnostic {
@@ -170,11 +178,17 @@ interface SsmlDiagnostic {
     message: string;
     severity: SsmlDiagnosticSeverity;
 }
-interface AzureSsmlValidationOptions {
+interface AzureValidationOptions {
     allowedAudioOrigins?: readonly string[];
+    allowExternalAudio?: boolean;
     allowHttpAudio?: boolean;
+    customVoiceStyleMap?: Record<string, readonly string[]>;
     maxLength?: number;
+    unknownVoicePolicy?: "error" | "warn" | "ignore";
+    validateNestedVoices?: boolean;
 }
-declare function validateAzureSsml(ssml: string, options?: AzureSsmlValidationOptions): SsmlDiagnostic[];
+/** @deprecated Use AzureValidationOptions instead. */
+type AzureSsmlValidationOptions = AzureValidationOptions;
+declare function validateAzureSsml(ssml: string, options?: AzureValidationOptions): SsmlDiagnostic[];
 
-export { type AudioElement, type AzureSsmlValidationOptions, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type LangElement, type LexiconElement, 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 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 };

package/dist/core.js

@@ -897,6 +897,9 @@ function decodeXmlText(value) {
 function encodeXmlText(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+function decodeXmlAttribute(value) {
+  return decodeXmlText(value);
+}
 function findTagEnd(source, start) {
   let quote = "";
   for (let index = start; index < source.length; index += 1) {
@@ -915,14 +918,31 @@ function readTagName(tag) {
   const match = /^<\s*([A-Za-z_][A-Za-z0-9_.:-]*)/.exec(tag);
   return match?.[1];
 }
+function readTagAttributes(tag, name) {
+  const attributes = {};
+  const nameStart = tag.indexOf(name);
+  const attributeSource = tag.slice(nameStart + name.length, tag.length - 1).replace(/\/\s*$/, "");
+  const attributePattern = /([A-Za-z_][A-Za-z0-9_.:-]*)\s*=\s*(["'])([\s\S]*?)\2/g;
+  for (const match of attributeSource.matchAll(attributePattern)) {
+    attributes[match[1].toLowerCase()] = decodeXmlAttribute(match[3]);
+  }
+  return attributes;
+}
 function collectTextNodes(source) {
   const nodes = [];
-  const path = [];
+  const elements = [];
   let index = 0;
   const addText = (start, end, rawText, sourceStart = start, sourceEnd = end) => {
     if (!rawText) return;
+    const path = elements.map((element) => element.name);
+    const parent = elements[elements.length - 1];
     nodes.push({
-      context: { parentTag: path[path.length - 1] ?? "", path: [...path] },
+      context: {
+        ancestorTags: path.slice(0, -1),
+        parentAttributes: { ...parent?.attributes ?? {} },
+        parentTag: parent?.name ?? "",
+        path
+      },
       decodedText: decodeXmlText(rawText),
       end,
       sourceEnd,
@@ -964,14 +984,14 @@ function collectTextNodes(source) {
     }
     if (source.startsWith("</", index)) {
       const end2 = findTagEnd(source, index + 2);
-      path.pop();
+      elements.pop();
       index = end2 + 1;
       continue;
     }
     const end = findTagEnd(source, index + 1);
     const tag = source.slice(index, end + 1);
     const name = readTagName(tag);
-    if (name && !/\/\s*>$/.test(tag)) path.push(name);
+    if (name && !/\/\s*>$/.test(tag)) elements.push({ attributes: readTagAttributes(tag, name), name });
     index = end + 1;
   }
   return nodes;
@@ -980,15 +1000,21 @@ function extractSsmlText(ssml) {
   parseSsml(ssml);
   return collectTextNodes(ssml).map((node) => node.decodedText);
 }
-async function mapSsmlTextNodes(ssml, transform) {
+async function mapSsmlTextNodes(ssml, transform, options = {}) {
   parseSsml(ssml);
   const nodes = collectTextNodes(ssml);
+  const skipTags = new Set((options.skipTags ?? ["phoneme", "say-as", "sub"]).map((tag) => tag.toLowerCase()));
   const replacements = await Promise.all(
     nodes.map(async (node) => {
-      const transformed = await transform(node.decodedText, {
+      const context = {
+        ancestorTags: [...node.context.ancestorTags],
+        parentAttributes: { ...node.context.parentAttributes },
         parentTag: node.context.parentTag,
         path: [...node.context.path]
-      });
+      };
+      const shouldTransform = !skipTags.has(context.parentTag.toLowerCase()) && (options.filter?.(context) ?? true);
+      if (!shouldTransform) return ssml.slice(node.sourceStart, node.sourceEnd);
+      const transformed = await transform(node.decodedText, context);
       if (typeof transformed !== "string") {
         throw new TypeError("SSML text node transform must return a string");
       }
@@ -1145,6 +1171,7 @@ function findTagEnd2(source, start) {
 }
 function tokenizeElements(source) {
   const tokens = [];
+  const openElements = [];
   let index = 0;
   while (index < source.length) {
     const start = source.indexOf("<", index);
@@ -1166,8 +1193,13 @@ function tokenizeElements(source) {
     }
     const end = findTagEnd2(source, start + 1);
     const raw = source.slice(start, end + 1);
+    if (raw.startsWith("</")) {
+      openElements.pop();
+      index = end + 1;
+      continue;
+    }
     const nameMatch = /^<\s*([A-Za-z_][A-Za-z0-9_.:-]*)/.exec(raw);
-    if (!nameMatch?.[1] || raw.startsWith("</")) {
+    if (!nameMatch?.[1]) {
       index = end + 1;
       continue;
     }
@@ -1177,7 +1209,15 @@ function tokenizeElements(source) {
     for (const match of attributeSource.matchAll(attributePattern)) {
       attributes.set(match[1].toLowerCase(), decodeAttribute(match[3]));
     }
-    tokens.push({ attributes, end, name: nameMatch[1], selfClosing: /\/\s*>$/.test(raw), start });
+    const selfClosing = /\/\s*>$/.test(raw);
+    const parentVoiceName = [...openElements].reverse().find((element) => element.voiceName)?.voiceName;
+    tokens.push({ attributes, end, name: nameMatch[1], parentVoiceName, selfClosing, start });
+    if (!selfClosing) {
+      openElements.push({
+        name: nameMatch[1],
+        voiceName: nameMatch[1].toLowerCase() === "voice" ? attributes.get("name") : parentVoiceName
+      });
+    }
     index = end + 1;
   }
   return tokens;
@@ -1193,7 +1233,23 @@ function addDiagnostic(diagnostics, source, offset, message, severity = "error")
 function attr(token, name) {
   return token.attributes.get(name.toLowerCase());
 }
-function validateElement(token, source, diagnostics, voiceName, options) {
+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())
+    );
+  }
+  return map;
+}
+function diagnosticSeverity(policy) {
+  if (policy === "ignore") return void 0;
+  return policy === "error" ? "error" : "warning";
+}
+function validateElement(token, source, diagnostics, voiceName, options, voiceStyleMap) {
   const name = token.name.toLowerCase();
   if (name === "voice" && !attr(token, "name")?.trim())
     addDiagnostic(diagnostics, source, token.start, '<voice> requires a non-empty "name" attribute.');
@@ -1235,9 +1291,24 @@ function validateElement(token, source, diagnostics, voiceName, options) {
     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 ? EXPRESS_AS_STYLES[voiceName.toLowerCase()] : void 0;
-    if (style && supportedStyles && !supportedStyles.includes(style.toLowerCase()))
-      addDiagnostic(diagnostics, source, token.start, `Style "${style}" is not supported by voice "${voiceName}".`);
+    const supportedStyles = voiceName ? voiceStyleMap.get(voiceName.toLowerCase()) : void 0;
+    const severity = diagnosticSeverity(options.unknownVoicePolicy ?? "warn");
+    if (style && supportedStyles && !supportedStyles.includes(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
+      );
+    if (style && voiceName && !supportedStyles && severity)
+      addDiagnostic(
+        diagnostics,
+        source,
+        token.start,
+        `Unknown style "${style}" cannot be verified because voice "${voiceName}" is not registered in the voice style map.`,
+        severity
+      );
   }
   if (name === "say-as" || name === "sayas") {
     const interpretAs = attr(token, "interpret-as");
@@ -1297,6 +1368,14 @@ function validateElement(token, source, diagnostics, voiceName, options) {
         addDiagnostic(diagnostics, source, token.start, "<audio src> must use HTTPS.");
       if (options.allowedAudioOrigins && !options.allowedAudioOrigins.includes(parsed.origin))
         addDiagnostic(diagnostics, source, token.start, `<audio src> origin "${parsed.origin}" is not allowed.`);
+      else if (!options.allowExternalAudio)
+        addDiagnostic(
+          diagnostics,
+          source,
+          token.start,
+          `<audio src> external origin "${parsed.origin}" is blocked by default; set allowExternalAudio to true or provide allowedAudioOrigins.`,
+          "error"
+        );
     }
   }
 }
@@ -1327,7 +1406,24 @@ function validateAzureSsml(ssml, options = {}) {
       "Azure SSML requires at least one <voice> element under <speak>."
     );
   const voiceName = voices[0] ? attr(voices[0], "name") : void 0;
-  for (const token of tokens) validateElement(token, ssml, diagnostics, voiceName, options);
+  const voiceStyleMap = normalizeVoiceStyleMap(options.customVoiceStyleMap);
+  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)
+      addDiagnostic(
+        diagnostics,
+        ssml,
+        token.start,
+        `Unknown voice "${name}" is not registered in the voice style map.`,
+        policySeverity
+      );
+  }
+  for (const token of tokens) {
+    const tokenVoiceName = options.validateNestedVoices === false ? voiceName : token.parentVoiceName;
+    validateElement(token, ssml, diagnostics, tokenVoiceName, options, voiceStyleMap);
+  }
   return diagnostics;
 }
 // Annotate the CommonJS export names for ESM import in node: