ssml-builder-js 2.15.0 → 2.17.0

package/README.md

@@ -165,7 +165,7 @@ const parsed = parseSsml(ssml);
 | `fromPlainTextToSsml(text, options?)` | プレーンテキストを `<speak>`、段落 `<p>`、文 `<s>` を含む SSML に変換 |
 | `validateSsmlStructureIntegrity(original, translated)` | 翻訳前後のタグ階層・タグ名・属性の一致を検証 |
 | `validateAzureSsml(xml, options?)` | Azure Speech 向けの意味検証結果を Diagnostic 配列で返す（各診断に `source: "ssml-static-validator"` を付与） |
-| `getAzureVoiceCatalogMetadata()` / `getBuiltInVoiceCatalogMetadata()` | 組み込み音声カタログの生成日時、API バージョン、リージョン、収録数を返す |
+| `getAzureVoiceCatalogMetadata()` / `getBuiltInVoiceCatalogMetadata()` | 組み込み音声カタログの生成日時、API バージョン、リージョン、収録数、有効期限、リージョン差分を返す |
 
 ### 3段階の検証モデル
 
@@ -670,7 +670,7 @@ The main `buildSsml` and `parseSsml` signatures are:
 | `fromPlainTextToSsml(text, options?)` | Converts plain text into an initial `<speak>` document containing paragraphs (`<p>`) and sentences (`<s>`) |
 | `validateSsmlStructureIntegrity(original, translated)` | Checks that tag hierarchy, element names, and attributes are unchanged after translation |
 | `validateAzureSsml(xml, options?)` | Returns Azure Speech semantic-validation diagnostics (each diagnostic has `source: "ssml-static-validator"`) |
-| `getAzureVoiceCatalogMetadata()` / `getBuiltInVoiceCatalogMetadata()` | Returns generation time, API version, regions, and voice count for the bundled voice catalog |
+| `getAzureVoiceCatalogMetadata()` / `getBuiltInVoiceCatalogMetadata()` | Returns generation time, API version, regions, voice count, expiry, and known regional differences for the bundled voice catalog |
 
 ### Three-stage validation model
 
@@ -913,7 +913,11 @@ 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.15.0 では `synthesizeSsmlChunksSafe(client, chunks, options)` が全チャンクを事前検証し、`outputFormat`、`signal`、`timeoutMs`、`sourceNodePath` を各合成へ伝播します。`mergeAudioBuffers(buffers, { format })` と `mergeSynthesisResults(results, { format })` は形式指定を必須とし、結合結果には `mimeType` が含まれます。Ogg/WebM などは `customMerger` で外部 Muxer に委譲できます。エラーは `validation-error`、`azure-api-error`、`merge-error`、`unsupported-format-error`、`cancelled`、`timeout` の判別可能な `kind` を持ちます。同期イベントは個別の `sourceNodePath` と `originalTextRange` にマッピングされ、URL 検証コールバックには `AbortSignal` が渡されます。
+ v2.15.0 では `synthesizeSsmlChunksSafe(client, chunks, options)` が全チャンクを事前検証し、`outputFormat`、`signal`、`timeoutMs`、`sourceNodePath` を各合成へ伝播します。`mergeAudioBuffers(buffers, { format })` と `mergeSynthesisResults(results, { format })` は形式指定を必須とし、結合結果には `mimeType` が含まれます。Ogg/WebM などは `customMerger` で外部 Muxer に委譲できます。エラーは `validation-error`、`azure-api-error`、`merge-error`、`unsupported-format-error`、`cancelled`、`timeout` の判別可能な `kind` を持ちます。同期イベントは個別の `sourceNodePath` と `originalTextRange` にマッピングされ、URL 検証コールバックには `AbortSignal` が渡されます。
+
+v2.16.0 では `concurrency` と `retryOptions`（429/5xx・ネットワーク障害のみ、Jitter 付き指数バックオフ）でチャンク合成を制御できます。`onProgress` には `retryAttempt`、`nextRetryDelayMs`、`isRetrying` が追加され、結合は常に `chunkIndex` 順です。`SsmlSynthesisResult.audioSpec` は WAV/MP3 ヘッダーから音声仕様を抽出し、チャンク間の仕様不一致は `AudioFormatMismatchError` になります。同期イベントには `mappingStatus`、Azure 診断には `nodePath`、`range`、`tagName`、`attributeName`、`voiceName`、`chunkIndex` が含まれます。`validateAzureSsmlChunks` は URL 検証プールを全チャンクで共有し、カスタム結合器には `inputSpecs` と `signal` を渡します。
+
+v2.17.0 では `customMerger`、`outputMimeType`、`postMergeValidator` をチャンク合成の末尾まで構成でき、`BatchChunkValidationError` が全チャンクの診断と総エラー数を返します。`cancelOnFailure` と `resumeChunks` により成功済みバイナリを再利用でき、`timeouts`（URL 検証、チャンク、リトライ込みチャンク、ジョブ全体）を個別に設定できます。429 の `Retry-After` は指数バックオフより優先されます。`AudioSpecification` には `bitDepth`、`container`、`isVbr` が追加され、同期 `mappingStatus` は JSON 化後も保持されます。
 
 `validateAzureSsml` の `urlValidation` オプションは URL の重複排除、キャッシュ、`concurrency`、`signal`、`timeoutMs` を制御します。
 
@@ -921,6 +925,10 @@ For long documents, use `synthesizeSsmlChunks` or `AzureTtsClient.synthesizeChun
 
 In v2.15.0, `synthesizeSsmlChunksSafe(client, chunks, options)` validates every chunk before contacting Azure and propagates `outputFormat`, `signal`, `timeoutMs`, and `sourceNodePath` to each synthesis. `mergeAudioBuffers(buffers, { format })` and `mergeSynthesisResults(results, { format })` require an explicit format and merged results expose `mimeType`. Ogg and WebM can be delegated to an external Muxer through `customMerger`. Errors have discriminated `kind` values: `validation-error`, `azure-api-error`, `merge-error`, `unsupported-format-error`, `cancelled`, and `timeout`. Synchronization events receive individual `sourceNodePath` and `originalTextRange` mappings, and URL validators receive an `AbortSignal`.
 
+In v2.16.0, use `concurrency` and `retryOptions` to control chunk synthesis; only 429/5xx and network failures are retried with jittered exponential backoff. Progress events include `retryAttempt`, `nextRetryDelayMs`, and `isRetrying`, while merging always follows `chunkIndex` order. `SsmlSynthesisResult.audioSpec` is extracted from WAV/MP3 headers, and incompatible chunk specs throw `AudioFormatMismatchError`. Synchronization events include `mappingStatus`, diagnostics include structured node/range/tag/attribute/voice/chunk fields, `validateAzureSsmlChunks` shares one URL validation pool, and custom mergers receive `inputSpecs` and an `AbortSignal`.
+
+In v2.17.0, configure `customMerger`, `outputMimeType`, and `postMergeValidator` through the chunk synthesis pipeline. `BatchChunkValidationError` aggregates diagnostics and the total error count for every invalid chunk. `cancelOnFailure` and `resumeChunks` allow successful binary chunks to be reused, while `timeouts` independently bounds URL validation, individual chunks, retries, and the total job. HTTP 429 `Retry-After` takes priority over exponential backoff. `AudioSpecification` now includes `bitDepth`, `container`, and `isVbr`, and `mappingStatus` remains present after JSON serialization.
+
 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)`).

package/dist/{chunk-FXUM45ZY.mjs → chunk-2SYLELUT.mjs}

@@ -2015,6 +2015,7 @@ function tokenizeElements(source) {
     if (parent) parent.childElementCount += 1;
     const parentVoiceName = [...openElements].reverse().find((element) => element.voiceName)?.voiceName;
     const tokenName = nameMatch[1];
+    const path = parent ? [...parent.path, `${tokenName}[${childElementIndex ?? 0}]`] : [tokenName];
     const tokenVoiceName = tokenName.toLowerCase() === "voice" ? attributes.get("name") : tokenName.toLowerCase() === "mstts:turn" ? attributes.get("voice") ?? parentVoiceName : parentVoiceName;
     tokens.push({
       attributes,
@@ -2025,12 +2026,14 @@ function tokenizeElements(source) {
       parentName: parent?.name,
       parentVoiceName,
       selfClosing,
-      start
+      start,
+      path
     });
     if (!selfClosing) {
       openElements.push({
         childElementCount: 0,
         name: tokenName,
+        path,
         voiceName: tokenVoiceName
       });
     }
@@ -2043,13 +2046,14 @@ function location(source, offset) {
   const line = before.split("\n").length;
   return { line, column: before.length - (before.lastIndexOf("\n") + 1) + 1 };
 }
-function addDiagnostic(diagnostics, source, offset, message, severity = "error", code) {
+function addDiagnostic(diagnostics, source, offset, message, severity = "error", code, metadata = {}) {
   diagnostics.push({
     ...location(source, offset),
     message,
     severity,
     source: "ssml-static-validator",
-    ...code ? { code } : {}
+    ...code ? { code } : {},
+    ...metadata
   });
 }
 function isSupportedProsodyRate(value) {
@@ -2522,9 +2526,11 @@ function validateAzureSsmlStatic(ssml, options = {}) {
   for (const token of tokens) {
     const tokenName = token.name.toLowerCase();
     const tokenVoiceName = tokenName === "voice" ? attr(token, "name")?.trim() : tokenName === "mstts:turn" ? attr(token, "voice")?.trim() || token.parentVoiceName : options.validateNestedVoices === false ? voiceName : token.parentVoiceName;
+    const tokenDiagnosticStart = diagnostics.length;
     validateElement(token, ssml, diagnostics, tokenVoiceName, options, voiceCatalog);
     const definition = tokenVoiceName ? voiceCatalog.get(tokenVoiceName.toLowerCase()) : void 0;
     validateVoiceFeatureMatrix(token, ssml, diagnostics, tokenVoiceName, definition);
+    annotateTokenDiagnostics(diagnostics, tokenDiagnosticStart, token, options, tokenVoiceName);
     if (tokenName === "voice" && options.model && definition?.models && !definition.models.some((model) => model.toLowerCase() === options.model?.toLowerCase())) {
       addDiagnostic(
         diagnostics,
@@ -2546,12 +2552,30 @@ function urlAttributes(token) {
     return value === void 0 ? [] : [{ attribute, value }];
   });
 }
+function annotateTokenDiagnostics(diagnostics, startIndex, token, options, voiceName) {
+  const attributes = [...token.attributes.keys()];
+  for (const diagnostic of diagnostics.slice(startIndex)) {
+    const attributeName = attributes.find(
+      (attribute) => new RegExp(`(?:<[^> ]+\\s+|")${attribute}(?:"|>|\\s)`, "i").test(diagnostic.message)
+    );
+    const nodePath = options.sourceNodePath ? [...options.sourceNodePath] : [...token.path];
+    Object.assign(diagnostic, {
+      range: { start: token.start, end: token.end + 1 },
+      tagName: token.name,
+      ...attributeName ? { attributeName } : {},
+      ...voiceName ? { voiceName } : {},
+      ...options.chunkIndex !== void 0 ? { chunkIndex: options.chunkIndex } : {},
+      nodePath,
+      targetNodePath: [...token.path]
+    });
+  }
+}
 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, {
+  const boundedValidator = options.urlValidatorRunner ?? createAzureUrlValidatorRunner(validator, {
     ...runnerOptions,
     ...options.urlValidatorConcurrency !== void 0 ? { concurrency: options.urlValidatorConcurrency } : {},
     ...options.urlValidatorTimeoutMs !== void 0 ? { timeoutMs: options.urlValidatorTimeoutMs } : {},
@@ -2576,33 +2600,55 @@ function validateAzureSsml(ssml, options = {}) {
         const valid = typeof result === "boolean" ? result : result.valid;
         if (!valid) {
           const reason = typeof result === "boolean" ? void 0 : result.reason;
+          const diagnosticStart = diagnostics.length;
           addDiagnostic(
             diagnostics,
             ssml,
             token.start,
             `<${token.name} ${attribute}> was rejected by the custom URL validator${reason ? `: ${reason}` : "."}`
           );
+          annotateTokenDiagnostics(diagnostics, diagnosticStart, token, options, token.parentVoiceName);
         }
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
+        const diagnosticStart = diagnostics.length;
         addDiagnostic(
           diagnostics,
           ssml,
           token.start,
           `<${token.name} ${attribute}> could not be validated by the custom URL validator: ${reason}`
         );
+        annotateTokenDiagnostics(diagnostics, diagnosticStart, token, options, token.parentVoiceName);
       }
     })
   );
   return Promise.all(checks).then(() => diagnostics);
 }
+async function validateAzureSsmlChunks(chunks, options = {}) {
+  const validator = options.urlValidator ?? options.customUrlValidator;
+  const sharedOptions = validator ? {
+    ...options,
+    urlValidatorRunner: options.urlValidatorRunner ?? createAzureUrlValidatorRunner(validator, {
+      ...options.urlValidation ?? {},
+      ...options.urlValidatorConcurrency !== void 0 ? { concurrency: options.urlValidatorConcurrency } : {},
+      ...options.urlValidatorTimeoutMs !== void 0 ? { timeoutMs: options.urlValidatorTimeoutMs } : {},
+      ...options.urlValidatorSignal ? { signal: options.urlValidatorSignal } : {},
+      ...options.urlValidatorCache ? { cache: options.urlValidatorCache } : {}
+    })
+  } : options;
+  return Promise.all(
+    chunks.map((chunk, chunkIndex) => Promise.resolve(validateAzureSsml(chunk, { ...sharedOptions, chunkIndex })))
+  );
+}
 
 // packages/ssml-core/src/generated/azureVoiceCatalog.ts
 var AZURE_VOICE_CATALOG_METADATA = {
   apiVersion: "2025-10-01",
   generatedAt: "2026-08-28T00:00:00.000Z",
   regions: [],
-  voiceCount: AZURE_VOICE_DEFINITIONS.length
+  voiceCount: AZURE_VOICE_DEFINITIONS.length,
+  expiresAt: "2026-09-04T00:00:00.000Z",
+  regionDiffs: {}
 };
 
 // packages/ssml-core/src/voiceCatalog.ts
@@ -2631,7 +2677,8 @@ export {
   normalizeAzureLanguage,
   areAzureLanguagesEquivalent,
   validateAzureSsml,
+  validateAzureSsmlChunks,
   getAzureVoiceCatalogMetadata,
   getBuiltInVoiceCatalogMetadata
 };
-//# sourceMappingURL=chunk-FXUM45ZY.mjs.map
+//# sourceMappingURL=chunk-2SYLELUT.mjs.map