ssml-builder-js 2.11.0 → 2.12.0

package/dist/core.d.mts

@@ -188,6 +188,14 @@ interface BuildPartialSsmlOptions extends SsmlPartialContext {
 declare function buildPartialSsml(text: string, context?: SsmlPartialContext): string;
 declare function buildPartialSsml(options: BuildPartialSsmlOptions): string;
 
+/**
+ * Splits SSML into independently synthesizable documents without breaking XML
+ * elements. Parent elements such as `<voice>` and `<prosody>` are copied into
+ * every block. Paragraph and sentence elements therefore remain the natural
+ * split points, while oversized text is split at word/character boundaries.
+ */
+declare function splitSsmlDocument(ssml: string, maxLength?: number): string[];
+
 declare function parseSsml(xmlString: string): SsmlDocument;
 
 interface SsmlValidationError {
@@ -286,6 +294,8 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     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;
@@ -324,4 +334,4 @@ 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 };
+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, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };

package/dist/core.d.ts

@@ -188,6 +188,14 @@ interface BuildPartialSsmlOptions extends SsmlPartialContext {
 declare function buildPartialSsml(text: string, context?: SsmlPartialContext): string;
 declare function buildPartialSsml(options: BuildPartialSsmlOptions): string;
 
+/**
+ * Splits SSML into independently synthesizable documents without breaking XML
+ * elements. Parent elements such as `<voice>` and `<prosody>` are copied into
+ * every block. Paragraph and sentence elements therefore remain the natural
+ * split points, while oversized text is split at word/character boundaries.
+ */
+declare function splitSsmlDocument(ssml: string, maxLength?: number): string[];
+
 declare function parseSsml(xmlString: string): SsmlDocument;
 
 interface SsmlValidationError {
@@ -286,6 +294,8 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     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;
@@ -324,4 +334,4 @@ 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 };
+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, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };

package/dist/core.js

@@ -39,6 +39,7 @@ __export(core_exports, {
   mapSsmlTextNodes: () => mapSsmlTextNodes,
   normalizeAzureLanguage: () => normalizeAzureLanguage,
   parseSsml: () => parseSsml,
+  splitSsmlDocument: () => splitSsmlDocument,
   validateAzureSsml: () => validateAzureSsml,
   validateSsml: () => validateSsml,
   validateSsmlStructureIntegrity: () => validateSsmlStructureIntegrity
@@ -972,6 +973,104 @@ function buildPartialSsml(textOrOptions, context) {
   return serializePartialSsml(textOrOptions.text, textOrOptions);
 }
 
+// packages/ssml-core/src/split.ts
+var DEFAULT_MAX_LENGTH = 1e4;
+function cloneElement(element, children) {
+  return { ...element, children };
+}
+function documentWithChildren(document, children) {
+  return buildSsml({ ...document, children });
+}
+function wrapWithContext(node, context) {
+  return context.reduceRight((current, parent) => cloneElement(parent, [current]), node);
+}
+function documentWithNode(document, node, context) {
+  return documentWithChildren(document, [wrapWithContext(node, context)]);
+}
+function splitTextNode(text, document, context, maxLength) {
+  if (!text) return [text];
+  const parts = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = start + 1;
+    let bestEnd = end;
+    while (end <= text.length) {
+      if (documentWithNode(document, text.slice(start, end), context).length > maxLength) break;
+      bestEnd = end;
+      end += 1;
+    }
+    if (bestEnd === start) {
+      throw new RangeError("maxLength is too small to contain the SSML document wrapper");
+    }
+    const segment = text.slice(start, bestEnd);
+    const boundary = Math.max(segment.lastIndexOf(" "), segment.lastIndexOf("\n"), segment.lastIndexOf("	"));
+    const splitEnd = boundary > 0 ? start + boundary + 1 : bestEnd;
+    parts.push(text.slice(start, splitEnd));
+    start = splitEnd;
+  }
+  return parts;
+}
+function splitNode(document, node, maxLength, context = []) {
+  if (typeof node === "string" || node.type === "text") {
+    const value = typeof node === "string" ? node : node.value;
+    if (documentWithNode(document, node, context).length <= maxLength) return [node];
+    return splitTextNode(value, document, context, maxLength);
+  }
+  if (documentWithNode(document, node, context).length <= maxLength) return [node];
+  const children = node.children ?? [];
+  if (children.length === 0) {
+    throw new RangeError(`maxLength is too small to contain <${node.type}>`);
+  }
+  const splitChildren = children.flatMap((child) => splitNode(document, child, maxLength, [...context, node]));
+  const parts = [];
+  let group = [];
+  const flush = () => {
+    if (group.length > 0) {
+      parts.push(cloneElement(node, group));
+      group = [];
+    }
+  };
+  for (const child of splitChildren) {
+    const candidate = cloneElement(node, [...group, child]);
+    if (documentWithNode(document, candidate, context).length <= maxLength) {
+      group.push(child);
+      continue;
+    }
+    flush();
+    if (documentWithNode(document, cloneElement(node, [child]), context).length > maxLength) {
+      throw new RangeError(`maxLength is too small to contain <${node.type}>`);
+    }
+    group.push(child);
+  }
+  flush();
+  return parts;
+}
+function splitSsmlDocument(ssml, maxLength = DEFAULT_MAX_LENGTH) {
+  if (!Number.isInteger(maxLength) || maxLength <= 0) {
+    throw new RangeError("maxLength must be a positive integer");
+  }
+  const document = parseSsml(ssml);
+  if (ssml.length <= maxLength) return [ssml];
+  const children = document.children ?? [];
+  const splitChildren = children.flatMap((child) => splitNode(document, child, maxLength));
+  const chunks = [];
+  let group = [];
+  for (const child of splitChildren) {
+    const candidate = [...group, child];
+    if (documentWithChildren(document, candidate).length <= maxLength) {
+      group = candidate;
+      continue;
+    }
+    if (group.length > 0) chunks.push(group);
+    group = [child];
+    if (documentWithChildren(document, group).length > maxLength) {
+      throw new RangeError("maxLength is too small to contain the SSML document wrapper");
+    }
+  }
+  if (group.length > 0) chunks.push(group);
+  return chunks.map((chunk) => documentWithChildren(document, chunk));
+}
+
 // packages/ssml-core/src/validation.ts
 var PARSER_POSITION_SUFFIX = / at position (\d+)$/;
 function validateSsml(xmlString) {
@@ -1666,6 +1765,7 @@ function tokenizeElements(source) {
       attributes,
       childElementIndex,
       end,
+      depth: openElements.length + 1,
       name: tokenName,
       parentName: parent?.name,
       parentVoiceName,
@@ -1856,13 +1956,18 @@ function validateAudioSource(token, source, diagnostics, options, elementName2)
     addDiagnostic(diagnostics, source, token.start, `<${elementName2} src> must be an absolute HTTP(S) URL.`);
     return;
   }
+  if (parsed.username || parsed.password)
+    addDiagnostic(diagnostics, source, token.start, `<${elementName2} src> must not contain URL credentials.`);
   if (parsed.protocol !== "https:" && !(options.allowHttpAudio && parsed.protocol === "http:"))
     addDiagnostic(diagnostics, source, token.start, `<${elementName2} src> must use HTTPS.`);
   const isAllowedOrigin = options.allowedAudioOrigins?.some((allowedOrigin) => {
     try {
-      return new URL(allowedOrigin).origin === parsed.origin;
+      const configured = new URL(allowedOrigin);
+      if (configured.protocol !== "https:" && configured.protocol !== "http:" || configured.username || configured.password || configured.pathname !== "/" || configured.search || configured.hash)
+        return false;
+      return configured.origin === parsed.origin;
     } catch {
-      return allowedOrigin === parsed.origin;
+      return false;
     }
   }) ?? false;
   if (options.allowedAudioOrigins && !isAllowedOrigin)
@@ -2070,6 +2175,9 @@ function validateAzureSsml(ssml, options = {}) {
   const maxLength = options.maxLength ?? 1e4;
   if (ssml.length > maxLength)
     addDiagnostic(diagnostics, ssml, maxLength, `SSML exceeds the maximum length of ${maxLength} characters.`);
+  if (options.maxXmlDepth !== void 0 && (!Number.isInteger(options.maxXmlDepth) || options.maxXmlDepth <= 0)) {
+    addDiagnostic(diagnostics, ssml, 0, "maxXmlDepth must be a positive integer.");
+  }
   try {
     parseSsml(ssml);
   } catch (error) {
@@ -2079,6 +2187,18 @@ function validateAzureSsml(ssml, options = {}) {
     return diagnostics;
   }
   const tokens = tokenizeElements(ssml);
+  if (options.maxXmlDepth !== void 0) {
+    for (const token of tokens) {
+      if (token.depth > options.maxXmlDepth) {
+        addDiagnostic(
+          diagnostics,
+          ssml,
+          token.start,
+          `XML nesting depth ${token.depth} exceeds the configured maximum of ${options.maxXmlDepth}.`
+        );
+      }
+    }
+  }
   const speak = tokens.find((token) => token.name.toLowerCase() === "speak");
   const voices = tokens.filter((token) => token.name.toLowerCase() === "voice");
   const backgroundAudioTokens = tokens.filter((token) => token.name.toLowerCase() === "mstts:backgroundaudio");
@@ -2194,6 +2314,7 @@ var getBuiltInVoiceCatalogMetadata = getAzureVoiceCatalogMetadata;
   mapSsmlTextNodes,
   normalizeAzureLanguage,
   parseSsml,
+  splitSsmlDocument,
   validateAzureSsml,
   validateSsml,
   validateSsmlStructureIntegrity