@inworld/tts 0.0.0

package/src/client.js

@@ -0,0 +1,929 @@
+/**
+ * HTTP client for generate and stream (aligned with Inworld TTS API).
+ */
+
+import {
+  BITS_PER_SAMPLE,
+  CHANNELS,
+  MAX_CHUNK_SIZE,
+  MIN_CHUNK_SIZE,
+  SAMPLE_RATE,
+  SPLICE_BREAK_SECONDS,
+  MAX_CONCURRENT_REQUESTS,
+  GENERATE_MAX_CHARS,
+  STREAM_MAX_CHARS,
+  CHARS_PER_SECOND,
+  CJK_CHAR_WEIGHT,
+  getTimeoutSignal,
+  debugLog,
+  withRetry,
+} from './config.js';
+import { ApiError, MissingApiKeyError, NetworkError } from './errors.js';
+import { writeFileSafe } from './write-file.js';
+import { playFile, play as playAudio } from './player.js';
+
+// ---------------------------------------------------------------------------
+// Browser-compatible byte utilities
+// (Buffer extends Uint8Array in Node, so returning Uint8Array is backward-compatible)
+// ---------------------------------------------------------------------------
+
+function base64ToBytes(b64) {
+  if (typeof Buffer !== 'undefined') return Buffer.from(b64, 'base64');
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function concatBytes(arrays) {
+  if (typeof Buffer !== 'undefined') return Buffer.concat(arrays);
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) { out.set(a, offset); offset += a.length; }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Effective length estimation (SSML <break> + CJK weight)
+// ---------------------------------------------------------------------------
+
+/**
+ * Count CJK characters (Chinese, Japanese Kanji/Kana, Korean Hangul).
+ * @param {string} text
+ * @returns {number}
+ */
+function _countCjk(text) {
+  return text?.match(/[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g)?.length ?? 0;
+}
+
+/**
+ * Return text length with SSML <break> durations and CJK weight factored in.
+ * Without this, chunks stuffed with <break time="Xs"/> tags look short in chars
+ * but produce huge audio, potentially exceeding API response size limits. CJK
+ * characters also produce ~3x more audio per character than Latin text.
+ * @param {string} text
+ * @param {number} [charsPerSecond]
+ * @returns {number}
+ */
+function estimateEffectiveLength(text, charsPerSecond = CHARS_PER_SECOND) {
+  const breakPattern = /<break\s+time="([\d.]+)(m?s)"\s*\/?>/gi;
+  let totalBreakSeconds = 0;
+  let m;
+  while ((m = breakPattern.exec(text)) !== null) {
+    const val = parseFloat(m[1]);
+    if (!isNaN(val)) totalBreakSeconds += m[2].toLowerCase() === 'ms' ? val / 1000 : val;
+  }
+  const textWithoutBreaks = text.replace(/<break\s[^>]*\/?>/gi, '');
+  const cjkCount = _countCjk(textWithoutBreaks);
+  const rawLength = (textWithoutBreaks.length - cjkCount) + Math.floor(cjkCount * CJK_CHAR_WEIGHT);
+  return rawLength + Math.floor(totalBreakSeconds * charsPerSecond);
+}
+
+// ---------------------------------------------------------------------------
+// Long text chunking (per api-examples)
+// ---------------------------------------------------------------------------
+
+function findBreakPoint(text, minPos, maxPos) {
+  const searchText = text.slice(0, maxPos);
+  let searchStart = minPos;
+  for (;;) {
+    const idx = searchText.indexOf('\n\n', searchStart);
+    if (idx === -1 || idx >= maxPos) break;
+    if (idx >= minPos) return idx + 2;
+    searchStart = idx + 1;
+  }
+  searchStart = minPos;
+  for (;;) {
+    const idx = searchText.indexOf('\n', searchStart);
+    if (idx === -1 || idx >= maxPos) break;
+    if (idx >= minPos) return idx + 1;
+    searchStart = idx + 1;
+  }
+  const sentenceEnd = /[.!?]["']?\s+|[。！？]["']?\s*|[.!?。！？]["']?$/g;
+  let match;
+  while ((match = sentenceEnd.exec(searchText)) !== null) {
+    if (match.index >= minPos) return match.index + match[0].length;
+  }
+  sentenceEnd.lastIndex = 0;
+  let last = -1;
+  while ((match = sentenceEnd.exec(searchText)) !== null) {
+    last = match.index + match[0].length;
+  }
+  if (last > 0) return last;
+  const spaceIdx = searchText.lastIndexOf(' ');
+  return spaceIdx > 0 ? spaceIdx + 1 : maxPos;
+}
+
+function chunkText(text) {
+  const chunks = [];
+  let pos = 0;
+  while (pos < text.length) {
+    const rest = text.slice(pos);
+    if (estimateEffectiveLength(rest) <= MAX_CHUNK_SIZE) {
+      const s = rest.trim();
+      if (s) chunks.push(s);
+      break;
+    }
+    // When <break> tags or CJK inflate effective length, scale down the search window
+    const candidate = rest.slice(0, MAX_CHUNK_SIZE);
+    const effLen = estimateEffectiveLength(candidate);
+    let effectiveMax, effectiveMin;
+    if (effLen > MAX_CHUNK_SIZE) {
+      const scale = MAX_CHUNK_SIZE / effLen;
+      effectiveMax = Math.max(1, Math.floor(candidate.length * scale));
+      effectiveMin = Math.max(1, Math.floor(MIN_CHUNK_SIZE * scale));
+    } else {
+      effectiveMax = MAX_CHUNK_SIZE;
+      effectiveMin = MIN_CHUNK_SIZE;
+    }
+    const end = findBreakPoint(rest, effectiveMin, effectiveMax);
+    const s = rest.slice(0, end).trim();
+    if (s) chunks.push(s);
+    pos += end;
+  }
+  return chunks;
+}
+
+// ---------------------------------------------------------------------------
+// Audio merge for long-text generate
+// ---------------------------------------------------------------------------
+
+function extractRawPcm(audioData) {
+  // Check for RIFF header bytes: R=0x52 I=0x49 F=0x46 F=0x46
+  if (audioData.length > 44 &&
+      audioData[0] === 0x52 && audioData[1] === 0x49 &&
+      audioData[2] === 0x46 && audioData[3] === 0x46) {
+    return audioData.subarray(44);
+  }
+  return audioData;
+}
+
+function createSilence(seconds, sampleRate = SAMPLE_RATE) {
+  const byteRate = sampleRate * (BITS_PER_SAMPLE / 8) * CHANNELS;
+  let n = Math.floor(byteRate * seconds);
+  n -= n % 2;
+  return new Uint8Array(n); // zero-initialized
+}
+
+function mergeLinear16Buffers(buffers, spliceBreak = SPLICE_BREAK_SECONDS, sampleRate = SAMPLE_RATE) {
+  if (buffers.length === 0) return new Uint8Array(0);
+  if (buffers.length === 1) return buffers[0];
+  const silence = spliceBreak > 0 ? createSilence(spliceBreak, sampleRate) : null;
+  const out = [];
+  for (let i = 0; i < buffers.length; i++) {
+    const raw = extractRawPcm(buffers[i]);
+    if (i > 0 && silence) out.push(silence);
+    out.push(raw);
+  }
+  return concatBytes(out);
+}
+
+function wavHeader(dataLen, sampleRate = SAMPLE_RATE) {
+  const byteRate = sampleRate * (BITS_PER_SAMPLE / 8) * CHANNELS;
+  const blockAlign = CHANNELS * (BITS_PER_SAMPLE / 8);
+  const ab = new ArrayBuffer(44);
+  const v = new DataView(ab);
+  // RIFF chunk: "RIFF" + size + "WAVE"
+  v.setUint8(0, 0x52); v.setUint8(1, 0x49); v.setUint8(2, 0x46); v.setUint8(3, 0x46);
+  v.setUint32(4, 36 + dataLen, true);
+  v.setUint8(8, 0x57); v.setUint8(9, 0x41); v.setUint8(10, 0x56); v.setUint8(11, 0x45);
+  // fmt sub-chunk: "fmt " + 16 + PCM + channels + sampleRate + byteRate + blockAlign + bitsPerSample
+  v.setUint8(12, 0x66); v.setUint8(13, 0x6D); v.setUint8(14, 0x74); v.setUint8(15, 0x20);
+  v.setUint32(16, 16, true);
+  v.setUint16(20, 1, true);
+  v.setUint16(22, CHANNELS, true);
+  v.setUint32(24, sampleRate, true);
+  v.setUint32(28, byteRate, true);
+  v.setUint16(32, blockAlign, true);
+  v.setUint16(34, BITS_PER_SAMPLE, true);
+  // data sub-chunk: "data" + size
+  v.setUint8(36, 0x64); v.setUint8(37, 0x61); v.setUint8(38, 0x74); v.setUint8(39, 0x61);
+  v.setUint32(40, dataLen, true);
+  return new Uint8Array(ab);
+}
+
+// ---------------------------------------------------------------------------
+// outputFile extension check
+// ---------------------------------------------------------------------------
+
+const VALID_ENCODINGS = ['MP3', 'OGG_OPUS', 'LINEAR16', 'WAV', 'PCM', 'FLAC', 'ALAW', 'MULAW'];
+
+const ENCODING_EXTENSIONS = {
+  MP3:      ['.mp3'],
+  OGG_OPUS: ['.ogg', '.opus'],
+  LINEAR16: ['.wav'],
+  WAV:      ['.wav'],
+  PCM:      ['.pcm'],
+  FLAC:     ['.flac'],
+  ALAW:     ['.alaw'],
+  MULAW:    ['.mulaw'],
+};
+
+function warnExtensionMismatch(outputFile, encoding) {
+  const ext = outputFile.slice(outputFile.lastIndexOf('.')).toLowerCase();
+  const expected = ENCODING_EXTENSIONS[encoding];
+  if (expected && !expected.includes(ext)) {
+    console.warn(
+      `[inworld-tts] Warning: outputFile "${outputFile}" has extension "${ext}" ` +
+      `but encoding is "${encoding}" (expected ${expected.join(' or ')}). ` +
+      `The file will contain ${encoding} audio data.`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Option parsing and request body
+// ---------------------------------------------------------------------------
+
+const KNOWN_OPTIONS = new Set([
+  'text', 'voice', 'model', 'encoding', 'sampleRate',
+  'bitRate', 'speakingRate', 'temperature', 'timestampType', 'timestampTransportStrategy',
+  'applyTextNormalization', 'outputFile', 'play',
+]);
+
+const RENAMED_OPTIONS = {
+  voiceId: 'voice',
+  modelId: 'model',
+  audioEncoding: 'encoding',
+  sampleRateHertz: 'sampleRate',
+};
+
+function parseOptions(options, defaultModelId) {
+  if (!options || typeof options !== 'object') throw new ApiError('options object is required');
+  for (const key of Object.keys(options)) {
+    if (RENAMED_OPTIONS[key]) {
+      console.warn(`[inworld-tts] Warning: "${key}" has been renamed to "${RENAMED_OPTIONS[key]}". Please update your code.`);
+    } else if (!KNOWN_OPTIONS.has(key)) {
+      console.warn(`[inworld-tts] Warning: unknown option "${key}" will be ignored. Use camelCase keys (e.g. voice, encoding).`);
+    }
+  }
+  return {
+    text: options.text || '',
+    voice: (() => {
+      if (!options.voice) throw new ApiError('options.voice is required');
+      return options.voice;
+    })(),
+    model: options.model || defaultModelId,
+    encoding: (() => {
+      const enc = (options.encoding || 'MP3').toUpperCase();
+      if (!VALID_ENCODINGS.includes(enc)) {
+        throw new ApiError(`encoding "${enc}" is not supported. Valid values: ${VALID_ENCODINGS.join(', ')}`);
+      }
+      return enc;
+    })(),
+    sampleRate: (() => {
+      const enc = (options.encoding || 'MP3').toUpperCase();
+      if ((enc === 'ALAW' || enc === 'MULAW') && options.sampleRate == null) {
+        console.warn(`[inworld-tts] ${enc} only supports sampleRate 8000 — defaulting to 8000.`);
+        return 8000;
+      }
+      return options.sampleRate ?? 48000;
+    })(),
+    bitRate: options.bitRate ?? 128000,
+    speakingRate: options.speakingRate ?? 1.0,
+    temperature: options.temperature ?? 1.0,
+    timestampType: options.timestampType,
+    timestampTransportStrategy: options.timestampTransportStrategy,
+    applyTextNormalization: options.applyTextNormalization === 'none' ? 'APPLY_TEXT_NORMALIZATION_UNSPECIFIED' : options.applyTextNormalization,
+  };
+}
+
+function buildBody(opts, textOverride) {
+  const ac = {
+    audioEncoding: opts.encoding,
+    sampleRateHertz: opts.sampleRate,
+    speakingRate: opts.speakingRate,
+  };
+  if (['MP3', 'OGG_OPUS'].includes(opts.encoding)) ac.bitRate = opts.bitRate;
+  const body = {
+    text: textOverride ?? opts.text,
+    voiceId: opts.voice,
+    modelId: opts.model,
+    audioConfig: ac,
+    temperature: opts.temperature,
+  };
+  if (opts.timestampType) body.timestampType = opts.timestampType;
+  if (opts.timestampTransportStrategy) body.timestampTransportStrategy = opts.timestampTransportStrategy;
+  if (opts.applyTextNormalization) body.applyTextNormalization = opts.applyTextNormalization;
+  return body;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP request helper
+// ---------------------------------------------------------------------------
+
+async function generateOne(url, headers, body, signal, config = {}) {
+  const fetchOpts = { method: 'POST', headers, body: JSON.stringify(body), signal };
+  let response;
+  try {
+    response = await fetch(url, fetchOpts);
+  } catch (e) {
+    // Let AbortError/TimeoutError pass through unwrapped so withRetry sees them
+    // as non-retryable; convert connection failures to NetworkError so withRetry
+    // can retry them.
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') throw e;
+    throw new NetworkError(e.message);
+  }
+  if (!response.ok) {
+    let errMsg = response.statusText;
+    let details = {};
+    try {
+      details = await response.json();
+      errMsg = details.message || JSON.stringify(details);
+    } catch (_) {}
+    throw new ApiError(errMsg, response.status, details);
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch (_) {
+    throw new ApiError('unexpected response: failed to parse JSON');
+  }
+  if (!data.audioContent) {
+    throw new ApiError('unexpected response: missing audioContent');
+  }
+  return { audio: base64ToBytes(data.audioContent), timestampInfo: data.timestampInfo ?? null };
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp helpers (for generateWithTimestamps)
+// ---------------------------------------------------------------------------
+
+function isEmptyTimestampInfo(ts) {
+  if (!ts) return true;
+  if (ts.wordAlignment) {
+    return !ts.wordAlignment.words || ts.wordAlignment.words.length === 0;
+  }
+  if (ts.characterAlignment) {
+    return !ts.characterAlignment.characters || ts.characterAlignment.characters.length === 0;
+  }
+  return true;
+}
+
+function getLastEndTime(ts) {
+  if (!ts) return 0;
+  if (ts.wordAlignment?.wordEndTimeSeconds?.length) {
+    const ends = ts.wordAlignment.wordEndTimeSeconds;
+    return ends[ends.length - 1];
+  }
+  if (ts.characterAlignment?.characterEndTimeSeconds?.length) {
+    const ends = ts.characterAlignment.characterEndTimeSeconds;
+    return ends[ends.length - 1];
+  }
+  return 0;
+}
+
+function extractTrailingBreakSeconds(text) {
+  const m = text.match(/<break\s+time="([\d.]+)(m?s)"\s*\/?>\s*$/i);
+  if (!m) return 0;
+  const val = parseFloat(m[1]);
+  return m[2].toLowerCase() === 'ms' ? val / 1000 : val;
+}
+
+function applyTimestampOffset(ts, offset) {
+  if (!ts || offset === 0) return ts ?? {};
+  const result = {};
+  if (ts.wordAlignment) {
+    result.wordAlignment = {
+      words: ts.wordAlignment.words,
+      wordStartTimeSeconds: ts.wordAlignment.wordStartTimeSeconds?.map(t => t + offset) ?? [],
+      wordEndTimeSeconds: ts.wordAlignment.wordEndTimeSeconds?.map(t => t + offset) ?? [],
+      phoneticDetails: ts.wordAlignment.phoneticDetails?.map(pd => ({
+        ...pd,
+        phones: pd.phones?.map(p => ({ ...p, startTimeSeconds: p.startTimeSeconds + offset })),
+      })) ?? [],
+    };
+  }
+  if (ts.characterAlignment) {
+    result.characterAlignment = {
+      characters: ts.characterAlignment.characters,
+      characterStartTimeSeconds: ts.characterAlignment.characterStartTimeSeconds?.map(t => t + offset) ?? [],
+      characterEndTimeSeconds: ts.characterAlignment.characterEndTimeSeconds?.map(t => t + offset) ?? [],
+    };
+  }
+  return result;
+}
+
+function mergeTimestampInfos(infos) {
+  const result = {};
+  const hasWord = infos.some(ts => ts?.wordAlignment);
+  if (hasWord) {
+    const allWords = [];
+    const allWordStart = [];
+    const allWordEnd = [];
+    const allPhoneticDetails = [];
+    let runningWordCount = 0;
+    for (const ts of infos) {
+      if (!ts?.wordAlignment) continue;
+      const wa = ts.wordAlignment;
+      allWords.push(...(wa.words ?? []));
+      allWordStart.push(...(wa.wordStartTimeSeconds ?? []));
+      allWordEnd.push(...(wa.wordEndTimeSeconds ?? []));
+      for (const pd of wa.phoneticDetails ?? []) {
+        allPhoneticDetails.push({ ...pd, wordIndex: pd.wordIndex + runningWordCount });
+      }
+      runningWordCount += wa.words?.length ?? 0;
+    }
+    result.wordAlignment = {
+      words: allWords,
+      wordStartTimeSeconds: allWordStart,
+      wordEndTimeSeconds: allWordEnd,
+      phoneticDetails: allPhoneticDetails,
+    };
+  }
+  const hasChar = infos.some(ts => ts?.characterAlignment);
+  if (hasChar) {
+    const allChars = [];
+    const allCharStart = [];
+    const allCharEnd = [];
+    for (const ts of infos) {
+      if (!ts?.characterAlignment) continue;
+      const ca = ts.characterAlignment;
+      allChars.push(...(ca.characters ?? []));
+      allCharStart.push(...(ca.characterStartTimeSeconds ?? []));
+      allCharEnd.push(...(ca.characterEndTimeSeconds ?? []));
+    }
+    result.characterAlignment = {
+      characters: allChars,
+      characterStartTimeSeconds: allCharStart,
+      characterEndTimeSeconds: allCharEnd,
+    };
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Generate (handles any text length automatically)
+// ---------------------------------------------------------------------------
+
+export async function generate(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+  const url = `${config._baseUrl}/tts/v1/voice`;
+  const { outputFile, play: shouldPlay, ...rest } = options || {};
+  const opts = parseOptions(rest, 'inworld-tts-1.5-max');
+
+  if (!opts.text) {
+    const received = (options || {}).text;
+    const typeInfo = received === undefined ? 'undefined' : received === null ? 'null' : `${typeof received} (${JSON.stringify(received)})`;
+    throw new ApiError(`options.text is required (received: ${typeInfo})`);
+  }
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? 60_000);
+  const maxConcurrent = config.maxConcurrentRequests ?? MAX_CONCURRENT_REQUESTS;
+  const spliceBreak = SPLICE_BREAK_SECONDS;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: config._authHeader,
+  };
+
+  const generateStart = performance.now();
+  let audio;
+
+  try {
+    if (estimateEffectiveLength(opts.text) <= GENERATE_MAX_CHARS) {
+      let result;
+      try {
+        result = await withRetry(() => generateOne(url, headers, buildBody(opts), signal, config), config);
+      } catch (e) {
+        if (e instanceof ApiError || e instanceof NetworkError) throw e;
+        throw new NetworkError('Request timed out');
+      }
+      audio = result.audio;
+    } else {
+      const chunks = chunkText(opts.text);
+      if (chunks.length === 0) return new Uint8Array(0);
+      debugLog(config, `long text: ${chunks.length} chunks, concurrency=${Math.min(maxConcurrent, chunks.length)}`);
+
+      const results = new Array(chunks.length);
+      const queue = chunks.map((t, i) => ({ text: t, index: i }));
+      const concurrency = Math.min(maxConcurrent, chunks.length);
+
+      const ac = new AbortController();
+      signal.addEventListener('abort', () => ac.abort(signal.reason), { once: true });
+
+      async function worker() {
+        while (queue.length > 0) {
+          if (ac.signal.aborted) return;
+          const { text: t, index: i } = queue.shift();
+          try {
+            results[i] = await withRetry(() => generateOne(url, headers, buildBody(opts, t), ac.signal, config), config);
+          } catch (e) {
+            ac.abort(e);
+            if (e instanceof ApiError || e instanceof NetworkError) throw e;
+            throw new NetworkError('Request timed out');
+          }
+        }
+      }
+
+      await Promise.all(Array.from({ length: concurrency }, () => worker()));
+
+      const listBuffers = results.filter(r => r?.audio instanceof Uint8Array).map(r => r.audio);
+      if (opts.encoding === 'LINEAR16' || opts.encoding === 'WAV') {
+        // 16-bit PCM with WAV container: merge with silence, add WAV header
+        const merged = mergeLinear16Buffers(listBuffers, spliceBreak, opts.sampleRate);
+        audio = concatBytes([wavHeader(merged.length, opts.sampleRate), merged]);
+      } else if (opts.encoding === 'PCM') {
+        // Raw 16-bit PCM, no container: merge with silence, no WAV header
+        audio = mergeLinear16Buffers(listBuffers, spliceBreak, opts.sampleRate);
+      } else {
+        // MP3, OGG_OPUS, FLAC, ALAW, MULAW: concatenate chunks as-is
+        audio = concatBytes(listBuffers);
+      }
+    }
+  } finally {
+    clear();
+  }
+
+  debugLog(config, `generate: ${audio.length.toLocaleString()} bytes (${((performance.now() - generateStart) / 1000).toFixed(2)}s)`);
+  if (outputFile) {
+    warnExtensionMismatch(outputFile, opts.encoding);
+    await writeFileSafe(outputFile, audio);
+  }
+  if (shouldPlay) {
+    if (outputFile) {
+      await playFile(outputFile, opts.encoding);
+    } else {
+      await playAudio(audio, { encoding: opts.encoding });
+    }
+  }
+  return audio;
+}
+
+// ---------------------------------------------------------------------------
+// Generate with timestamps
+// ---------------------------------------------------------------------------
+
+export async function generateWithTimestamps(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+  const url = `${config._baseUrl}/tts/v1/voice`;
+  const { outputFile, play: shouldPlay, timestampType, ...rest } = options || {};
+  if (!timestampType) throw new ApiError('options.timestampType is required ("WORD" or "CHARACTER")');
+  const opts = parseOptions({ ...rest, timestampType }, 'inworld-tts-1.5-max');
+
+  if (!opts.text) {
+    const received = (options || {}).text;
+    const typeInfo = received === undefined ? 'undefined' : received === null ? 'null' : `${typeof received} (${JSON.stringify(received)})`;
+    throw new ApiError(`options.text is required (received: ${typeInfo})`);
+  }
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? 60_000);
+  const maxConcurrent = config.maxConcurrentRequests ?? MAX_CONCURRENT_REQUESTS;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: config._authHeader,
+  };
+
+  const generateStart = performance.now();
+  let audio;
+  let timestamps;
+
+  try {
+    if (estimateEffectiveLength(opts.text) <= GENERATE_MAX_CHARS) {
+      let result;
+      try {
+        result = await withRetry(() => generateOne(url, headers, buildBody(opts), signal, config), config);
+      } catch (e) {
+        if (e instanceof ApiError || e instanceof NetworkError) throw e;
+        throw new NetworkError('Request timed out');
+      }
+      audio = result.audio;
+      timestamps = result.timestampInfo ?? {};
+    } else {
+      const chunks = chunkText(opts.text);
+      if (chunks.length === 0) return { audio: new Uint8Array(0), timestamps: {} };
+      debugLog(config, `generateWithTimestamps: ${chunks.length} chunks, concurrency=${Math.min(maxConcurrent, chunks.length)}`);
+
+      const results = new Array(chunks.length);
+      const queue = chunks.map((t, i) => ({ text: t, index: i }));
+      const concurrency = Math.min(maxConcurrent, chunks.length);
+
+      const ac = new AbortController();
+      signal.addEventListener('abort', () => ac.abort(signal.reason), { once: true });
+
+      async function worker() {
+        while (queue.length > 0) {
+          if (ac.signal.aborted) return;
+          const { text: t, index: i } = queue.shift();
+          try {
+            results[i] = await withRetry(() => generateOne(url, headers, buildBody(opts, t), ac.signal, config), config);
+          } catch (e) {
+            ac.abort(e);
+            if (e instanceof ApiError || e instanceof NetworkError) throw e;
+            throw new NetworkError('Request timed out');
+          }
+        }
+      }
+
+      await Promise.all(Array.from({ length: concurrency }, () => worker()));
+
+      // Sequential pass: compute timestamp offsets and merge
+      const spliceGap = ['LINEAR16', 'WAV', 'PCM'].includes(opts.encoding) ? SPLICE_BREAK_SECONDS : 0;
+      let offset = 0;
+      const adjustedTimestamps = [];
+      const audioBuffers = [];
+
+      for (let i = 0; i < chunks.length; i++) {
+        const { audio: chunkAudio, timestampInfo } = results[i];
+        audioBuffers.push(chunkAudio);
+        adjustedTimestamps.push(applyTimestampOffset(timestampInfo, offset));
+        offset += getLastEndTime(timestampInfo) + extractTrailingBreakSeconds(chunks[i]) + spliceGap;
+      }
+
+      timestamps = mergeTimestampInfos(adjustedTimestamps);
+
+      if (opts.encoding === 'LINEAR16' || opts.encoding === 'WAV') {
+        const merged = mergeLinear16Buffers(audioBuffers, SPLICE_BREAK_SECONDS, opts.sampleRate);
+        audio = concatBytes([wavHeader(merged.length, opts.sampleRate), merged]);
+      } else if (opts.encoding === 'PCM') {
+        audio = mergeLinear16Buffers(audioBuffers, SPLICE_BREAK_SECONDS, opts.sampleRate);
+      } else {
+        audio = concatBytes(audioBuffers);
+      }
+    }
+  } finally {
+    clear();
+  }
+
+  debugLog(config, `generateWithTimestamps: ${audio.length.toLocaleString()} bytes (${((performance.now() - generateStart) / 1000).toFixed(2)}s)`);
+  if (outputFile) {
+    warnExtensionMismatch(outputFile, opts.encoding);
+    await writeFileSafe(outputFile, audio);
+  }
+  if (shouldPlay) {
+    if (outputFile) {
+      await playFile(outputFile, opts.encoding);
+    } else {
+      await playAudio(audio, { encoding: opts.encoding });
+    }
+  }
+  return { audio, timestamps };
+}
+
+// ---------------------------------------------------------------------------
+// Stream (HTTP streaming, async iterable)
+// ---------------------------------------------------------------------------
+
+export async function* stream(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+  const url = `${config._baseUrl}/tts/v1/voice:stream`;
+  const outputFile = options?.outputFile;
+  const shouldPlay = options?.play;
+  if (outputFile && typeof window !== 'undefined') {
+    throw new ApiError('outputFile is not supported in browser environments. Use stream() to collect chunks or generate() to get a Uint8Array.');
+  }
+  const opts = parseOptions(options, 'inworld-tts-1.5-mini');
+
+  if (!opts.text) {
+    const received = (options || {}).text;
+    const typeInfo = received === undefined ? 'undefined' : received === null ? 'null' : `${typeof received} (${JSON.stringify(received)})`;
+    throw new ApiError(`options.text is required (received: ${typeInfo})`);
+  }
+  const effectiveLen = estimateEffectiveLength(opts.text);
+  if (effectiveLen > STREAM_MAX_CHARS) {
+    throw new ApiError(
+      `text exceeds ${STREAM_MAX_CHARS} character limit for stream() (effective length ${effectiveLen}, raw length ${opts.text.length}). Use generate() instead — it handles any text length automatically.`
+    );
+  }
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? 60_000);
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: config._authHeader,
+  };
+
+  const body = buildBody(opts);
+  const fetchOpts = { method: 'POST', headers, body: JSON.stringify(body), signal };
+  const streamStart = performance.now();
+  const collectedChunks = (outputFile || shouldPlay) ? [] : null;
+  try {
+    let res;
+    try {
+      res = await withRetry(async () => {
+        let r;
+        try {
+          r = await fetch(url, fetchOpts);
+        } catch (e) {
+          if (e.name === 'AbortError' || e.name === 'TimeoutError') throw e;
+          throw new NetworkError(e.message);
+        }
+        if (r.status >= 500) {
+          const details = await r.json().catch(() => ({}));
+          throw new ApiError(details.message || r.statusText, r.status, details);
+        }
+        return r;
+      }, config);
+    } catch (e) {
+      if (e instanceof ApiError || e instanceof NetworkError) throw e;
+      throw new NetworkError('Request timed out');
+    }
+    if (!res.ok) {
+      let errMsg = res.statusText;
+      let details = {};
+      try {
+        details = await res.json();
+        errMsg = details.message || JSON.stringify(details);
+      } catch (_) {
+        errMsg = await res.text().catch(() => `HTTP ${res.status}`);
+      }
+      throw new ApiError(errMsg, res.status, details);
+    }
+    const resBody = res.body;
+    if (!resBody) throw new ApiError('empty response body');
+    const reader = resBody.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let chunkCount = 0;
+    let firstChunkMs = null;
+    let totalBytes = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split('\n');
+        buf = lines.pop() || '';
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const data = JSON.parse(line);
+            const result = data.result;
+            if (result && result.audioContent) {
+              const chunk = base64ToBytes(result.audioContent);
+              if (firstChunkMs === null) firstChunkMs = performance.now() - streamStart;
+              chunkCount++;
+              totalBytes += chunk.length;
+              debugLog(config, `stream chunk #${chunkCount} (${chunk.length} bytes)`);
+              if (collectedChunks) collectedChunks.push(chunk);
+              yield chunk;
+            }
+          } catch (_) {}
+        }
+      }
+      if (buf.trim()) {
+        try {
+          const data = JSON.parse(buf);
+          const result = data.result;
+          if (result && result.audioContent) {
+            const chunk = base64ToBytes(result.audioContent);
+            if (firstChunkMs === null) firstChunkMs = performance.now() - streamStart;
+            chunkCount++;
+            totalBytes += chunk.length;
+            debugLog(config, `stream chunk #${chunkCount} (${chunk.length} bytes)`);
+            if (collectedChunks) collectedChunks.push(chunk);
+            yield chunk;
+          }
+        } catch (_) {}
+      }
+      if (chunkCount > 0) {
+        debugLog(config, `stream: first chunk ${Math.round(firstChunkMs)}ms, ${chunkCount} chunks, ${totalBytes.toLocaleString()} bytes total`);
+      }
+    } finally {
+      reader.releaseLock?.();
+    }
+  } finally {
+    clear();
+  }
+
+  if (collectedChunks) {
+    const audio = concatBytes(collectedChunks);
+    const enc = (opts.encoding || 'MP3').toUpperCase();
+    if (outputFile) {
+      warnExtensionMismatch(outputFile, enc);
+      await writeFileSafe(outputFile, audio);
+      if (shouldPlay) await playFile(outputFile, enc);
+    } else {
+      await playAudio(audio, { encoding: enc });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stream with timestamps (hardcodes SYNC strategy)
+// ---------------------------------------------------------------------------
+
+export async function* streamWithTimestamps(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+  const url = `${config._baseUrl}/tts/v1/voice:stream`;
+  const { timestampType, outputFile, play: shouldPlay, ...rest } = options || {};
+  if (!timestampType) throw new ApiError('options.timestampType is required ("WORD" or "CHARACTER")');
+  if (outputFile && typeof window !== 'undefined') {
+    throw new ApiError('outputFile is not supported in browser environments.');
+  }
+  const opts = parseOptions({ ...rest, timestampType }, 'inworld-tts-1.5-mini');
+
+  if (!opts.text) {
+    const received = (options || {}).text;
+    const typeInfo = received === undefined ? 'undefined' : received === null ? 'null' : `${typeof received} (${JSON.stringify(received)})`;
+    throw new ApiError(`options.text is required (received: ${typeInfo})`);
+  }
+  const effectiveLen = estimateEffectiveLength(opts.text);
+  if (effectiveLen > STREAM_MAX_CHARS) {
+    throw new ApiError(
+      `text exceeds ${STREAM_MAX_CHARS} character limit for streamWithTimestamps() (effective length ${effectiveLen}, raw length ${opts.text.length}). Use generateWithTimestamps() instead.`
+    );
+  }
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? 60_000);
+  const headers = { 'Content-Type': 'application/json', Authorization: config._authHeader };
+  const body = buildBody(opts);
+  body.timestampTransportStrategy = 'SYNC';
+  const fetchOpts = { method: 'POST', headers, body: JSON.stringify(body), signal };
+  const streamStart = performance.now();
+  const collectedChunks = (outputFile || shouldPlay) ? [] : null;
+
+  try {
+    let res;
+    try {
+      res = await withRetry(async () => {
+        let r;
+        try {
+          r = await fetch(url, fetchOpts);
+        } catch (e) {
+          if (e.name === 'AbortError' || e.name === 'TimeoutError') throw e;
+          throw new NetworkError(e.message);
+        }
+        if (r.status >= 500) {
+          const details = await r.json().catch(() => ({}));
+          throw new ApiError(details.message || r.statusText, r.status, details);
+        }
+        return r;
+      }, config);
+    } catch (e) {
+      if (e instanceof ApiError || e instanceof NetworkError) throw e;
+      throw new NetworkError('Request timed out');
+    }
+    if (!res.ok) {
+      let errMsg = res.statusText;
+      let details = {};
+      try {
+        details = await res.json();
+        errMsg = details.message || JSON.stringify(details);
+      } catch (_) {
+        errMsg = await res.text().catch(() => `HTTP ${res.status}`);
+      }
+      throw new ApiError(errMsg, res.status, details);
+    }
+    const resBody = res.body;
+    if (!resBody) throw new ApiError('empty response body');
+    const reader = resBody.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let chunkCount = 0;
+    let firstChunkMs = null;
+
+    const processChunk = function* (line) {
+      if (!line.trim()) return;
+      try {
+        const data = JSON.parse(line);
+        const result = data.result;
+        if (result && result.audioContent) {
+          const chunk = base64ToBytes(result.audioContent);
+          if (firstChunkMs === null) firstChunkMs = performance.now() - streamStart;
+          chunkCount++;
+          debugLog(config, `streamWithTimestamps chunk #${chunkCount} (${chunk.length} bytes)`);
+          if (collectedChunks) collectedChunks.push(chunk);
+          const ts = result.timestampInfo;
+          if (isEmptyTimestampInfo(ts)) {
+            yield { audio: chunk };
+          } else {
+            yield { audio: chunk, timestamps: ts };
+          }
+        }
+      } catch (_) {}
+    };
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split('\n');
+        buf = lines.pop() || '';
+        for (const line of lines) yield* processChunk(line);
+      }
+      if (buf.trim()) yield* processChunk(buf);
+      if (chunkCount > 0) {
+        debugLog(config, `streamWithTimestamps: first chunk ${Math.round(firstChunkMs)}ms, ${chunkCount} chunks total`);
+      }
+    } finally {
+      reader.releaseLock?.();
+    }
+  } finally {
+    clear();
+  }
+
+  if (collectedChunks) {
+    const audio = concatBytes(collectedChunks);
+    const enc = (opts.encoding || 'MP3').toUpperCase();
+    if (outputFile) {
+      warnExtensionMismatch(outputFile, enc);
+      await writeFileSafe(outputFile, audio);
+      if (shouldPlay) await playFile(outputFile, enc);
+    } else {
+      await playAudio(audio, { encoding: enc });
+    }
+  }
+}