@inworld/tts 0.0.0

package/src/player.browser.js

@@ -0,0 +1,53 @@
+/**
+ * Browser player — bundlers substitute this for player.js in browser builds.
+ * Uses <audio> element for playback. Must be called inside a user gesture.
+ */
+
+import { ApiError } from './errors.js';
+import { detectEncoding } from './encoding.js';
+
+export { detectEncoding };
+
+const MIME = {
+  MP3: 'audio/mpeg',
+  WAV: 'audio/wav',
+  OGG_OPUS: 'audio/ogg; codecs=opus',
+  FLAC: 'audio/flac',
+};
+
+const UNSUPPORTED_IN_BROWSER = new Set(['LINEAR16', 'PCM', 'ALAW', 'MULAW']);
+
+export function findPlayer(_encoding) {
+  return null;
+}
+
+export async function playFile(_filePath, _encoding) {
+  throw new ApiError('Audio playback from file is not supported in browser environments.');
+}
+
+export async function play(audio, options = {}) {
+  if (typeof audio === 'string') {
+    throw new ApiError('File paths are not supported in browser. Pass a Uint8Array instead.');
+  }
+  const encoding = options.encoding ? options.encoding.toUpperCase() : detectEncoding(audio);
+  if (UNSUPPORTED_IN_BROWSER.has(encoding)) {
+    throw new ApiError(`${encoding} cannot be played in browser. Use AudioContext or request MP3/WAV instead.`);
+  }
+  const blob = new Blob([audio], { type: MIME[encoding] || 'audio/mpeg' });
+  const url = URL.createObjectURL(blob);
+  const el = new Audio(url);
+  try {
+    await el.play();
+    await new Promise((res, rej) => {
+      el.onended = res;
+      el.onerror = () => rej(new ApiError('Audio playback failed. The format may be unsupported by this browser.'));
+    });
+  } catch (e) {
+    if (e.name === 'NotAllowedError') {
+      throw new ApiError('play() was blocked by the browser. Call play() inside a user event handler (e.g. button click).');
+    }
+    throw e;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}

package/src/player.js

@@ -0,0 +1,143 @@
+/**
+ * Audio playback utilities. Node.js only — bundlers substitute player.browser.js.
+ */
+
+import { existsSync } from 'fs';
+import { writeFile, unlink } from 'fs/promises';
+import { spawn } from 'child_process';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { detectEncoding } from './encoding.js';
+
+export { detectEncoding };
+
+// ---------------------------------------------------------------------------
+// 3b. Find installed audio player
+// ---------------------------------------------------------------------------
+
+const EXT_MAP = {
+  MP3: '.mp3', OGG_OPUS: '.ogg', LINEAR16: '.wav', WAV: '.wav',
+  PCM: '.pcm', FLAC: '.flac', ALAW: '.wav', MULAW: '.wav',
+};
+
+function scanPath(binary) {
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const pathDirs = (process.env.PATH || '').split(sep);
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const full = join(dir, binary);
+    if (existsSync(full)) return full;
+    if (process.platform === 'win32' && existsSync(full + '.exe')) return full + '.exe';
+  }
+  return null;
+}
+
+const FFPLAY_ARGS = ['-nodisp', '-autoexit', '-loglevel', 'quiet'];
+
+/**
+ * Find the best available audio player for the given encoding.
+ * Returns null (with a stderr warning) if no suitable player is found.
+ * @param {string} encoding
+ * @returns {{ binary: string, args: string[] } | null}
+ */
+export function findPlayer(encoding) {
+  if (encoding === 'PCM') {
+    process.stderr.write('[inworld-tts] PCM audio cannot be played directly. Use encoding: \'WAV\' instead.\n');
+    return null;
+  }
+
+  const platform = process.platform;
+  const ffplay = scanPath('ffplay');
+  if (ffplay) return { binary: ffplay, args: FFPLAY_ARGS };
+
+  if (platform === 'darwin') {
+    const afplayEncodings = ['MP3', 'WAV', 'FLAC', 'ALAW', 'MULAW'];
+    if (afplayEncodings.includes(encoding)) {
+      const afplay = scanPath('afplay');
+      if (afplay) return { binary: afplay, args: [] };
+    }
+  }
+
+  if (platform === 'linux') {
+    if (encoding === 'MP3') {
+      const mpg123 = scanPath('mpg123');
+      if (mpg123) return { binary: mpg123, args: ['-q'] };
+    }
+    if (encoding === 'OGG_OPUS') {
+      const ogg123 = scanPath('ogg123');
+      if (ogg123) return { binary: ogg123, args: [] };
+    }
+    if (encoding === 'WAV' || encoding === 'LINEAR16') {
+      const aplay = scanPath('aplay');
+      if (aplay) return { binary: aplay, args: ['-q'] };
+    }
+  }
+
+  if (platform === 'win32') {
+    return { binary: 'cmd', args: ['/c', 'start', '/wait', ''] };
+  }
+
+  const hint = platform === 'darwin'
+    ? 'Install ffmpeg (brew install ffmpeg) or use afplay (built-in for MP3/WAV/FLAC).'
+    : platform === 'linux'
+    ? 'Install ffmpeg (apt install ffmpeg) or mpg123/ogg123/aplay for specific formats.'
+    : 'Install ffmpeg to enable audio playback.';
+  process.stderr.write(`[inworld-tts] No audio player found for encoding "${encoding}". ${hint}\n`);
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: play a file at the given path
+// ---------------------------------------------------------------------------
+
+/**
+ * Play an audio file using the best available player.
+ * Prints a warning and returns (does not throw) if no player is found.
+ * @param {string} filePath
+ * @param {string} encoding
+ * @returns {Promise<void>}
+ */
+export async function playFile(filePath, encoding) {
+  const player = findPlayer(encoding);
+  if (!player) return;
+  return new Promise((resolve, reject) => {
+    const args = [...player.args, filePath];
+    const proc = spawn(player.binary, args, { stdio: 'ignore' });
+    proc.on('close', () => resolve());
+    proc.on('error', reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 3c. play() — public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Play audio from a Uint8Array. Detects encoding from magic bytes unless overridden.
+ * Writes to a temp file, plays it, then deletes the temp file. Node.js only.
+ * @param {Uint8Array} audio
+ * @param {{ encoding?: string }} [options]
+ * @returns {Promise<void>}
+ * @example
+ * import { play } from '@inworld/tts';
+ * const audio = await tts.generate({ text: 'Hello!' });
+ * await play(audio); // encoding inferred from magic bytes
+ */
+export async function play(audio, options = {}) {
+  // File path input: play directly without reading into memory
+  if (typeof audio === 'string') {
+    const ext = audio.split('.').pop().toLowerCase();
+    const EXT_TO_ENCODING = { mp3: 'MP3', wav: 'WAV', ogg: 'OGG_OPUS', flac: 'FLAC', pcm: 'PCM' };
+    const encoding = options.encoding ? options.encoding.toUpperCase() : (EXT_TO_ENCODING[ext] || 'MP3');
+    return playFile(audio, encoding);
+  }
+  const encoding = options.encoding ? options.encoding.toUpperCase() : detectEncoding(audio);
+  const ext = EXT_MAP[encoding] || '.mp3';
+  const tmpPath = join(tmpdir(), `inworld-tts-${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`);
+  await writeFile(tmpPath, audio);
+  try {
+    await playFile(tmpPath, encoding);
+  } finally {
+    await unlink(tmpPath).catch(() => {});
+  }
+}

package/src/voice.js

@@ -0,0 +1,498 @@
+/**
+ * Voice API client: list, get, update, delete, clone, design, publish.
+ * Base URL: /voices/v1/voices
+ */
+
+import { getTimeoutSignal, withRetry } from './config.js';
+import { ApiError, MissingApiKeyError, NetworkError } from './errors.js';
+
+const VOICES_PATH = '/voices/v1/voices';
+
+function bytesToBase64(bytes) {
+  if (typeof Buffer !== 'undefined') {
+    return (Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)).toString('base64');
+  }
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+
+const DEFAULT_TIMEOUT = {
+  listVoices:      30_000,
+  cloneVoice:     300_000,
+  designVoice:    120_000,
+  publishVoice:    30_000,
+  migrateAudio:    60_000,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function authHeader(authValue) {
+  return { Authorization: authValue };
+}
+
+function jsonHeaders(authValue) {
+  return { 'Content-Type': 'application/json', Authorization: authValue };
+}
+
+async function parseErrorResponse(response) {
+  let errMsg = response.statusText;
+  let details = {};
+  try {
+    details = await response.json();
+    errMsg = details.message || JSON.stringify(details);
+  } catch (_) {}
+  return new ApiError(errMsg, response.status, details);
+}
+
+async function fetchWithRetry(url, fetchOpts, config) {
+  try {
+    return await withRetry(async () => {
+      let res;
+      try {
+        res = await fetch(url, fetchOpts);
+      } catch (e) {
+        // Let AbortError/TimeoutError pass through unwrapped so withRetry
+        // sees the original error and does not retry it.
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') throw e;
+        throw new NetworkError(e.message);
+      }
+      if (!res.ok) throw await parseErrorResponse(res);
+      return res;
+    }, config);
+  } catch (e) {
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') throw new NetworkError('Request timed out');
+    throw e;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// List voices
+// GET /voices/v1/voices[?languages=EN_US&languages=es]
+// ---------------------------------------------------------------------------
+
+export async function listVoices(options = {}, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+
+  const url = new URL(`${config._baseUrl}${VOICES_PATH}`);
+  if (options.languages && !options.lang) {
+    console.warn('[inworld-tts] Warning: "languages" has been renamed to "lang". Please update your code.');
+  }
+  const langs = options.lang ?? options.languages;
+  if (langs) {
+    const arr = Array.isArray(langs) ? langs : [langs];
+    for (const l of arr) url.searchParams.append('languages', l);
+  }
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.listVoices);
+  try {
+    const fetchOpts = { method: 'GET', headers: authHeader(config._authHeader), signal };
+    const res = await fetchWithRetry(url.toString(), fetchOpts, config);
+    let data;
+    try { data = await res.json(); } catch (_) { throw new ApiError('unexpected response: failed to parse JSON'); }
+    if (!Array.isArray(data.voices)) {
+      throw new ApiError('unexpected response: missing "voices" array');
+    }
+    return data.voices;
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Clone voice
+// POST /voices/v1/voices:clone
+// ---------------------------------------------------------------------------
+
+export async function cloneVoice(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+  const url = `${config._baseUrl}${VOICES_PATH}:clone`;
+
+  const rawSamples = options.audioSamples || [];
+  if (rawSamples.length === 0) throw new ApiError('options.audioSamples is required (array of Uint8Array / Buffer / file path strings)');
+  if (options.langCode && !options.lang) {
+    console.warn('[inworld-tts] Warning: "langCode" has been renamed to "lang". Please update your code.');
+  }
+
+  // Resolve file path strings to Uint8Array (Node.js only)
+  const samples = await Promise.all(rawSamples.map(async (s, i) => {
+    if (typeof s === 'string') {
+      let readFileSync;
+      try {
+        ({ readFileSync } = await import('fs'));
+      } catch {
+        throw new ApiError(`options.audioSamples[${i}] is a file path string, but file system access is not available in browser. Pass Uint8Array contents instead.`);
+      }
+      return readFileSync(s);
+    }
+    if (!(s instanceof Uint8Array)) {
+      throw new ApiError(`options.audioSamples[${i}] must be a Uint8Array, Buffer, or file path string (got ${typeof s})`);
+    }
+    return s;
+  }));
+
+  const voiceSamples = samples.map((buf, i) => {
+    const sample = { audioData: bytesToBase64(buf) };
+    if (options.transcriptions && i < options.transcriptions.length) {
+      sample.transcription = options.transcriptions[i];
+    }
+    return sample;
+  });
+
+  const body = {
+    displayName: options.displayName || 'Cloned Voice',
+    langCode: options.lang || options.langCode || 'EN_US',
+    voiceSamples,
+  };
+  if (options.description) body.description = options.description;
+  if (options.tags && options.tags.length) body.tags = options.tags;
+  if (options.removeBackgroundNoise) body.audioProcessingConfig = { removeBackgroundNoise: true };
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.cloneVoice);
+  try {
+    const fetchOpts = { method: 'POST', headers: jsonHeaders(config._authHeader), body: JSON.stringify(body), signal };
+    const res = await fetchWithRetry(url, fetchOpts, config);
+    try { return await res.json(); } catch (_) { throw new ApiError('unexpected response: failed to parse JSON'); }
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Design voice
+// POST /voices/v1/voices:design
+// ---------------------------------------------------------------------------
+
+export async function designVoice(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+  const url = `${config._baseUrl}${VOICES_PATH}:design`;
+
+  const prompt = options.designPrompt || '';
+  if (prompt.length < 30 || prompt.length > 250) {
+    throw new ApiError(`designPrompt must be 30-250 characters (got ${prompt.length})`);
+  }
+  if (!options.previewText) throw new ApiError('options.previewText is required');
+  if (options.langCode && !options.lang) {
+    console.warn('[inworld-tts] Warning: "langCode" has been renamed to "lang". Please update your code.');
+  }
+
+  const body = {
+    designPrompt: prompt,
+    previewText: options.previewText,
+    langCode: options.lang || options.langCode || 'EN_US',
+    voiceDesignConfig: { numberOfSamples: Math.min(3, Math.max(1, options.numberOfSamples || 1)) },
+  };
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.designVoice);
+  try {
+    const fetchOpts = { method: 'POST', headers: jsonHeaders(config._authHeader), body: JSON.stringify(body), signal };
+    const res = await fetchWithRetry(url, fetchOpts, config);
+    try { return await res.json(); } catch (_) { throw new ApiError('unexpected response: failed to parse JSON'); }
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Publish voice
+// POST /voices/v1/voices/{voiceId}:publish
+// ---------------------------------------------------------------------------
+
+export async function publishVoice(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+
+  const voiceId = options.voice;
+  if (!voiceId) throw new ApiError('options.voice is required');
+  const url = `${config._baseUrl}${VOICES_PATH}/${encodeURIComponent(voiceId)}:publish`;
+
+  const body = {};
+  if (options.displayName) body.displayName = options.displayName;
+  if (options.description) body.description = options.description;
+  if (options.tags && options.tags.length) body.tags = options.tags;
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.publishVoice);
+  try {
+    const fetchOpts = { method: 'POST', headers: jsonHeaders(config._authHeader), body: JSON.stringify(body), signal };
+    const res = await fetchWithRetry(url, fetchOpts, config);
+    try { return await res.json(); } catch (_) { throw new ApiError('unexpected response: failed to parse JSON'); }
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Get a specific voice
+// GET /voices/v1/voices/{voiceId}
+// ---------------------------------------------------------------------------
+
+export async function getVoice(voiceId, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+
+  if (!voiceId) throw new ApiError('voiceId is required');
+  const url = `${config._baseUrl}${VOICES_PATH}/${encodeURIComponent(voiceId)}`;
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.listVoices);
+  try {
+    const fetchOpts = { method: 'GET', headers: authHeader(config._authHeader), signal };
+    const res = await fetchWithRetry(url, fetchOpts, config);
+    try { return await res.json(); } catch (_) { throw new ApiError('unexpected response: failed to parse JSON'); }
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Update a voice
+// PATCH /voices/v1/voices/{voiceId}
+// ---------------------------------------------------------------------------
+
+export async function updateVoice(options, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+
+  const voiceId = options.voice;
+  if (!voiceId) throw new ApiError('options.voice is required');
+  const url = `${config._baseUrl}${VOICES_PATH}/${encodeURIComponent(voiceId)}`;
+
+  const body = {};
+  if (options.displayName != null) body.displayName = options.displayName;
+  if (options.description != null) body.description = options.description;
+  if (options.tags != null) body.tags = options.tags;
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.publishVoice);
+  try {
+    const fetchOpts = { method: 'PATCH', headers: jsonHeaders(config._authHeader), body: JSON.stringify(body), signal };
+    const res = await fetchWithRetry(url, fetchOpts, config);
+    try { return await res.json(); } catch (_) { throw new ApiError('unexpected response: failed to parse JSON'); }
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Delete a voice
+// DELETE /voices/v1/voices/{voiceId}
+// ---------------------------------------------------------------------------
+
+export async function deleteVoice(voiceId, config = {}) {
+  if (!config._authHeader) throw new MissingApiKeyError();
+
+  if (!voiceId) throw new ApiError('voiceId is required');
+  const url = `${config._baseUrl}${VOICES_PATH}/${encodeURIComponent(voiceId)}`;
+
+  const { signal, clear } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.publishVoice);
+  try {
+    const fetchOpts = { method: 'DELETE', headers: authHeader(config._authHeader), signal };
+    await fetchWithRetry(url, fetchOpts, config);
+  } finally {
+    clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Migrate from ElevenLabs (single voice)
+// ---------------------------------------------------------------------------
+
+const LANG_TO_INWORLD = {
+  en: 'EN_US', zh: 'ZH_CN', ja: 'JA_JP', ko: 'KO_KR',
+  es: 'ES_ES', fr: 'FR_FR', de: 'DE_DE', pt: 'PT_BR',
+  it: 'IT_IT', pl: 'PL_PL', ru: 'RU_RU', hi: 'HI_IN',
+  ar: 'AR_SA', nl: 'NL_NL', he: 'HE_IL',
+};
+
+// ---------------------------------------------------------------------------
+// WAV header builder (Option C: preserve original format, only trim duration)
+// ---------------------------------------------------------------------------
+
+function buildWavHeader(dataLen, sampleRate, channels, bitsPerSample) {
+  const buf = new ArrayBuffer(44);
+  const view = new DataView(buf);
+  const writeUint32LE = (off, v) => view.setUint32(off, v, true);
+  const writeUint16LE = (off, v) => view.setUint16(off, v, true);
+
+  // RIFF chunk
+  view.setUint8(0, 0x52); view.setUint8(1, 0x49); view.setUint8(2, 0x46); view.setUint8(3, 0x46); // "RIFF"
+  writeUint32LE(4, 36 + dataLen);   // ChunkSize
+  view.setUint8(8, 0x57); view.setUint8(9, 0x41); view.setUint8(10, 0x56); view.setUint8(11, 0x45); // "WAVE"
+
+  // fmt sub-chunk
+  view.setUint8(12, 0x66); view.setUint8(13, 0x6D); view.setUint8(14, 0x74); view.setUint8(15, 0x20); // "fmt "
+  writeUint32LE(16, 16);            // Subchunk1Size (PCM)
+  writeUint16LE(20, 1);             // AudioFormat (PCM)
+  writeUint16LE(22, channels);
+  writeUint32LE(24, sampleRate);
+  writeUint32LE(28, sampleRate * channels * (bitsPerSample >> 3)); // ByteRate
+  writeUint16LE(32, channels * (bitsPerSample >> 3));              // BlockAlign
+  writeUint16LE(34, bitsPerSample);
+
+  // data sub-chunk
+  view.setUint8(36, 0x64); view.setUint8(37, 0x61); view.setUint8(38, 0x74); view.setUint8(39, 0x61); // "data"
+  writeUint32LE(40, dataLen);
+
+  return new Uint8Array(buf);
+}
+
+function trimWavTo15s(bytes) {
+  // Validate RIFF header
+  if (bytes[0] !== 0x52 || bytes[1] !== 0x49 || bytes[2] !== 0x46 || bytes[3] !== 0x46) {
+    return bytes; // not a valid WAV
+  }
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const sampleRate    = view.getUint32(24, true);
+  const channels      = view.getUint16(22, true);
+  const bitsPerSample = view.getUint16(34, true);
+
+  // Find the "data" sub-chunk (may not always be at offset 44)
+  let dataOffset = 12;
+  while (dataOffset + 8 <= bytes.length) {
+    const id = String.fromCharCode(bytes[dataOffset], bytes[dataOffset+1], bytes[dataOffset+2], bytes[dataOffset+3]);
+    const chunkSize = view.getUint32(dataOffset + 4, true);
+    if (id === 'data') {
+      dataOffset += 8;
+      break;
+    }
+    dataOffset += 8 + chunkSize;
+  }
+
+  const pcm = bytes.slice(dataOffset);
+  const maxDataBytes = Math.floor(15 * sampleRate * channels * (bitsPerSample >> 3));
+
+  if (pcm.length <= maxDataBytes) return bytes; // no trim needed
+
+  const trimmedPcm = pcm.slice(0, maxDataBytes);
+  const header = buildWavHeader(trimmedPcm.length, sampleRate, channels, bitsPerSample);
+  const result = new Uint8Array(header.length + trimmedPcm.length);
+  result.set(header, 0);
+  result.set(trimmedPcm, header.length);
+  return result;
+}
+
+// MP3 bitrate table for MPEG1 Layer3 (index 1-14; index 0 = free, 15 = bad)
+const MP3_BITRATES = [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320];
+
+function findMp3FrameSync(bytes, startOffset) {
+  for (let i = startOffset; i < bytes.length - 1; i++) {
+    if (bytes[i] === 0xFF && (bytes[i+1] & 0xE0) === 0xE0) return i;
+  }
+  return -1;
+}
+
+function trimMp3To15s(bytes) {
+  const firstSync = findMp3FrameSync(bytes, 0);
+  if (firstSync < 0) return bytes;
+
+  const b1 = bytes[firstSync + 1];
+  const b2 = bytes[firstSync + 2];
+
+  // Verify MPEG version and layer (we only handle MPEG1/2 Layer 3)
+  const mpegVersion = (b1 >> 3) & 0x03; // 0b11=MPEG1, 0b10=MPEG2
+  const layer       = (b1 >> 1) & 0x03; // 0b01=Layer3
+  if (layer !== 1) return bytes; // not Layer 3
+
+  const bitrateIdx  = (b2 >> 4) & 0x0F;
+  if (bitrateIdx === 0 || bitrateIdx === 15) return bytes; // free/bad bitrate
+
+  // For MPEG2 the bitrate table differs but for estimation purposes we use the same table
+  const bitrateKbps = MP3_BITRATES[bitrateIdx];
+  const estimatedBytes = Math.floor(15 * bitrateKbps * 1000 / 8);
+
+  if (bytes.length <= estimatedBytes) return bytes;
+
+  // Scan back from estimatedBytes to find a frame boundary
+  const cutPos = findMp3FrameSync(bytes, estimatedBytes);
+  const actualCut = cutPos > firstSync ? cutPos : estimatedBytes;
+
+  return bytes.slice(0, actualCut);
+}
+
+function trimAudioTo15s(bytes) {
+  if (bytes.length === 0) return bytes;
+
+  // WAV: starts with RIFF
+  if (bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46) {
+    return trimWavTo15s(bytes);
+  }
+
+  // MP3: look for frame sync
+  const mp3Sync = findMp3FrameSync(bytes, 0);
+  if (mp3Sync >= 0 && mp3Sync < 4) {
+    return trimMp3To15s(bytes);
+  }
+
+  // Other formats (OGG, FLAC, etc.) — return as-is
+  return bytes;
+}
+
+export async function migrateFromElevenLabs({ elevenLabsApiKey, elevenLabsVoiceId } = {}, config = {}) {
+  if (!elevenLabsApiKey) throw new ApiError('elevenLabsApiKey is required');
+  if (!elevenLabsVoiceId) throw new ApiError('elevenLabsVoiceId is required');
+  const voiceId = elevenLabsVoiceId;
+  if (!config._authHeader) throw new MissingApiKeyError();
+
+  // 1. Fetch voice metadata
+  const { signal: metaSignal, clear: clearMeta } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.listVoices);
+  let meta;
+  try {
+    const metaRes = await fetch(
+      `https://api.elevenlabs.io/v1/voices/${encodeURIComponent(voiceId)}`,
+      { headers: { 'xi-api-key': elevenLabsApiKey }, signal: metaSignal }
+    );
+    if (!metaRes.ok) {
+      const err = await metaRes.json().catch(() => ({}));
+      const msg = (typeof err.detail === 'string' ? err.detail : err.detail?.message) || err.message || metaRes.statusText;
+      throw new ApiError(`ElevenLabs get voice failed: ${msg}`, metaRes.status, err);
+    }
+    meta = await metaRes.json();
+  } finally {
+    clearMeta();
+  }
+
+  const voiceName = meta.name;
+  const rawLang = (meta.labels?.language || 'en').toLowerCase().split(/[-_]/)[0];
+  const inworldLang = LANG_TO_INWORLD[rawLang] ?? 'EN_US';
+
+  // 2. Get sample audio: try first sample, fallback to preview_url
+  const { signal: audioSignal, clear: clearAudio } = getTimeoutSignal(config.timeout ?? DEFAULT_TIMEOUT.migrateAudio);
+  let audioBytes;
+  try {
+    const samples = meta.samples;
+    if (samples && samples.length > 0) {
+      const sampleId = samples[0].sample_id;
+      const sampleRes = await fetch(
+        `https://api.elevenlabs.io/v1/voices/${encodeURIComponent(voiceId)}/samples/${encodeURIComponent(sampleId)}/audio`,
+        { headers: { 'xi-api-key': elevenLabsApiKey }, signal: audioSignal }
+      );
+      if (!sampleRes.ok) {
+        const err = await sampleRes.json().catch(() => ({}));
+        const msg = (typeof err.detail === 'string' ? err.detail : err.detail?.message) || err.message || sampleRes.statusText;
+        throw new ApiError(`ElevenLabs get sample audio failed: ${msg}`, sampleRes.status, err);
+      }
+      audioBytes = new Uint8Array(await sampleRes.arrayBuffer());
+    } else if (meta.preview_url) {
+      const previewRes = await fetch(meta.preview_url, { signal: audioSignal });
+      if (!previewRes.ok) {
+        throw new ApiError(`ElevenLabs fetch preview_url failed: ${previewRes.statusText}`, previewRes.status);
+      }
+      audioBytes = new Uint8Array(await previewRes.arrayBuffer());
+    } else {
+      throw new ApiError('No voice samples or preview_url available for this ElevenLabs voice');
+    }
+  } finally {
+    clearAudio();
+  }
+
+  // 3. Trim to 15 s if needed
+  audioBytes = trimAudioTo15s(audioBytes);
+
+  // 4. Clone to Inworld
+  const cloneResult = await cloneVoice(
+    { displayName: voiceName, audioSamples: [audioBytes], lang: inworldLang },
+    config
+  );
+
+  const inworldVoiceId = cloneResult.voice?.voiceId;
+  if (!inworldVoiceId) throw new ApiError('unexpected Inworld clone response: missing voiceId');
+  return { elevenLabsVoiceId: voiceId, elevenLabsName: voiceName, inworldVoiceId };
+}