ssml-builder-js 2.6.0 → 2.8.0

package/README.md

@@ -136,7 +136,7 @@ const parsed = parseSsml(ssml);
 | `validateSsml(xml)` | SSML の構文エラーを `{ message, position }` または `null` で返す |
 | `extractSsmlText(xml)` | タグを除いた全テキストノードを文書順に抽出 |
 | `mapSsmlTextNodes(xml, transform, options?)` | タグ構造を維持したままテキストノードだけを同期・非同期変換。スキップタグとコンテキストフィルターに対応 |
-| `validateAzureSsml(xml, options?)` | Azure Speech 向けの意味検証結果を Diagnostic 配列で返す |
+| `validateAzureSsml(xml, options?)` | Azure Speech 向けの意味検証結果を Diagnostic 配列で返す（各診断に `source: "ssml-static-validator"` を付与） |
 
 ### 3段階の検証モデル
 
@@ -150,6 +150,8 @@ SSML の検証は、構文、Azure 固有の静的な意味、実サービスの
 
 `voice`、`prosody`、`break`、`express-as`、`say-as`、`phoneme`、`audio`、`lang`、`mark` などの要素を型付きで表現できます。`type: "custom"` と `name` を指定すれば、未定義の XML 要素や追加属性も扱えます。`mstts:` 要素を含むドキュメントを生成すると、必要な Azure Speech 名前空間が自動的に追加されます。
 
+`validateAzureSsml` は Azure Speech へ送信する前に実行する事前静的チェックです。返却される診断の `source` はパッケージ側の静的解析結果であることを示し、Azure Speech サービス側でのランタイム生成結果や実際の合成可否を表すものではありません。
+
 翻訳などで本文だけを置き換える場合は、`mapSsmlTextNodes` に変換関数を渡します。変換関数には直近の親タグと祖先タグの `path` が渡され、戻り値は `string` または `Promise<string>` を指定できます。`validateAzureSsml` は音声、属性値、音声スタイル、文字数、`audio` URL/オリジンを検証します。
 
 `mapSsmlTextNodes` の第 3 引数で、翻訳対象外タグとコンテキストフィルターを指定できます。デフォルトでは `phoneme`、`say-as`、`sub` の本文を変換しません。`filter` には `parentTag`、`parentAttributes`、`ancestorTags`、`path` が渡されます。
@@ -162,7 +164,33 @@ const translated = await mapSsmlTextNodes(ssml, translate, {
 });
 ```
 
-`validateAzureSsml` は `AzureValidationOptions` で音声・スタイルの定義を追加できます。Azure の音声・スタイル一覧はサービス更新やリージョン差分があるため、組み込み一覧は固定の完全な台帳ではありません。新しい音声を一覧の更新前から使う場合や既存音声のスタイルを上書きする場合は、`customVoiceStyleMap` に同じ音声名を指定すれば、その呼び出しで直ちに置き換えられます。未知音声をデフォルトの `unknownVoicePolicy: "warn"` で警告に留めるのは、一覧更新前の音声、カスタム音声、リージョン限定音声を静的検証で不必要にブロックしないためです。厳格なデプロイ前検査では `"error"`、台帳外の音声を利用する構成では `"ignore"` も選択できます。`validateNestedVoices` のデフォルトは `true` です。`audio` の外部 URL はデフォルトで拒否されるため、利用する場合は `allowedAudioOrigins` に許可するオリジンを列挙するか、構成を理解した上で `allowExternalAudio: true` を指定してください。
+`validateAzureSsml` は `AzureValidationOptions` で音声・スタイルの定義を追加できます。言語比較は `Intl.Locale` を使って BCP 47 として正規化し、組み込みで `zh-Hans` と `zh-CN`、`zh-Hant` と `zh-TW` を同一視します。独自の別名や正規化関数も注入できます。
+
+```ts
+const diagnostics = validateAzureSsml(ssml, {
+  languageAliases: { "ja": ["ja-JP", "ja-Japan"] },
+  normalizeLanguage: (language) => language.replace("_", "-"),
+});
+```
+
+音声カタログは `AzureVoiceDefinition` の `name`、`locale`、`secondaryLocales`、`styles` で表現できます。`voiceDefinitions`（または `voiceCatalog`）を渡すと、組み込み台帳を外部定義で補完・上書きできます。`customVoiceStyleMap` は既存利用者向けに引き続き利用でき、指定した音声のスタイルを上書きします。組み込み台帳にない音声は `azure-unknown-voice`（`unknownVoicePolicy` に従う）、登録済み音声への非対応スタイルは `azure-unsupported-style`、ロケール不一致は `azure-locale-mismatch` として区別されます。
+
+```ts
+const diagnostics = validateAzureSsml(ssml, {
+  voiceDefinitions: [
+    {
+      name: "my-custom-voice",
+      locale: "ja-JP",
+      secondaryLocales: ["zh-Hant"],
+      styles: ["narration"],
+    },
+  ],
+  unknownVoicePolicy: "error", // "error" | "warn" | "ignore"
+  allowedAudioOrigins: ["https://cdn.example.com"],
+});
+```
+
+Azure の音声・スタイル一覧はサービス更新やリージョン差分があるため、組み込み一覧は固定の完全な台帳ではありません。新しい音声を完全に静的検証したい場合は、音声名だけでなくロケールとスタイルを `voiceDefinitions` に定義してください。`validateNestedVoices` のデフォルトは `true` です。`audio` の外部 URL はデフォルトで拒否されるため、利用する場合は `allowedAudioOrigins` に許可するオリジンを列挙するか、構成を理解した上で `allowExternalAudio: true` を指定してください。
 
 ```ts
 const diagnostics = validateAzureSsml(ssml, {
@@ -516,7 +544,7 @@ The main `buildSsml` and `parseSsml` signatures are:
 | `validateSsml(xml)` | Returns `{ message, position }` for a syntax error, or `null` |
 | `extractSsmlText(xml)` | Extracts all text nodes in document order |
 | `mapSsmlTextNodes(xml, transform, options?)` | Transforms only text nodes while preserving the XML structure; supports sync/async transforms, skipped tags, and context filters |
-| `validateAzureSsml(xml, options?)` | Returns Azure Speech semantic-validation diagnostics |
+| `validateAzureSsml(xml, options?)` | Returns Azure Speech semantic-validation diagnostics (each diagnostic has `source: "ssml-static-validator"`) |
 
 ### Three-stage validation model
 
@@ -530,6 +558,8 @@ SSML validation separates XML syntax, Azure-specific static semantics, and runti
 
 Typed representations are available for elements such as `voice`, `prosody`, `break`, `express-as`, `say-as`, `phoneme`, `audio`, `lang`, and `mark`. Use `type: "custom"` and `name` to handle undefined XML elements or additional attributes. When a document contains `mstts:` elements, the required Azure Speech namespace is added automatically.
 
+`validateAzureSsml` is a preflight static check performed by this package before sending SSML to Azure Speech. The `source` on each returned diagnostic identifies package-side static analysis; it is independent of Azure Speech's runtime generation result and does not guarantee that synthesis will succeed.
+
 Use `mapSsmlTextNodes` to replace translatable content without changing tags, attributes, or nesting. The transform receives the immediate parent tag and ancestor `path`, and may return a `string` or a `Promise<string>`. The third argument supports `skipTags` and a `filter` callback; `phoneme`, `say-as`, and `sub` are skipped by default. The callback receives `parentTag`, decoded `parentAttributes`, `ancestorTags`, and `path`.
 
 ```ts
@@ -540,7 +570,33 @@ const translated = await mapSsmlTextNodes(ssml, translate, {
 });
 ```
 
-`validateAzureSsml` accepts `AzureValidationOptions` for extending the voice/style map. Azure's voice and style catalog changes over time and can differ by region, so the built-in map is a fixed snapshot rather than a complete live catalog. To use a newly released voice before the built-in map is updated, or to replace the styles for an existing voice, pass the same voice name through `customVoiceStyleMap`; that entry takes effect immediately for the call. Unknown voices default to `unknownVoicePolicy: "warn"` so catalog lag, custom voices, and region-limited voices do not get unnecessarily blocked by static validation. Use `"error"` for strict pre-deployment checks or `"ignore"` when the deployment intentionally operates outside the built-in catalog. `validateNestedVoices` defaults to `true`. External `<audio>` URLs are blocked by default; provide `allowedAudioOrigins` or explicitly set `allowExternalAudio: true` only when the deployment is configured to control those requests.
+`validateAzureSsml` accepts `AzureValidationOptions` for extending the voice/style catalog. Language comparison uses `Intl.Locale` and BCP 47 normalization; the built-in aliases treat `zh-Hans` and `zh-CN`, and `zh-Hant` and `zh-TW`, as equivalent. Custom aliases or a custom normalizer can be injected as well.
+
+```ts
+const diagnostics = validateAzureSsml(ssml, {
+  languageAliases: { ja: ["ja-JP", "ja-Japan"] },
+  normalizeLanguage: (language) => language.replace("_", "-"),
+});
+```
+
+The catalog is represented by `AzureVoiceDefinition` with `name`, `locale`, optional `secondaryLocales`, and optional `styles`. Pass `voiceDefinitions` (or `voiceCatalog`) to supplement or override the built-in catalog with an external definition. `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`).
+
+```ts
+const diagnostics = validateAzureSsml(ssml, {
+  voiceDefinitions: [
+    {
+      name: "my-custom-voice",
+      locale: "ja-JP",
+      secondaryLocales: ["zh-Hant"],
+      styles: ["narration"],
+    },
+  ],
+  unknownVoicePolicy: "error", // "error" | "warn" | "ignore"
+  allowedAudioOrigins: ["https://cdn.example.com"],
+});
+```
+
+Azure's voice and style catalog changes over time and can differ by region, so the built-in catalog is a fixed snapshot rather than a complete live catalog. For complete static validation of a new voice, define its name, locale, and supported styles in `voiceDefinitions`. `validateNestedVoices` defaults to `true`. External `<audio>` URLs are blocked by default; provide `allowedAudioOrigins` or explicitly set `allowExternalAudio: true` only when the deployment is configured to control those requests.
 
 ```ts
 const diagnostics = validateAzureSsml(ssml, {

package/dist/{chunk-GF4QZHLJ.mjs → chunk-4RQETJUI.mjs}

@@ -3510,4 +3510,4 @@ export {
   findSsmlHoverTarget,
   formatSsmlHover
 };
-//# sourceMappingURL=chunk-GF4QZHLJ.mjs.map
+//# sourceMappingURL=chunk-4RQETJUI.mjs.map