ssml-builder-js 2.13.0 → 2.14.0

package/dist/index.js

@@ -40,9 +40,13 @@ __export(src_exports, {
   AzureTtsClient: () => AzureTtsClient,
   AzureTtsError: () => AzureTtsError,
   AzureTtsSdkError: () => AzureTtsSdkError,
+  ChunkValidationError: () => ChunkValidationError,
+  UnsupportedMergeFormatError: () => UnsupportedMergeFormatError,
   areAzureLanguagesEquivalent: () => areAzureLanguagesEquivalent,
   buildPartialSsml: () => buildPartialSsml,
   buildSsml: () => buildSsml,
+  canMergeAudioFormat: () => canMergeAudioFormat,
+  createAzureUrlValidatorRunner: () => createAzureUrlValidatorRunner,
   extractSsmlText: () => extractSsmlText,
   extractSsmlTranslatableText: () => extractSsmlTranslatableText,
   fetchAzureVoiceCatalog: () => fetchAzureVoiceCatalog,
@@ -51,13 +55,16 @@ __export(src_exports, {
   getBuiltInVoiceCatalogMetadata: () => getBuiltInVoiceCatalogMetadata,
   isValidAzureAudioDuration: () => isValidAzureAudioDuration,
   mapSsmlTextNodes: () => mapSsmlTextNodes,
+  mergeAudioBuffers: () => mergeAudioBuffers,
   mergeSynthesisResults: () => mergeSynthesisResults,
   normalizeAzureLanguage: () => normalizeAzureLanguage,
   parseSsml: () => parseSsml,
+  resolveMergeAudioFormat: () => resolveMergeAudioFormat,
   splitSsmlDocument: () => splitSsmlDocument,
   synthesizeSpeech: () => synthesizeSpeech,
   synthesizeSsml: () => synthesizeSsml,
   synthesizeSsmlChunks: () => synthesizeSsmlChunks,
+  synthesizeSsmlChunksSafe: () => synthesizeSsmlChunksSafe,
   synthesizeSsmlSafe: () => synthesizeSsmlSafe,
   validateAzureSsml: () => validateAzureSsml,
   validateSsml: () => validateSsml,
@@ -1095,6 +1102,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("");
@@ -1110,7 +1145,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 = {}) {
@@ -1336,7 +1372,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":
@@ -1489,7 +1525,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)]);
     });
@@ -1535,7 +1571,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("");
@@ -1549,7 +1585,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);
     });
   };
@@ -1747,6 +1783,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",
@@ -2041,23 +2140,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);
@@ -2069,13 +2168,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) {
@@ -2393,6 +2492,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);
@@ -2402,7 +2509,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;
@@ -2463,6 +2570,13 @@ var AzureTtsSdkError = class extends AzureTtsError {
     this.errorDetails = errorDetails;
   }
 };
+var UnsupportedMergeFormatError = class extends Error {
+  constructor(format) {
+    super(`Audio format "${format}" cannot be safely concatenated; container re-multiplexing is required.`);
+    this.name = "UnsupportedMergeFormatError";
+    this.format = format;
+  }
+};
 function createSpeechSdkError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new AzureTtsSdkError(message);
@@ -2540,6 +2654,149 @@ function createSpeechConfig(config) {
 }
 
 // packages/azure-tts-client/src/synthesis.ts
+function ascii(bytes, offset, value) {
+  return [...value].every((character, index) => bytes[offset + index] === character.charCodeAt(0));
+}
+function readUint32(bytes, offset) {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(offset, true);
+}
+function parseWav(buffer) {
+  const bytes = new Uint8Array(buffer);
+  if (bytes.byteLength < 12 || !ascii(bytes, 0, "RIFF") || !ascii(bytes, 8, "WAVE")) {
+    throw new Error("Invalid WAV/RIFF audio buffer.");
+  }
+  const chunks = [];
+  const dataParts = [];
+  let format;
+  let offset = 12;
+  while (offset < bytes.byteLength) {
+    if (offset + 8 > bytes.byteLength) throw new Error("Invalid WAV chunk header.");
+    const id = String.fromCharCode(...bytes.slice(offset, offset + 4));
+    const size = readUint32(bytes, offset + 4);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + size;
+    if (dataEnd > bytes.byteLength) throw new Error(`WAV chunk "${id}" exceeds the audio buffer.`);
+    const data2 = bytes.slice(dataStart, dataEnd);
+    chunks.push({ id, data: data2 });
+    if (id === "fmt ") format ?? (format = data2);
+    if (id === "data") dataParts.push(data2);
+    offset = dataEnd + (size & 1);
+    if (offset > bytes.byteLength) throw new Error("Invalid WAV chunk padding.");
+  }
+  if (!format || dataParts.length === 0) throw new Error("WAV audio must contain fmt and data chunks.");
+  const dataLength = dataParts.reduce((total, part) => total + part.byteLength, 0);
+  const data = new Uint8Array(dataLength);
+  let dataOffset = 0;
+  for (const part of dataParts) {
+    data.set(part, dataOffset);
+    dataOffset += part.byteLength;
+  }
+  return { chunks, data, format };
+}
+function writeUint32(target, offset, value) {
+  new DataView(target.buffer).setUint32(offset, value, true);
+}
+function writeChunk(target, offset, id, data) {
+  for (let index = 0; index < 4; index += 1) target[offset + index] = id.charCodeAt(index) ?? 0;
+  writeUint32(target, offset + 4, data.byteLength);
+  target.set(data, offset + 8);
+  const end = offset + 8 + data.byteLength;
+  if (data.byteLength & 1) target[end] = 0;
+  return end + (data.byteLength & 1);
+}
+function mergeWavBuffers(buffers) {
+  if (buffers.length === 0) return new ArrayBuffer(0);
+  const parsed = buffers.map(parseWav);
+  const first = parsed[0];
+  if (!first) throw new Error("At least one WAV buffer is required.");
+  if (parsed.some(
+    (item) => item.format.length !== first.format.length || item.format.some((value, i) => value !== first.format[i])
+  ))
+    throw new Error("WAV buffers have incompatible fmt chunks.");
+  const dataLength = parsed.reduce((total, item) => total + item.data.byteLength, 0);
+  const nonDataLength = first.chunks.reduce(
+    (total, chunk) => chunk.id === "data" ? total : total + 8 + chunk.data.byteLength + (chunk.data.byteLength & 1),
+    0
+  );
+  const outputLength = 12 + nonDataLength + 8 + dataLength + (dataLength & 1);
+  if (outputLength - 8 > 4294967295) throw new RangeError("Merged WAV exceeds the RIFF format size limit.");
+  const output = new Uint8Array(outputLength);
+  output.set(Uint8Array.from([82, 73, 70, 70]), 0);
+  writeUint32(output, 4, outputLength - 8);
+  output.set(Uint8Array.from([87, 65, 86, 69]), 8);
+  let outputOffset = 12;
+  let dataWritten = false;
+  for (const chunk of first.chunks) {
+    if (chunk.id === "data") {
+      if (dataWritten) continue;
+      const data = new Uint8Array(dataLength);
+      let dataOffset = 0;
+      for (const item of parsed) {
+        data.set(item.data, dataOffset);
+        dataOffset += item.data.byteLength;
+      }
+      outputOffset = writeChunk(output, outputOffset, "data", data);
+      dataWritten = true;
+    } else {
+      outputOffset = writeChunk(output, outputOffset, chunk.id, chunk.data);
+    }
+  }
+  if (!dataWritten) throw new Error("WAV audio must contain a data chunk.");
+  return output.buffer;
+}
+function skipId3v2(bytes) {
+  if (!ascii(bytes, 0, "ID3") || bytes.byteLength < 10) return 0;
+  const size = [bytes[6], bytes[7], bytes[8], bytes[9]].reduce((total, value) => total << 7 | value & 127, 0);
+  const hasFooter = (bytes[5] & 16) !== 0;
+  return Math.min(bytes.byteLength, 10 + size + (hasFooter ? 10 : 0));
+}
+function stripMp3Tags(buffer) {
+  const bytes = new Uint8Array(buffer);
+  const start = skipId3v2(bytes);
+  const end = bytes.byteLength >= 128 && ascii(bytes, bytes.byteLength - 128, "TAG") ? bytes.byteLength - 128 : bytes.byteLength;
+  return bytes.slice(Math.min(start, end), end);
+}
+function isMp3Format(format) {
+  return /(?:mp3|mpeg)/i.test(format);
+}
+function isWavFormat(format) {
+  return /(?:wav|wave|riff)/i.test(format);
+}
+function isRawFormat(format) {
+  return /^raw(?:-|$)/i.test(format);
+}
+function resolveMergeAudioFormat(format) {
+  if (isWavFormat(format)) return "wav";
+  if (isMp3Format(format)) return "mp3";
+  if (isRawFormat(format)) return "raw";
+  return void 0;
+}
+function canMergeAudioFormat(format) {
+  return resolveMergeAudioFormat(format) !== void 0;
+}
+function mergeAudioBuffers(buffers, format) {
+  if (isWavFormat(format)) return mergeWavBuffers(buffers);
+  if (isMp3Format(format)) {
+    const parts = buffers.map(stripMp3Tags);
+    const output = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+    let offset = 0;
+    for (const part of parts) {
+      output.set(part, offset);
+      offset += part.byteLength;
+    }
+    return output.buffer;
+  }
+  if (isRawFormat(format)) {
+    const output = new Uint8Array(buffers.reduce((total, buffer) => total + buffer.byteLength, 0));
+    let offset = 0;
+    for (const buffer of buffers) {
+      output.set(new Uint8Array(buffer), offset);
+      offset += buffer.byteLength;
+    }
+    return output.buffer;
+  }
+  throw new UnsupportedMergeFormatError(format);
+}
 function closeSpeechResources(speechConfig, synthesizer) {
   try {
     synthesizer.close();
@@ -2616,6 +2873,9 @@ async function synthesizeSsml(ssml, config) {
       const addSourceMetadata = (event) => ({
         ...event,
         ...config.sourceTextRange ? { textRange: { ...config.sourceTextRange } } : {},
+        ...config.sourceTextRange ? { originalTextRange: { ...config.sourceTextRange } } : {},
+        ...config.chunkIndex !== void 0 ? { chunkIndex: config.chunkIndex } : {},
+        ...config.sourceNodePath ? { sourceNodePath: [...config.sourceNodePath] } : {},
         ...requestId ? { requestId } : {}
       });
       const sourceBoundaries = boundaries.map((boundary) => addSourceMetadata(boundary));
@@ -2651,60 +2911,126 @@ async function synthesizeSsml(ssml, config) {
 async function synthesizeSsmlChunks(chunks, config) {
   const results = [];
   const totalChunks = chunks.length;
+  const report = (event) => config.onProgress?.(event);
   for (const [index, chunk] of chunks.entries()) {
     const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
-    const result = await synthesizeSsml(input.ssml, {
-      ...config,
-      ...input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {},
-      onProgress: void 0
+    report({
+      currentChunk: index,
+      totalChunks,
+      percent: totalChunks === 0 ? 100 : Math.round(index / totalChunks * 100),
+      chunkIndex: index,
+      originalTextRange: input.originalTextRange,
+      status: "pending",
+      durationMs: 0
     });
-    results.push(result);
-    config.onProgress?.({
-      currentChunk: index + 1,
+  }
+  for (const [index, chunk] of chunks.entries()) {
+    const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
+    report({
+      currentChunk: index,
       totalChunks,
-      percent: totalChunks === 0 ? 100 : Math.round((index + 1) / totalChunks * 100)
+      percent: totalChunks === 0 ? 100 : Math.round(index / totalChunks * 100),
+      chunkIndex: index,
+      originalTextRange: input.originalTextRange,
+      status: "synthesizing",
+      durationMs: 0
     });
+    const startedAt = Date.now();
+    try {
+      const result = await synthesizeSsml(input.ssml, {
+        ...config,
+        ...input.originalTextRange ? { sourceTextRange: input.originalTextRange } : {},
+        ...input.sourceNodePath ? { sourceNodePath: input.sourceNodePath } : {},
+        chunkIndex: index,
+        onProgress: void 0
+      });
+      results.push(result);
+      report({
+        currentChunk: index + 1,
+        totalChunks,
+        percent: totalChunks === 0 ? 100 : Math.round((index + 1) / totalChunks * 100),
+        chunkIndex: index,
+        originalTextRange: input.originalTextRange,
+        status: "success",
+        durationMs: Date.now() - startedAt
+      });
+    } catch (error) {
+      report({
+        currentChunk: index,
+        totalChunks,
+        percent: totalChunks === 0 ? 100 : Math.round(index / totalChunks * 100),
+        chunkIndex: index,
+        originalTextRange: input.originalTextRange,
+        status: "failed",
+        durationMs: Date.now() - startedAt,
+        error
+      });
+      throw error;
+    }
   }
-  return mergeSynthesisResults(results);
+  return mergeSynthesisResults(results, config.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3");
 }
-function mergeSynthesisResults(results) {
-  const audioLength = results.reduce((total, result) => total + result.audioData.byteLength, 0);
-  const audioData = new Uint8Array(audioLength);
+function mergeSynthesisResults(results, format) {
+  const audioData = format ? new Uint8Array(
+    mergeAudioBuffers(
+      results.map((result) => result.audioData),
+      format
+    )
+  ) : new Uint8Array(results.reduce((total, result) => total + result.audioData.byteLength, 0));
+  if (!format) {
+    let offset = 0;
+    for (const result of results) {
+      audioData.set(new Uint8Array(result.audioData), offset);
+      offset += result.audioData.byteLength;
+    }
+  }
   const boundaries = [];
   const visemes = [];
   const bookmarks = [];
-  let byteOffset = 0;
   let durationOffset = 0;
   for (const result of results) {
-    audioData.set(new Uint8Array(result.audioData), byteOffset);
-    byteOffset += result.audioData.byteLength;
     const chunkBoundaries = result.boundaries && result.boundaries.length > 0 ? result.boundaries : result.wordBoundary ?? result.wordBoundaries ?? [];
     for (const boundary of chunkBoundaries) {
       const textRange = boundary.textRange ?? result.textRange;
+      const originalTextRange = boundary.originalTextRange ?? textRange;
       const requestId = boundary.requestId ?? result.requestId;
       boundaries.push({
         ...boundary,
         audioOffsetMs: boundary.audioOffsetMs + durationOffset,
+        chunkAudioOffsetMs: boundary.chunkAudioOffsetMs ?? boundary.audioOffsetMs,
+        ...boundary.chunkIndex === void 0 ? { chunkIndex: results.indexOf(result) } : {},
+        ...boundary.sourceNodePath ? { sourceNodePath: [...boundary.sourceNodePath] } : {},
+        ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
         ...requestId ? { requestId } : {}
       });
     }
     for (const viseme of result.visemes ?? []) {
       const textRange = viseme.textRange ?? result.textRange;
+      const originalTextRange = viseme.originalTextRange ?? textRange;
       const requestId = viseme.requestId ?? result.requestId;
       visemes.push({
         ...viseme,
         audioOffsetMs: viseme.audioOffsetMs + durationOffset,
+        chunkAudioOffsetMs: viseme.chunkAudioOffsetMs ?? viseme.audioOffsetMs,
+        ...viseme.chunkIndex === void 0 ? { chunkIndex: results.indexOf(result) } : {},
+        ...viseme.sourceNodePath ? { sourceNodePath: [...viseme.sourceNodePath] } : {},
+        ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
         ...requestId ? { requestId } : {}
       });
     }
     for (const bookmark of result.bookmarks ?? []) {
       const textRange = bookmark.textRange ?? result.textRange;
+      const originalTextRange = bookmark.originalTextRange ?? textRange;
       const requestId = bookmark.requestId ?? result.requestId;
       bookmarks.push({
         ...bookmark,
         audioOffsetMs: bookmark.audioOffsetMs + durationOffset,
+        chunkAudioOffsetMs: bookmark.chunkAudioOffsetMs ?? bookmark.audioOffsetMs,
+        ...bookmark.chunkIndex === void 0 ? { chunkIndex: results.indexOf(result) } : {},
+        ...bookmark.sourceNodePath ? { sourceNodePath: [...bookmark.sourceNodePath] } : {},
+        ...originalTextRange ? { originalTextRange: { ...originalTextRange } } : {},
         ...textRange ? { textRange: { ...textRange } } : {},
         ...requestId ? { requestId } : {}
       });
@@ -3496,6 +3822,69 @@ var AZURE_VOICE_DEFINITIONS2 = [
   },
   { name: "zh-TW-HsiaoChenNeural", locale: "zh-TW" }
 ];
+function createAzureUrlValidatorRunner2(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_STRENGTHS2 = /* @__PURE__ */ new Set(["none", "x-weak", "weak", "medium", "strong", "x-strong"]);
 var ALLOWED_SAY_AS2 = /* @__PURE__ */ new Set([
   "characters",
@@ -3780,23 +4169,23 @@ function validateVoiceFeatureMatrix2(token, source, diagnostics, voiceName, defi
     );
   }
 }
-function validateAudioSource2(token, source, diagnostics, options, elementName2) {
+function validateAudioSource2(token, source, diagnostics, options, elementName3) {
   const src = attr2(token, "src");
   if (!src) {
-    addDiagnostic2(diagnostics, source, token.start, `<${elementName2}> requires a "src" attribute.`);
+    addDiagnostic2(diagnostics, source, token.start, `<${elementName3}> requires a "src" attribute.`);
     return;
   }
   let parsed;
   try {
     parsed = new URL(src);
   } catch {
-    addDiagnostic2(diagnostics, source, token.start, `<${elementName2} src> must be an absolute HTTP(S) URL.`);
+    addDiagnostic2(diagnostics, source, token.start, `<${elementName3} src> must be an absolute HTTP(S) URL.`);
     return;
   }
   if (parsed.username || parsed.password)
-    addDiagnostic2(diagnostics, source, token.start, `<${elementName2} src> must not contain URL credentials.`);
+    addDiagnostic2(diagnostics, source, token.start, `<${elementName3} src> must not contain URL credentials.`);
   if (parsed.protocol !== "https:" && !(options.allowHttpAudio && parsed.protocol === "http:"))
-    addDiagnostic2(diagnostics, source, token.start, `<${elementName2} src> must use HTTPS.`);
+    addDiagnostic2(diagnostics, source, token.start, `<${elementName3} src> must use HTTPS.`);
   const isAllowedOrigin = options.allowedAudioOrigins?.some((allowedOrigin) => {
     try {
       const configured = new URL(allowedOrigin);
@@ -3808,13 +4197,13 @@ function validateAudioSource2(token, source, diagnostics, options, elementName2)
     }
   }) ?? false;
   if (options.allowedAudioOrigins && !isAllowedOrigin)
-    addDiagnostic2(diagnostics, source, token.start, `<${elementName2} src> origin "${parsed.origin}" is not allowed.`);
+    addDiagnostic2(diagnostics, source, token.start, `<${elementName3} src> origin "${parsed.origin}" is not allowed.`);
   else if (!isAllowedOrigin && !options.allowExternalAudio)
     addDiagnostic2(
       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 validateElement2(token, source, diagnostics, voiceName, options, voiceCatalog) {
@@ -4132,6 +4521,14 @@ function validateAzureSsml2(ssml, options = {}) {
   const diagnostics = validateAzureSsmlStatic2(ssml, options);
   const validator = options.urlValidator ?? options.customUrlValidator;
   if (!validator || typeof ssml !== "string") return diagnostics;
+  const runnerOptions = options.urlValidation ?? {};
+  const boundedValidator = createAzureUrlValidatorRunner2(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 = tokenizeElements2(ssml);
@@ -4141,7 +4538,7 @@ function validateAzureSsml2(ssml, options = {}) {
   const checks = tokens.flatMap(
     (token) => urlAttributes2(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;
@@ -4173,6 +4570,15 @@ var AZURE_VOICE_CATALOG_METADATA2 = {
 };
 
 // packages/azure-tts-client/src/safe.ts
+var ChunkValidationError = class extends Error {
+  constructor(chunkIndex, diagnostics) {
+    super(`SSML validation failed for chunk ${chunkIndex}; the Azure Speech API was not called.`);
+    this.kind = "chunk-validation";
+    this.name = "ChunkValidationError";
+    this.chunkIndex = chunkIndex;
+    this.diagnostics = diagnostics;
+  }
+};
 async function synthesizeSsmlSafe(client, ssml, options = {}) {
   const validationOptions = options.validation ?? options;
   const diagnostics = await Promise.resolve(validateAzureSsml2(ssml, validationOptions));
@@ -4196,6 +4602,95 @@ async function synthesizeSsmlSafe(client, ssml, options = {}) {
     return { ok: false, success: false, status: "azure-api-error", error: azureError };
   }
 }
+async function synthesizeSsmlChunksSafe(client, chunks, options = {}) {
+  const validationOptions = options.validation ?? options;
+  const pending = (index, status, error) => {
+    options.onProgress?.({
+      currentChunk: status === "success" ? index + 1 : index,
+      totalChunks: chunks.length,
+      percent: chunks.length === 0 ? 100 : Math.round((status === "success" ? index + 1 : index) / chunks.length * 100),
+      chunkIndex: index,
+      originalTextRange: typeof chunks[index] === "string" ? void 0 : chunks[index]?.originalTextRange,
+      status,
+      durationMs: 0,
+      ...error ? { error } : {}
+    });
+  };
+  chunks.forEach((_chunk, index) => {
+    pending(index, "pending");
+  });
+  const validations = await Promise.all(
+    chunks.map(async (chunk) => {
+      const ssml = typeof chunk === "string" ? chunk : chunk.ssml;
+      const diagnostics = await Promise.resolve(validateAzureSsml2(ssml, validationOptions));
+      return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    })
+  );
+  const firstInvalidIndex = validations.findIndex((diagnostics) => diagnostics.length > 0);
+  if (firstInvalidIndex >= 0) {
+    const error = new ChunkValidationError(firstInvalidIndex, validations[firstInvalidIndex] ?? []);
+    pending(firstInvalidIndex, "failed", error);
+    return { ok: false, success: false, status: "validation-error", error };
+  }
+  try {
+    if (client.synthesizeChunks) {
+      const value = await client.synthesizeChunks(chunks, { onProgress: options.onProgress });
+      return { ok: true, success: true, status: "success", value };
+    }
+    const results = [];
+    for (const [index, chunk] of chunks.entries()) {
+      const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
+      const sourceNodePath = input.sourceNodePath;
+      pending(index, "synthesizing");
+      const startedAt = Date.now();
+      try {
+        const result = await client.synthesizeSsml(input.ssml);
+        results.push({
+          ...result,
+          ...input.originalTextRange ? { textRange: { ...input.originalTextRange } } : {},
+          ...sourceNodePath ? {
+            boundaries: result.boundaries?.map((event) => ({
+              ...event,
+              sourceNodePath: [...sourceNodePath]
+            })),
+            visemes: result.visemes?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] })),
+            bookmarks: result.bookmarks?.map((event) => ({ ...event, sourceNodePath: [...sourceNodePath] }))
+          } : {}
+        });
+        options.onProgress?.({
+          currentChunk: index + 1,
+          totalChunks: chunks.length,
+          percent: chunks.length === 0 ? 100 : Math.round((index + 1) / chunks.length * 100),
+          chunkIndex: index,
+          originalTextRange: input.originalTextRange,
+          status: "success",
+          durationMs: Date.now() - startedAt
+        });
+      } catch (error) {
+        options.onProgress?.({
+          currentChunk: index,
+          totalChunks: chunks.length,
+          percent: chunks.length === 0 ? 100 : Math.round(index / chunks.length * 100),
+          chunkIndex: index,
+          originalTextRange: input.originalTextRange,
+          status: "failed",
+          durationMs: Date.now() - startedAt,
+          error
+        });
+        throw error;
+      }
+    }
+    return {
+      ok: true,
+      success: true,
+      status: "success",
+      value: mergeSynthesisResults(results, options.outputFormat)
+    };
+  } catch (error) {
+    const azureError = error instanceof AzureTtsError ? error : createSpeechSdkError(error);
+    return { ok: false, success: false, status: "azure-api-error", error: azureError };
+  }
+}
 
 // packages/azure-tts-client/src/client.ts
 var ENDPOINT_TEMPLATE = "https://{region}.tts.speech.microsoft.com/cognitiveservices/v1";
@@ -4234,6 +4729,16 @@ var AzureTtsClient = class {
   async synthesizeSsmlSafe(ssml, options = {}) {
     return synthesizeSsmlSafe(this, ssml, options);
   }
+  async synthesizeChunksSafe(chunks, options = {}) {
+    return synthesizeSsmlChunksSafe(this, chunks, {
+      ...options,
+      outputFormat: options.outputFormat ?? __privateGet(this, _options).outputFormat,
+      onProgress: options.onProgress ?? __privateGet(this, _options).onProgress
+    });
+  }
+  async synthesizeSsmlChunksSafe(chunks, options = {}) {
+    return this.synthesizeChunksSafe(chunks, options);
+  }
 };
 _options = new WeakMap();
 
@@ -4289,6 +4794,9 @@ async function fetchAzureVoiceCatalog(options) {
       const secondaryLocales = stringList(record.SecondaryLocaleList);
       const styles = stringList(record.StyleList);
       const status = normalizeStatus(record.Status);
+      const supportedTags = stringList(record.SupportedTags);
+      const unsupportedTags = stringList(record.UnsupportedTags);
+      const models = stringList(record.Models);
       const merged = {
         name: existing?.name ?? name,
         locale: existing?.locale ?? locale,
@@ -4298,6 +4806,12 @@ async function fetchAzureVoiceCatalog(options) {
       if (mergedSecondaryLocales.length > 0) merged.secondaryLocales = mergedSecondaryLocales;
       const mergedStyles = [.../* @__PURE__ */ new Set([...existing?.styles ?? [], ...styles])];
       if (mergedStyles.length > 0) merged.styles = mergedStyles;
+      const mergedSupportedTags = [.../* @__PURE__ */ new Set([...existing?.supportedTags ?? [], ...supportedTags])];
+      if (mergedSupportedTags.length > 0) merged.supportedTags = mergedSupportedTags;
+      const mergedUnsupportedTags = [.../* @__PURE__ */ new Set([...existing?.unsupportedTags ?? [], ...unsupportedTags])];
+      if (mergedUnsupportedTags.length > 0) merged.unsupportedTags = mergedUnsupportedTags;
+      const mergedModels = [.../* @__PURE__ */ new Set([...existing?.models ?? [], ...models])];
+      if (mergedModels.length > 0) merged.models = mergedModels;
       if (status) merged.status = status;
       else if (existing?.status) merged.status = existing.status;
       voices.set(key, merged);
@@ -4319,9 +4833,13 @@ async function fetchAzureVoiceCatalog(options) {
   AzureTtsClient,
   AzureTtsError,
   AzureTtsSdkError,
+  ChunkValidationError,
+  UnsupportedMergeFormatError,
   areAzureLanguagesEquivalent,
   buildPartialSsml,
   buildSsml,
+  canMergeAudioFormat,
+  createAzureUrlValidatorRunner,
   extractSsmlText,
   extractSsmlTranslatableText,
   fetchAzureVoiceCatalog,
@@ -4330,13 +4848,16 @@ async function fetchAzureVoiceCatalog(options) {
   getBuiltInVoiceCatalogMetadata,
   isValidAzureAudioDuration,
   mapSsmlTextNodes,
+  mergeAudioBuffers,
   mergeSynthesisResults,
   normalizeAzureLanguage,
   parseSsml,
+  resolveMergeAudioFormat,
   splitSsmlDocument,
   synthesizeSpeech,
   synthesizeSsml,
   synthesizeSsmlChunks,
+  synthesizeSsmlChunksSafe,
   synthesizeSsmlSafe,
   validateAzureSsml,
   validateSsml,