ssml-builder-js 2.13.0 → 2.14.0

package/README.md

@@ -911,8 +911,16 @@ result.bookmarks; // { name, audioOffsetMs }[]
 
 長文を分割して合成する場合は `synthesizeSsmlChunks` または `AzureTtsClient.synthesizeChunks` を使います。音声バイナリを連結し、`boundaries`、`visemes`、`bookmarks` のオフセットを累積 `durationMs` 分だけ補正します。`synthesizeSsmlSafe(client, ssml, { validation })` は検証エラー時に Azure API を呼び出さず、`status: "validation-error"` / `"azure-api-error"` / `"success"` の結果を返します。
 
+v2.14.0 では `synthesizeSsmlChunksSafe(client, chunks, options)` が全チャンクを事前検証し、エラー時に `ChunkValidationError.chunkIndex` を返します。`onProgress` には `chunkIndex`、`originalTextRange`、`status`、`durationMs`、`error` が含まれます。`mergeAudioBuffers(buffers, format)` は PCM WAV のヘッダーを再構築し、MP3 の ID3 タグを除去して結合します。Ogg/WebM など安全に連結できない形式は `UnsupportedMergeFormatError` になります。同期イベントには `chunkIndex`、`sourceNodePath`、`originalTextRange`、`chunkAudioOffsetMs` が付与されます。
+
+`validateAzureSsml` の `urlValidation` オプションは URL の重複排除、キャッシュ、`concurrency`、`signal`、`timeoutMs` を制御します。
+
 For long documents, use `synthesizeSsmlChunks` or `AzureTtsClient.synthesizeChunks`; `onProgress` reports completed chunks while audio and synchronization offsets are merged. `synthesizeSsmlSafe(client, ssml, { validation })` validates before synthesis and returns a discriminated result without calling Azure when static validation fails.
 
+In v2.14.0, `synthesizeSsmlChunksSafe(client, chunks, options)` validates every chunk before contacting Azure and returns a `ChunkValidationError` with its `chunkIndex` when validation fails. `onProgress` events include `chunkIndex`, `originalTextRange`, `status`, `durationMs`, and `error`. `mergeAudioBuffers(buffers, format)` rebuilds PCM WAV headers and strips ID3 tags from MP3 streams; formats such as Ogg and WebM throw `UnsupportedMergeFormatError` because they require re-multiplexing. Synchronization events retain `chunkIndex`, `sourceNodePath`, `originalTextRange`, and `chunkAudioOffsetMs`.
+
+The `urlValidation` option of `validateAzureSsml` provides URL deduplication, in-memory caching, bounded `concurrency`, `signal`, and `timeoutMs` controls.
+
 The public updater CLI is `npx ssml-builder sync-voices --region eastus --output ./azure-voices.json`. It reads the key from `AZURE_SPEECH_KEY` (or `--key`) and regions from `AZURE_SPEECH_REGION(S)` (or `--region(s)`).
 
 ```ts

package/dist/{chunk-25LOR4AJ.mjs → chunk-AQ55MOPU.mjs}

@@ -1034,6 +1034,34 @@ function collectInheritedContext(nodes) {
   nodes.forEach(visit);
   return context;
 }
+function elementName(node) {
+  return node.type === "custom" || node.type === "element" ? node.name : node.type;
+}
+function findSourceNodePath(nodes, targetOffset) {
+  let textOffset = 0;
+  let firstPath;
+  let foundPath;
+  const visit = (node, path) => {
+    if (typeof node === "string" || node.type === "text") {
+      const text = typeof node === "string" ? node : node.value;
+      if (text && firstPath === void 0) firstPath = [...path];
+      if (text && foundPath === void 0 && targetOffset < textOffset + text.length) foundPath = [...path];
+      textOffset += text.length;
+      return;
+    }
+    node.children?.forEach((child, index) => {
+      const childPath = typeof child === "string" || child.type === "text" ? path : [...path, `${elementName(child)}[${index}]`];
+      visit(child, childPath);
+    });
+  };
+  nodes.forEach((node, index) => {
+    if (!foundPath) {
+      if (typeof node === "string" || node.type === "text") visit(node, ["speak"]);
+      else visit(node, ["speak", `${elementName(node)}[${index}]`]);
+    }
+  });
+  return foundPath ?? firstPath;
+}
 function createChunk(document, nodes, chunkIndex, textStart, backgroundAudio, replicateBackgroundAudio) {
   const chunkNodes = backgroundAudio && (replicateBackgroundAudio || chunkIndex === 0) ? [backgroundAudio, ...nodes] : nodes;
   const text = nodes.map(textFromNode).join("");
@@ -1049,7 +1077,8 @@ function createChunk(document, nodes, chunkIndex, textStart, backgroundAudio, re
     containedMarks: marks,
     hasBackgroundAudio: chunkNodes.some(
       (node) => typeof node !== "string" && node.type !== "text" && node.type === "mstts:backgroundaudio"
-    )
+    ),
+    sourceNodePath: findSourceNodePath(document.children ?? [], textStart)
   };
 }
 function splitSsmlDocument(ssml, maxLength = DEFAULT_MAX_LENGTH, options = {}) {
@@ -1275,7 +1304,7 @@ async function mapSsmlTextNodes(ssml, transform, options = {}) {
 
 // packages/ssml-core/src/migration.ts
 var DEFAULT_TRANSLATION_SKIP_TAGS = ["phoneme", "say-as", "sayAs", "sub"];
-function elementName(element) {
+function elementName2(element) {
   switch (element.type) {
     case "custom":
     case "element":
@@ -1428,7 +1457,7 @@ function extractSsmlTranslatableText(ssml, options = {}) {
         }
         return;
       }
-      const tag = elementName(node);
+      const tag = elementName2(node);
       if (skipTags.has(tag.toLowerCase())) return;
       visit(childrenOf(node), [...ancestors, tag], [...path, String(index)]);
     });
@@ -1474,7 +1503,7 @@ function serializeDocument2(document) {
   const serialize = (node) => {
     if (typeof node === "string") return node.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
     if (node.type === "text") return serialize(node.value);
-    const tag = elementName(node);
+    const tag = elementName2(node);
     const nodeAttributes = elementAttributes(node);
     const serializedAttributes = Object.entries(nodeAttributes).map(([name, value]) => ` ${name}="${serialize(value).replace(/"/g, "&quot;")}"`).join("");
     const children = childrenOf(node).map(serialize).join("");
@@ -1488,7 +1517,7 @@ function flatten(document) {
     nodes.forEach((node, index) => {
       if (typeof node === "string" || node.type === "text") return;
       const currentPath = `${path}/${index}`;
-      result.push({ name: elementName(node), attributes: elementAttributes(node), path: currentPath });
+      result.push({ name: elementName2(node), attributes: elementAttributes(node), path: currentPath });
       visit(childrenOf(node), currentPath);
     });
   };
@@ -1686,6 +1715,69 @@ var AZURE_VOICE_DEFINITIONS = [
 ];
 
 // packages/ssml-core/src/azureValidation.ts
+function createAzureUrlValidatorRunner(validator, options = {}) {
+  if (typeof validator !== "function") throw new TypeError("A URL validator function is required.");
+  const concurrency = options.concurrency === void 0 ? Infinity : Number.isFinite(options.concurrency) ? Math.max(1, Math.floor(options.concurrency)) : Infinity;
+  const cache = options.cache ?? /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  const waiters = [];
+  let active = 0;
+  const acquire = async () => {
+    if (active < concurrency) {
+      active += 1;
+      return;
+    }
+    await new Promise((resolve) => waiters.push(resolve));
+    active += 1;
+  };
+  const release = () => {
+    active -= 1;
+    waiters.shift()?.();
+  };
+  const check = async (url, context) => {
+    if (options.signal?.aborted) throw new Error("URL validation was aborted.");
+    const cached = cache.get(url);
+    if (cached !== void 0) return cached;
+    const existing = inFlight.get(url);
+    if (existing) return existing;
+    const promise = (async () => {
+      await acquire();
+      try {
+        if (options.signal?.aborted) throw new Error("URL validation was aborted.");
+        const validation = Promise.resolve(validator(url, context));
+        let timer;
+        let abortHandler;
+        const cancellation = new Promise((_resolve, reject) => {
+          abortHandler = () => reject(new Error("URL validation was aborted."));
+          options.signal?.addEventListener("abort", abortHandler, { once: true });
+          if (options.timeoutMs !== void 0 && options.timeoutMs > 0) {
+            timer = setTimeout(
+              () => reject(new Error(`URL validation timed out after ${options.timeoutMs} ms.`)),
+              options.timeoutMs
+            );
+          }
+        });
+        try {
+          const result = await (timer || abortHandler ? Promise.race([validation, cancellation]) : validation);
+          cache.set(url, result);
+          return result;
+        } finally {
+          if (timer) clearTimeout(timer);
+          if (abortHandler) options.signal?.removeEventListener("abort", abortHandler);
+        }
+      } finally {
+        release();
+      }
+    })();
+    inFlight.set(url, promise);
+    try {
+      return await promise;
+    } finally {
+      inFlight.delete(url);
+    }
+  };
+  return (url, context) => check(url, context);
+}
 var ALLOWED_BREAK_STRENGTHS = /* @__PURE__ */ new Set(["none", "x-weak", "weak", "medium", "strong", "x-strong"]);
 var ALLOWED_SAY_AS = /* @__PURE__ */ new Set([
   "characters",
@@ -1980,23 +2072,23 @@ function validateVoiceFeatureMatrix(token, source, diagnostics, voiceName, defin
     );
   }
 }
-function validateAudioSource(token, source, diagnostics, options, elementName2) {
+function validateAudioSource(token, source, diagnostics, options, elementName3) {
   const src = attr(token, "src");
   if (!src) {
-    addDiagnostic(diagnostics, source, token.start, `<${elementName2}> requires a "src" attribute.`);
+    addDiagnostic(diagnostics, source, token.start, `<${elementName3}> requires a "src" attribute.`);
     return;
   }
   let parsed;
   try {
     parsed = new URL(src);
   } catch {
-    addDiagnostic(diagnostics, source, token.start, `<${elementName2} src> must be an absolute HTTP(S) URL.`);
+    addDiagnostic(diagnostics, source, token.start, `<${elementName3} 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.`);
+    addDiagnostic(diagnostics, source, token.start, `<${elementName3} 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.`);
+    addDiagnostic(diagnostics, source, token.start, `<${elementName3} src> must use HTTPS.`);
   const isAllowedOrigin = options.allowedAudioOrigins?.some((allowedOrigin) => {
     try {
       const configured = new URL(allowedOrigin);
@@ -2008,13 +2100,13 @@ function validateAudioSource(token, source, diagnostics, options, elementName2)
     }
   }) ?? false;
   if (options.allowedAudioOrigins && !isAllowedOrigin)
-    addDiagnostic(diagnostics, source, token.start, `<${elementName2} src> origin "${parsed.origin}" is not allowed.`);
+    addDiagnostic(diagnostics, source, token.start, `<${elementName3} src> origin "${parsed.origin}" is not allowed.`);
   else if (!isAllowedOrigin && !options.allowExternalAudio)
     addDiagnostic(
       diagnostics,
       source,
       token.start,
-      `<${elementName2} src> external origin "${parsed.origin}" is blocked by default; set allowExternalAudio to true or provide allowedAudioOrigins.`
+      `<${elementName3} src> external origin "${parsed.origin}" is blocked by default; set allowExternalAudio to true or provide allowedAudioOrigins.`
     );
 }
 function validateElement(token, source, diagnostics, voiceName, options, voiceCatalog) {
@@ -2332,6 +2424,14 @@ function validateAzureSsml(ssml, options = {}) {
   const diagnostics = validateAzureSsmlStatic(ssml, options);
   const validator = options.urlValidator ?? options.customUrlValidator;
   if (!validator || typeof ssml !== "string") return diagnostics;
+  const runnerOptions = options.urlValidation ?? {};
+  const boundedValidator = createAzureUrlValidatorRunner(validator, {
+    ...runnerOptions,
+    ...options.urlValidatorConcurrency !== void 0 ? { concurrency: options.urlValidatorConcurrency } : {},
+    ...options.urlValidatorTimeoutMs !== void 0 ? { timeoutMs: options.urlValidatorTimeoutMs } : {},
+    ...options.urlValidatorSignal ? { signal: options.urlValidatorSignal } : {},
+    ...options.urlValidatorCache ? { cache: options.urlValidatorCache } : {}
+  });
   let tokens;
   try {
     tokens = tokenizeElements(ssml);
@@ -2341,7 +2441,7 @@ function validateAzureSsml(ssml, options = {}) {
   const checks = tokens.flatMap(
     (token) => urlAttributes(token).map(async ({ attribute, value }) => {
       try {
-        const result = await validator(value, { tag: token.name, attribute });
+        const result = await boundedValidator(value, { tag: token.name, attribute });
         const valid = typeof result === "boolean" ? result : result.valid;
         if (!valid) {
           const reason = typeof result === "boolean" ? void 0 : result.reason;
@@ -2394,6 +2494,7 @@ export {
   extractSsmlTranslatableText,
   fromPlainTextToSsml,
   validateSsmlStructureIntegrity,
+  createAzureUrlValidatorRunner,
   isValidAzureAudioDuration,
   normalizeAzureLanguage,
   areAzureLanguagesEquivalent,
@@ -2401,4 +2502,4 @@ export {
   getAzureVoiceCatalogMetadata,
   getBuiltInVoiceCatalogMetadata
 };
-//# sourceMappingURL=chunk-25LOR4AJ.mjs.map
+//# sourceMappingURL=chunk-AQ55MOPU.mjs.map