ssml-builder-js 2.12.0 → 2.13.0

package/dist/core.d.ts

@@ -188,13 +188,35 @@ interface BuildPartialSsmlOptions extends SsmlPartialContext {
 declare function buildPartialSsml(text: string, context?: SsmlPartialContext): string;
 declare function buildPartialSsml(options: BuildPartialSsmlOptions): string;
 
+interface SsmlTextRange {
+    start: number;
+    end: number;
+}
+interface SsmlChunkContext {
+    voice?: string;
+    lang?: string;
+    prosody?: Record<string, string>;
+}
+interface SsmlChunk {
+    chunkIndex: number;
+    ssml: string;
+    originalTextRange: SsmlTextRange;
+    inheritedContext: SsmlChunkContext;
+    containedMarks: string[];
+    hasBackgroundAudio: boolean;
+}
+interface SplitSsmlOptions {
+    maxLength?: number;
+    /** Keeps `<mstts:backgroundaudio>` in every chunk instead of the first chunk only. */
+    replicateBackgroundAudio?: boolean;
+}
 /**
  * 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 splitSsmlDocument(ssml: string, maxLength?: number | SplitSsmlOptions, options?: SplitSsmlOptions): SsmlChunk[];
 
 declare function parseSsml(xmlString: string): SsmlDocument;
 
@@ -292,6 +314,10 @@ interface AzureValidationOptions {
     allowHttpAudio?: boolean;
     customVoiceStyleMap?: Record<string, readonly string[]>;
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
+    /** Host-side validation hook for URL-bearing SSML attributes. */
+    urlValidator?: AzureUrlValidator;
+    /** Alias for urlValidator retained for applications that use the longer name. */
+    customUrlValidator?: AzureUrlValidator;
     languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
     /** Maximum XML element nesting depth, counting `<speak>` as depth 1. */
@@ -311,6 +337,14 @@ interface AzureValidationOptions {
     voiceCatalog?: readonly AzureVoiceDefinition[];
     voiceDefinitions?: readonly AzureVoiceDefinition[];
 }
+type AzureUrlValidationResult = boolean | {
+    valid: boolean;
+    reason?: string;
+};
+type AzureUrlValidator = (url: string, context: {
+    tag: string;
+    attribute: string;
+}) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
 type AzureLanguageNormalizationOptions = Pick<AzureValidationOptions, "languageAliases" | "normalizeLanguage">;
 /** @deprecated Use AzureValidationOptions instead. */
 type AzureSsmlValidationOptions = AzureValidationOptions;
@@ -320,7 +354,15 @@ declare function isValidAzureAudioDuration(value: string): boolean;
 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[];
+/**
+ * Validates Azure SSML synchronously unless a URL validator is supplied. URL
+ * validation is asynchronous-capable so hosts can perform DNS/private-network checks.
+ */
+declare function validateAzureSsml(ssml: string, options?: Omit<AzureValidationOptions, "urlValidator" | "customUrlValidator">): SsmlDiagnostic[];
+declare function validateAzureSsml(ssml: string, options: AzureValidationOptions & {
+    urlValidator?: AzureUrlValidator;
+    customUrlValidator?: AzureUrlValidator;
+}): SsmlDiagnostic[] | Promise<SsmlDiagnostic[]>;
 
 interface AzureVoiceCatalogMetadata {
     apiVersion: string;
@@ -334,4 +376,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, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };
+export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureUrlValidationResult, type AzureUrlValidator, 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 SplitSsmlOptions, type SsmlAttributeValue, type SsmlAttributes, type SsmlBackgroundAudioNode, type SsmlBreakElement, type SsmlChunk, type SsmlChunkContext, 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 SsmlTextRange, 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

@@ -1045,30 +1045,109 @@ function splitNode(document, node, maxLength, context = []) {
   flush();
   return parts;
 }
-function splitSsmlDocument(ssml, maxLength = DEFAULT_MAX_LENGTH) {
-  if (!Number.isInteger(maxLength) || maxLength <= 0) {
+function textFromNode(node) {
+  if (typeof node === "string") return node;
+  if (node.type === "text") return node.value;
+  return (node.children ?? []).map(textFromNode).join("");
+}
+function collectMarks(node, marks) {
+  if (typeof node === "string" || node.type === "text") return;
+  if (node.type === "mark" && node.name) marks.push(node.name);
+  if (node.type === "bookmark" && node.mark) marks.push(node.mark);
+  for (const child of node.children ?? []) collectMarks(child, marks);
+}
+function collectInheritedContext(nodes) {
+  const context = {};
+  const visit = (node) => {
+    if (typeof node === "string" || node.type === "text") return;
+    if (context.voice === void 0 && node.type === "voice" && node.name) context.voice = node.name;
+    if (context.lang === void 0 && node.type === "lang" && node.lang) context.lang = node.lang;
+    if (context.prosody === void 0 && node.type === "prosody") {
+      const prosody = {};
+      for (const [key, value] of Object.entries(node.attributes ?? {})) prosody[key] = String(value);
+      for (const key of ["rate", "pitch", "volume", "contour", "range"]) {
+        const value = node[key];
+        if (value !== void 0) prosody[key] = String(value);
+      }
+      if (Object.keys(prosody).length > 0) context.prosody = prosody;
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  nodes.forEach(visit);
+  return context;
+}
+function createChunk(document, nodes, chunkIndex, textStart, backgroundAudio, replicateBackgroundAudio) {
+  const chunkNodes = backgroundAudio && (replicateBackgroundAudio || chunkIndex === 0) ? [backgroundAudio, ...nodes] : nodes;
+  const text = nodes.map(textFromNode).join("");
+  const marks = [];
+  for (const node of nodes) collectMarks(node, marks);
+  const inheritedContext = collectInheritedContext(nodes);
+  if (inheritedContext.lang === void 0 && document.lang) inheritedContext.lang = document.lang;
+  return {
+    chunkIndex,
+    ssml: documentWithChildren(document, chunkNodes),
+    originalTextRange: { start: textStart, end: textStart + text.length },
+    inheritedContext,
+    containedMarks: marks,
+    hasBackgroundAudio: chunkNodes.some(
+      (node) => typeof node !== "string" && node.type !== "text" && node.type === "mstts:backgroundaudio"
+    )
+  };
+}
+function splitSsmlDocument(ssml, maxLength = DEFAULT_MAX_LENGTH, options = {}) {
+  const resolvedMaxLength = typeof maxLength === "number" ? maxLength : maxLength.maxLength ?? DEFAULT_MAX_LENGTH;
+  const resolvedOptions = typeof maxLength === "number" ? options : maxLength;
+  if (!Number.isInteger(resolvedMaxLength) || resolvedMaxLength <= 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 backgroundAudio = (document.children ?? []).find(
+    (node) => typeof node !== "string" && node.type !== "text" && node.type === "mstts:backgroundaudio"
+  );
+  if (ssml.length <= resolvedMaxLength) {
+    return [createChunk(document, document.children ?? [], 0, 0, backgroundAudio, true)];
+  }
+  const contentChildren = (document.children ?? []).filter((node) => node !== backgroundAudio);
+  const plainDocumentLength = documentWithChildren(document, []).length;
+  const backgroundDocumentLength = backgroundAudio ? documentWithChildren(document, [backgroundAudio]).length : plainDocumentLength;
+  const backgroundOverhead = Math.max(0, backgroundDocumentLength - plainDocumentLength);
+  const contentMaxLength = Math.max(1, resolvedMaxLength - backgroundOverhead);
+  const splitChildren = contentChildren.flatMap((child) => splitNode(document, child, contentMaxLength));
   const chunks = [];
   let group = [];
   for (const child of splitChildren) {
     const candidate = [...group, child];
-    if (documentWithChildren(document, candidate).length <= maxLength) {
+    if (documentWithChildren(document, candidate).length <= contentMaxLength) {
       group = candidate;
       continue;
     }
     if (group.length > 0) chunks.push(group);
     group = [child];
-    if (documentWithChildren(document, group).length > maxLength) {
+    if (documentWithChildren(document, group).length > contentMaxLength) {
       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));
+  if (chunks.length === 0) {
+    const result = createChunk(document, [], 0, 0, backgroundAudio, resolvedOptions.replicateBackgroundAudio ?? false);
+    if (result.ssml.length > resolvedMaxLength) {
+      throw new RangeError("maxLength is too small to contain the SSML document wrapper");
+    }
+    return [result];
+  }
+  let textStart = 0;
+  return chunks.map((chunk, chunkIndex) => {
+    const result = createChunk(
+      document,
+      chunk,
+      chunkIndex,
+      textStart,
+      backgroundAudio,
+      resolvedOptions.replicateBackgroundAudio ?? false
+    );
+    textStart = result.originalTextRange.end;
+    return result;
+  });
 }
 
 // packages/ssml-core/src/validation.ts
@@ -2159,7 +2238,7 @@ function validateElement(token, source, diagnostics, voiceName, options, voiceCa
       addDiagnostic(diagnostics, source, token.start, "<mstts:backgroundaudio> must be self-closing.");
   }
 }
-function validateAzureSsml(ssml, options = {}) {
+function validateAzureSsmlStatic(ssml, options = {}) {
   const diagnostics = [];
   if (typeof ssml !== "string") {
     return [
@@ -2283,6 +2362,51 @@ function validateAzureSsml(ssml, options = {}) {
   }
   return diagnostics;
 }
+function urlAttributes(token) {
+  const tag = canonicalTagName(token.name);
+  const attributes = tag === "audio" || tag === "mstts:backgroundaudio" ? ["src"] : tag === "lexicon" ? ["uri"] : tag === "mstts:voiceconversion" ? ["url"] : [];
+  return attributes.flatMap((attribute) => {
+    const value = attr(token, attribute);
+    return value === void 0 ? [] : [{ attribute, value }];
+  });
+}
+function validateAzureSsml(ssml, options = {}) {
+  const diagnostics = validateAzureSsmlStatic(ssml, options);
+  const validator = options.urlValidator ?? options.customUrlValidator;
+  if (!validator || typeof ssml !== "string") return diagnostics;
+  let tokens;
+  try {
+    tokens = tokenizeElements(ssml);
+  } catch {
+    return diagnostics;
+  }
+  const checks = tokens.flatMap(
+    (token) => urlAttributes(token).map(async ({ attribute, value }) => {
+      try {
+        const result = await validator(value, { tag: token.name, attribute });
+        const valid = typeof result === "boolean" ? result : result.valid;
+        if (!valid) {
+          const reason = typeof result === "boolean" ? void 0 : result.reason;
+          addDiagnostic(
+            diagnostics,
+            ssml,
+            token.start,
+            `<${token.name} ${attribute}> was rejected by the custom URL validator${reason ? `: ${reason}` : "."}`
+          );
+        }
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        addDiagnostic(
+          diagnostics,
+          ssml,
+          token.start,
+          `<${token.name} ${attribute}> could not be validated by the custom URL validator: ${reason}`
+        );
+      }
+    })
+  );
+  return Promise.all(checks).then(() => diagnostics);
+}
 
 // packages/ssml-core/src/generated/azureVoiceCatalog.ts
 var AZURE_VOICE_CATALOG_METADATA = {