ssml-builder-js 2.12.0 → 2.13.0

package/README.md

@@ -240,6 +240,8 @@ const diagnostics = validateAzureSsml(ssml, {
 });
 ```
 
+`audio`、`mstts:backgroundaudio`、`lexicon`、`mstts:voiceconversion` の URL は `urlValidator`（または `customUrlValidator`）へ渡せます。Promise を返す検証関数で DNS 解決後のプライベート IP 遮断などを実装できます。
+
 `maxXmlDepth` は `<speak>` を深さ 1 として XML の過剰なネストを検出します。長文は `splitSsmlDocument` で `<p>`／`<s>` と親の `voice`、`prosody` コンテキストを保ったまま分割できます。
 
 ```ts
@@ -248,10 +250,12 @@ import { splitSsmlDocument } from "ssml-builder-js/core";
 const blocks = splitSsmlDocument(longSsml, 10_000);
 for (const block of blocks) {
   // 各 block は独立した <speak> 文書として Azure へ送信できます。
-  await client.synthesize(block);
+  await client.synthesize(block.ssml);
 }
 ```
 
+各ブロックは `SsmlChunk`（`chunkIndex`、`originalTextRange`、継承した音声/言語/韻律、内包マーク、背景音声の有無）です。`<mstts:backgroundaudio>` はデフォルトで先頭チャンクだけに含まれ、全チャンクへ複製する場合は `splitSsmlDocument(longSsml, 10_000, { replicateBackgroundAudio: true })` を指定します。
+
 Azure Speech は `<audio>` の URL を取得するため、任意の URL をそのまま受け付けるサーバーは SSRF の踏み台になり得ます。ユーザー入力の SSML を合成する場合は、HTTPS、許可オリジン、リダイレクト先、応答サイズをサーバー側でも制限し、`allowExternalAudio` だけで無制限に許可しないでください。
 
 ## `ssml-editor-react` の利用方法
@@ -336,6 +340,8 @@ export function App() {
 - `insertionGroups`: 挿入メニューを縦線で区切るグループ設定。`toolbarGroups` を省略した場合は、この設定からツールバーの既定グループも作成されます。省略時は間・無音、声の調整、表現、読み上げに分けて表示されます
 - `emotionStyles`: `emotion` メニューに表示する音声スタイル候補
 - `customInsertions` / `additionalInsertions`: カスタム SSML 挿入定義。`customInsertions` は同じ ID の標準定義を置き換え、`additionalInsertions` は標準定義へ追加します
+- `customInspectors`: Visual Editor のタグ名ごとに Inspector を差し替えるレンダラー
+- `renderVoiceSelector`: 音声セレクターのカスタムレンダラー。`voiceCatalog` と `voiceLocale`、`voiceRegion`、`voiceStyle` で候補を絞り込めます。プレビュー音声にはバッジ情報も渡されます
 - `className` / `style`: エディター全体のクラス名とインラインスタイル
 - `toolbarClassName` / `toolbarStyle`: ツールバーのクラス名とインラインスタイル
 - `displayClassName` / `displayStyle`: 本文表示エリアのクラス名とインラインスタイル
@@ -702,6 +708,8 @@ const diagnostics = validateAzureSsml(ssml, {
 });
 ```
 
+URLs in `audio`, `mstts:backgroundaudio`, `lexicon`, and `mstts:voiceconversion` can be passed to `urlValidator` (or `customUrlValidator`). The callback may be asynchronous, making it suitable for host-side DNS/private-IP and SSRF policy checks.
+
 The catalog is represented by `AzureVoiceDefinition` with `name`, `locale`, optional `secondaryLocales`, `styles`, `supportedTags`, `unsupportedTags`, `models`, `regions`, and `status`. Pass `voiceDefinitions` (or `voiceCatalog`) to supplement or override the built-in catalog with an external definition. A tag that violates `supportedTags` or `unsupportedTags` produces `azure-unsupported-tag-for-voice` with error severity. `customVoiceStyleMap` remains supported for backward compatibility and overrides styles for the named voice. Diagnostics distinguish an unregistered voice (`azure-unknown-voice`, controlled by `unknownVoicePolicy`), an unsupported style on a registered voice (`azure-unsupported-style`), and a locale mismatch (`azure-locale-mismatch`). The `<mstts:audioduration value="10s"/>` element accepts positive `ms` or `s` values and `hh:mm:ss[.fff]` clock values.
 
 `npm run sync:voices -- --regions eastus,japaneast` fetches Azure's List Voices API for each region, deduplicates the results, and updates the generated TypeScript definitions plus `azureVoiceCatalog.json` with generation time, API version, regions, and voice count. Provide credentials through `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION(S)`, or CLI options.
@@ -735,6 +743,17 @@ const diagnostics = validateAzureSsml(ssml, {
 
 Azure Speech fetches `<audio>` URLs, so a server that accepts arbitrary user-provided SSML can become an SSRF proxy. For untrusted SSML, enforce HTTPS, an origin allowlist, redirect policy, and response-size limits on the server; do not treat `allowExternalAudio` as a substitute for those controls.
 
+Long documents can be split into independently synthesizable `SsmlChunk` values:
+
+```ts
+import { splitSsmlDocument } from "ssml-builder-js/core";
+
+const chunks = splitSsmlDocument(longSsml, 10_000);
+for (const chunk of chunks) await client.synthesize(chunk.ssml);
+```
+
+Each chunk includes `chunkIndex`, `originalTextRange`, inherited voice/language/prosody context, contained markers, and background-audio state. Background audio is placed in the first chunk by default; pass `{ replicateBackgroundAudio: true }` as the third argument to include it in every chunk.
+
 ## Using `ssml-editor-react`
 
 `SsmlEditor` accepts an `SsmlDocument` and renders only a toolbar and text display area. The toolbar applies rate, volume, and pitch settings to the selection and provides undo and redo actions. The application is responsible for selecting and displaying the voice. Monaco Editor is used for text editing, and SSML syntax is validated whenever the text changes. Syntax errors are shown with editor markers and an error message. Hovering over XML tag names or parameters shows SSML descriptions. Selecting text displays a floating action bar with the character count and preview action. When `enableCodeLens` is enabled (the default), CodeLens quick controls for editing and unwrapping `prosody` tags and editing or deleting `break` tags are shown above those tags. When `showDecorations` is enabled, inline badges for pause and pitch changes are rendered next to `break` and `prosody` tags, and Monaco inline decorations are enabled. Generated SSML is provided through `onSsmlChange` so the application can display it wherever it needs. Pass an `SsmlEditorRef` through `ref` to retrieve full, selected, or current-line SSML, and use `onSelectionChange` to observe selection text and state. The UI supports Japanese (the default) and English.
@@ -813,6 +832,8 @@ export function App() {
 - `insertionGroups`: Groups insertion menus with vertical separators; when `toolbarGroups` is omitted, these groups also define the default toolbar groups. Menus are grouped into pauses, voice, expression, and pronunciation by default
 - `emotionStyles`: Candidate voice styles shown by the `emotion` menu
 - `customInsertions` / `additionalInsertions`: Custom SSML insertion definitions. `customInsertions` replaces a built-in definition with the same ID, while `additionalInsertions` adds definitions to the built-ins
+- `customInspectors`: Custom renderers keyed by element type or serialized tag name for the Visual Editor
+- `renderVoiceSelector`: Custom voice selector renderer. Supply `voiceCatalog` and optional `voiceLocale`, `voiceRegion`, or `voiceStyle` filters; preview status is included in each voice entry
 - `className` / `style`: A class name and inline styles for the editor container
 - `toolbarClassName` / `toolbarStyle`: A class name and inline styles for the toolbar
 - `displayClassName` / `displayStyle`: A class name and inline styles for the text display area
@@ -888,6 +909,10 @@ result.visemes; // { visemeId, audioOffsetMs }[]
 result.bookmarks; // { name, audioOffsetMs }[]
 ```
 
+長文を分割して合成する場合は `synthesizeSsmlChunks` または `AzureTtsClient.synthesizeChunks` を使います。音声バイナリを連結し、`boundaries`、`visemes`、`bookmarks` のオフセットを累積 `durationMs` 分だけ補正します。`synthesizeSsmlSafe(client, ssml, { validation })` は検証エラー時に Azure API を呼び出さず、`status: "validation-error"` / `"azure-api-error"` / `"success"` の結果を返します。
+
+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.
+
 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-4BVNAUVR.mjs → chunk-25LOR4AJ.mjs}

@@ -1003,30 +1003,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
@@ -2117,7 +2196,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 [
@@ -2241,6 +2320,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 = {
@@ -2277,4 +2401,4 @@ export {
   getAzureVoiceCatalogMetadata,
   getBuiltInVoiceCatalogMetadata
 };
-//# sourceMappingURL=chunk-4BVNAUVR.mjs.map
+//# sourceMappingURL=chunk-25LOR4AJ.mjs.map