ssml-builder-js 2.4.0 → 2.6.0

package/dist/elements.mjs

@@ -33,7 +33,7 @@ import {
   registerSsmlCompletionProvider,
   resolveExpressAsStyles,
   updateEditableText
-} from "./chunk-I3BR2WCQ.mjs";
+} from "./chunk-GF4QZHLJ.mjs";
 import "./chunk-6S5ODO6A.mjs";
 
 // packages/ssml-editor-react/src/ssmlInsertions.ts

package/dist/index.d.mts

@@ -1,6 +1,8 @@
-export { AudioElement, AzureSsmlValidationOptions, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, LangElement, LexiconElement, MarkElement, MsttsSilenceElement, MsttsVisemeElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SsmlAttributeValue, SsmlAttributes, SsmlBreakElement, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDocument, SsmlElement, SsmlElementBase, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlText, SsmlTextNodeContext, SsmlValidationError, SsmlVoiceElement, SubElement, VoiceElement, WordElement, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, parseSsml, validateAzureSsml, validateSsml } from './core.mjs';
+export { AudioElement, AzureSsmlValidationOptions, AzureValidationOptions, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsSilenceElement, MsttsVisemeElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SsmlAttributeValue, SsmlAttributes, SsmlBreakElement, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDocument, SsmlElement, SsmlElementBase, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlText, SsmlTextNodeContext, SsmlValidationError, SsmlVoiceElement, SubElement, VoiceElement, WordElement, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, parseSsml, validateAzureSsml, validateSsml } from './core.mjs';
 
 interface TtsConfig {
+    signal?: AbortSignal;
+    timeoutMs?: number;
     endpoint?: string;
     subscriptionKey: string;
     region: string;
@@ -13,6 +15,8 @@ interface AzureTtsLogger {
     error?: (...args: unknown[]) => void;
 }
 interface AzureTtsClientOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
     subscriptionKey: string;
     region: string;
     endpoint?: string;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { AudioElement, AzureSsmlValidationOptions, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, LangElement, LexiconElement, MarkElement, MsttsSilenceElement, MsttsVisemeElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SsmlAttributeValue, SsmlAttributes, SsmlBreakElement, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDocument, SsmlElement, SsmlElementBase, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlText, SsmlTextNodeContext, SsmlValidationError, SsmlVoiceElement, SubElement, VoiceElement, WordElement, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, parseSsml, validateAzureSsml, validateSsml } from './core.js';
+export { AudioElement, AzureSsmlValidationOptions, AzureValidationOptions, BookmarkElement, BreakElement, BuildPartialSsmlOptions, CustomElement, EmphasisElement, ExpressAsElement, LangElement, LexiconElement, MapSsmlTextNodesOptions, MarkElement, MsttsSilenceElement, MsttsVisemeElement, NamedElement, ParagraphElement, PhonemeElement, ProsodyElement, SayAsElement, SentenceElement, SsmlAttributeValue, SsmlAttributes, SsmlBreakElement, SsmlDiagnostic, SsmlDiagnosticSeverity, SsmlDocument, SsmlElement, SsmlElementBase, SsmlExpressAsElement, SsmlNode, SsmlPartialContext, SsmlPartialProsody, SsmlPartialVoice, SsmlPhonemeElement, SsmlProsodyElement, SsmlSayAsElement, SsmlText, SsmlTextNodeContext, SsmlValidationError, SsmlVoiceElement, SubElement, VoiceElement, WordElement, buildPartialSsml, buildSsml, extractSsmlText, mapSsmlTextNodes, parseSsml, validateAzureSsml, validateSsml } from './core.js';
 
 interface TtsConfig {
+    signal?: AbortSignal;
+    timeoutMs?: number;
     endpoint?: string;
     subscriptionKey: string;
     region: string;
@@ -13,6 +15,8 @@ interface AzureTtsLogger {
     error?: (...args: unknown[]) => void;
 }
 interface AzureTtsClientOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
     subscriptionKey: string;
     region: string;
     endpoint?: string;

package/dist/index.js

@@ -911,6 +911,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) {
@@ -929,14 +932,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,
@@ -978,14 +998,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;
@@ -994,15 +1014,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");
       }
@@ -1159,6 +1185,7 @@ function findTagEnd2(source, start) {
 }
 function tokenizeElements(source) {
   const tokens = [];
+  const openElements = [];
   let index = 0;
   while (index < source.length) {
     const start = source.indexOf("<", index);
@@ -1180,8 +1207,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;
     }
@@ -1191,7 +1223,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;
@@ -1207,7 +1247,45 @@ 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 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;
+  return {
+    language: match.groups.language.toLowerCase(),
+    region: match.groups.region.toLowerCase()
+  };
+}
+function languageLocalePrefix(language) {
+  const match = /^(?<language>[A-Za-z]{2,3})(?:-(?<region>[A-Za-z]{2}|\d{3}))?(?:-|$)/.exec(language.trim());
+  if (!match?.groups) return void 0;
+  return {
+    language: match.groups.language.toLowerCase(),
+    region: match.groups.region?.toLowerCase()
+  };
+}
+function voiceMatchesLanguage(voiceName, language) {
+  const voiceLocale = voiceLocalePrefix(voiceName);
+  const languageLocale = languageLocalePrefix(language);
+  if (!voiceLocale || !languageLocale) return void 0;
+  return voiceLocale.language === languageLocale.language && (languageLocale.region === void 0 || voiceLocale.region === languageLocale.region);
+}
+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.');
@@ -1249,9 +1327,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");
@@ -1311,6 +1404,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"
+        );
     }
   }
 }
@@ -1341,7 +1442,33 @@ 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();
+    const language = attr(token, "xml:lang")?.trim() || (speak ? attr(speak, "xml:lang")?.trim() : void 0);
+    if (name && !voiceStyleMap.has(name.toLowerCase()) && policySeverity)
+      addDiagnostic(
+        diagnostics,
+        ssml,
+        token.start,
+        `Unknown voice "${name}" is not registered in the voice style map.`,
+        policySeverity
+      );
+    if (name && language && voiceMatchesLanguage(name, language) === false)
+      addDiagnostic(
+        diagnostics,
+        ssml,
+        token.start,
+        `Voice "${name}" does not match language "${language}"; the voice name prefix indicates a different language or region.`,
+        "warning"
+      );
+  }
+  for (const token of tokens) {
+    const tokenVoiceName = options.validateNestedVoices === false ? voiceName : token.parentVoiceName;
+    validateElement(token, ssml, diagnostics, tokenVoiceName, options, voiceStyleMap);
+  }
   return diagnostics;
 }
 
@@ -1452,30 +1579,56 @@ function closeSpeechResources(speechConfig, synthesizer) {
   }
 }
 async function synthesizeSpeech(ssml, config) {
+  if (config.signal?.aborted) {
+    throw createSpeechSdkError("Speech synthesis was cancelled.");
+  }
   const speechConfig = createSpeechConfig(config);
   const synthesizer = new SpeechSDK2.SpeechSynthesizer(speechConfig, null);
   return await new Promise((resolve, reject) => {
     let resourcesClosed = false;
+    let settled = false;
+    let timeout;
+    let abortHandler;
+    const cleanup = () => {
+      if (timeout) clearTimeout(timeout);
+      if (abortHandler) config.signal?.removeEventListener("abort", abortHandler);
+    };
     const closeResources = () => {
       if (resourcesClosed) return;
       resourcesClosed = true;
       closeSpeechResources(speechConfig, synthesizer);
     };
     const rejectWithError = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
       closeResources();
       reject(createSpeechSdkError(error));
     };
     const cb = (result) => {
+      if (settled) return;
       const { reason, errorDetails } = result;
       if (reason !== SpeechSDK2.ResultReason.SynthesizingAudioCompleted) {
         const err = errorDetails || `Speech synthesis failed with reason ${reason}.`;
         rejectWithError(err);
         return;
       }
+      settled = true;
+      cleanup();
       closeResources();
       resolve(result.audioData);
     };
     try {
+      if (config.signal) {
+        abortHandler = () => rejectWithError("Speech synthesis was cancelled.");
+        config.signal.addEventListener("abort", abortHandler, { once: true });
+      }
+      if (config.timeoutMs !== void 0 && config.timeoutMs > 0) {
+        timeout = setTimeout(
+          () => rejectWithError(`Speech synthesis timed out after ${config.timeoutMs} ms.`),
+          config.timeoutMs
+        );
+      }
       synthesizer.speakSsmlAsync(ssml, cb, rejectWithError);
     } catch (error) {
       rejectWithError(error);
@@ -1492,10 +1645,10 @@ var AzureTtsClient = class {
     __privateSet(this, _options, options);
   }
   async synthesize(ssml) {
-    const { region, subscriptionKey, outputFormat } = __privateGet(this, _options);
+    const { region, subscriptionKey, outputFormat, signal, timeoutMs } = __privateGet(this, _options);
     const endpoint = __privateGet(this, _options).endpoint?.trim() || ENDPOINT_TEMPLATE.replace("{region}", region);
     __privateGet(this, _options).logger?.debug?.("Using Azure TTS endpoint:", endpoint);
-    const config = { endpoint, region, subscriptionKey, outputFormat };
+    const config = { endpoint, region, subscriptionKey, outputFormat, signal, timeoutMs };
     return synthesizeSpeech(ssml, config);
   }
 };