@inworld/tts 0.0.0

package/src/config.js

@@ -0,0 +1,135 @@
+/** Config, env helpers, and retry logic. Works in Node.js 18+ and modern browsers. */
+
+const DEFAULT_BASE_URL = 'https://api.inworld.ai';
+
+export const MAX_CHUNK_SIZE = 1900;
+export const MIN_CHUNK_SIZE = 500;
+export const CHARS_PER_SECOND = 12.0; // approx speaking rate; used to convert <break> durations to equivalent char counts
+export const CJK_CHAR_WEIGHT = 3.0;  // CJK chars produce ~3x more audio than Latin chars
+export const SPLICE_BREAK_SECONDS = 0.5;
+export const SAMPLE_RATE = 48000;
+export const BITS_PER_SAMPLE = 16;
+export const CHANNELS = 1;
+export const MAX_CONCURRENT_REQUESTS = 2;
+export const GENERATE_MAX_CHARS = 2000;
+export const STREAM_MAX_CHARS = 2000;
+
+const _env = typeof process !== 'undefined' ? process.env : {};
+
+export function getApiKey(apiKey) {
+  return apiKey || _env.INWORLD_API_KEY || null;
+}
+
+export function debugLog(config, ...args) {
+  if (config.debug || _env.DEBUG === 'inworld-tts') {
+    console.debug('[inworld-tts]', ...args);
+  }
+}
+
+function isRetryable(e) {
+  if (e && (e.name === 'AbortError' || e.name === 'TimeoutError')) return false;
+  if (e && e.name === 'NetworkError') return true;
+  if (e && e.name === 'ApiError' && typeof e.code === 'number' && e.code >= 500) return true;
+  return false;
+}
+
+export async function withRetry(fn, config) {
+  const retries = config.maxRetries ?? 2;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0) {
+      const delay = Math.min(1000 * 2 ** (attempt - 1), 16000);
+      debugLog(config, `retry ${attempt}/${retries} after ${delay}ms`);
+      await new Promise(r => setTimeout(r, delay));
+    }
+    try {
+      return await fn();
+    } catch (e) {
+      if (!isRetryable(e) || attempt >= retries) throw e;
+      debugLog(config, `retryable error (${e.name}): ${e.message}`);
+    }
+  }
+}
+
+export function getBaseUrl(baseUrl) {
+  const base = (baseUrl || _env.INWORLD_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, '');
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Browser detection
+// ---------------------------------------------------------------------------
+
+export function isRunningInBrowser() {
+  return typeof window !== 'undefined'
+    && typeof window.document !== 'undefined'
+    && typeof navigator !== 'undefined';
+}
+
+// ---------------------------------------------------------------------------
+// AbortSignal compatibility (replaces AbortSignal.timeout())
+// ---------------------------------------------------------------------------
+
+export function getTimeoutSignal(ms) {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), ms);
+  return { signal: controller.signal, clear: () => clearTimeout(id) };
+}
+
+// ---------------------------------------------------------------------------
+// JWT token refresh helpers
+// ---------------------------------------------------------------------------
+
+export function getJwtExp(token) {
+  let exp = null;
+  try {
+    // JWT uses base64url (- and _ instead of + and /), atob() requires standard base64 with padding
+    let b64 = token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
+    while (b64.length % 4) b64 += '=';
+    const payload = JSON.parse(atob(b64));
+    exp = payload.exp ?? null;
+  } catch { /* parse failed, exp stays null */ }
+  if (exp === null) {
+    console.warn('[inworld-tts] Could not parse token expiry — token refresh will not be scheduled. Ensure token is a valid JWT.');
+  }
+  return exp;
+}
+
+// Stale-while-revalidate token refresh. Called before every API request.
+// - apiKey users: no-op (no _token)
+// - token already expired: await refresh before proceeding
+// - token expiring within 5 min: fire background refresh, proceed with current token
+// - token fine: no-op
+export async function ensureFreshToken(config) {
+  if (!config._token || !config._onTokenExpiring) return;
+  const exp = getJwtExp(config._token);
+  if (!exp) return;
+
+  const msUntilExp = exp * 1000 - Date.now();
+
+  const doRefresh = () => {
+    if (config._refreshPromise) return config._refreshPromise;
+    config._refreshPromise = Promise.resolve()
+      .then(() => config._onTokenExpiring())
+      .then(newToken => {
+        if (!newToken || typeof newToken !== 'string') {
+          console.warn('[inworld-tts] onTokenExpiring must return a non-empty string token');
+          return;
+        }
+        config._token = newToken;
+        config._authHeader = `Bearer ${newToken}`;
+      })
+      .catch(e => {
+        console.warn('[inworld-tts] Token refresh failed:', e.message);
+      })
+      .finally(() => {
+        config._refreshPromise = null;
+      });
+    return config._refreshPromise;
+  };
+
+  if (msUntilExp <= 0) {
+    await doRefresh();                // already expired — must wait
+  } else if (msUntilExp < 5 * 60 * 1000) {
+    doRefresh();                      // expiring soon — refresh in background, don't await
+  }
+}

package/src/encoding.js

@@ -0,0 +1,23 @@
+/**
+ * Audio encoding detection from magic bytes. Platform-independent — works in Node.js and browsers.
+ */
+
+/**
+ * Infer audio encoding from magic bytes. Falls back to 'MP3'.
+ * @param {Uint8Array} audio
+ * @returns {string}
+ */
+export function detectEncoding(audio) {
+  if (!audio || audio.length < 4) return 'MP3';
+  // RIFF → WAV
+  if (audio[0] === 0x52 && audio[1] === 0x49 && audio[2] === 0x46 && audio[3] === 0x46) return 'WAV';
+  // fLaC → FLAC
+  if (audio[0] === 0x66 && audio[1] === 0x4C && audio[2] === 0x61 && audio[3] === 0x43) return 'FLAC';
+  // OggS → OGG_OPUS
+  if (audio[0] === 0x4F && audio[1] === 0x67 && audio[2] === 0x67 && audio[3] === 0x53) return 'OGG_OPUS';
+  // ID3 → MP3
+  if (audio[0] === 0x49 && audio[1] === 0x44 && audio[2] === 0x33) return 'MP3';
+  // MP3 sync bytes
+  if (audio[0] === 0xFF && (audio[1] & 0xE0) === 0xE0) return 'MP3';
+  return 'MP3';
+}

package/src/errors.js

@@ -0,0 +1,31 @@
+/** TTS SDK errors. */
+
+export class InworldTTSError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'InworldTTSError';
+  }
+}
+
+export class MissingApiKeyError extends InworldTTSError {
+  constructor(message = 'INWORLD_API_KEY is not set. To fix this:\n  1. Set the environment variable: export INWORLD_API_KEY=your_key\n  2. Pass it to the constructor: InworldTTS({ apiKey: "your_key" })\n  3. Or use a JWT token: InworldTTS({ token: "your_jwt" })\n     (See: https://docs.inworld.ai/api-reference/introduction#jwt-authentication)\nGet your API key at https://platform.inworld.ai') {
+    super(message);
+    this.name = 'MissingApiKeyError';
+  }
+}
+
+export class ApiError extends InworldTTSError {
+  constructor(message, code = null, details = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class NetworkError extends InworldTTSError {
+  constructor(message) {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,363 @@
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class InworldTTSError extends Error {
+  name: 'InworldTTSError';
+}
+
+export class MissingApiKeyError extends InworldTTSError {
+  name: 'MissingApiKeyError';
+}
+
+export class ApiError extends InworldTTSError {
+  name: 'ApiError';
+  code: number | null;
+  details: Record<string, unknown>;
+}
+
+export class NetworkError extends InworldTTSError {
+  name: 'NetworkError';
+}
+
+// ---------------------------------------------------------------------------
+// Shared option types
+// ---------------------------------------------------------------------------
+
+export type AudioEncoding =
+  | 'MP3'
+  | 'OGG_OPUS'
+  | 'LINEAR16'
+  | 'WAV'
+  | 'PCM'
+  | 'FLAC'
+  | 'ALAW'
+  | 'MULAW';
+
+export type TextNormalization = 'ON' | 'OFF' | 'none';
+
+/** Options shared by generate() and stream(). */
+export interface TtsOptions {
+  /** Text to synthesize. Required. */
+  text: string;
+  /** Voice ID. Required. */
+  voice: string;
+  /** Model ID. Defaults differ per method (see method docs). */
+  model?: string;
+  /** Audio encoding format. Default: 'MP3'. */
+  encoding?: AudioEncoding;
+  /** Sample rate in Hz. Default: 48000. */
+  sampleRate?: number;
+  /** Bit rate in bps for MP3/OGG_OPUS. Default: 128000. */
+  bitRate?: number;
+  /** Speaking rate multiplier (0.5–1.5). Default: 1.0. */
+  speakingRate?: number;
+  /** Temperature for expressiveness (0.0–2.0). Default: 1.0. */
+  temperature?: number;
+  /** Text normalization mode. */
+  applyTextNormalization?: TextNormalization;
+}
+
+/** Options for generate(). Extends TtsOptions with outputFile convenience. */
+export interface GenerateOptions extends TtsOptions {
+  /**
+   * If provided, the audio is also written to this file path (Node.js only).
+   * The Uint8Array is still returned regardless.
+   */
+  outputFile?: string;
+  /** If true, play the generated audio immediately (Node.js only). */
+  play?: boolean;
+}
+
+/** Options for stream(). Same options as generate() except model defaults to 'inworld-tts-1.5-mini'. Max 2000 chars. */
+export interface StreamOptions extends TtsOptions {
+  /** Write audio to this file path after streaming completes (Node.js only). */
+  outputFile?: string;
+  /** Play audio after streaming completes. */
+  play?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp types
+// ---------------------------------------------------------------------------
+
+export type TimestampType = 'WORD' | 'CHARACTER';
+
+export interface PhoneInfo {
+  phoneSymbol: string;
+  startTimeSeconds: number;
+  durationSeconds: number;
+  visemeSymbol: string;
+}
+
+export interface PhoneticDetail {
+  wordIndex: number;
+  phones: PhoneInfo[];
+  isPartial: boolean;
+}
+
+export interface WordAlignment {
+  words: string[];
+  wordStartTimeSeconds: number[];
+  wordEndTimeSeconds: number[];
+  phoneticDetails: PhoneticDetail[];
+}
+
+export interface CharacterAlignment {
+  characters: string[];
+  characterStartTimeSeconds: number[];
+  characterEndTimeSeconds: number[];
+}
+
+export interface TimestampInfo {
+  /** Present when timestampType is 'WORD'. */
+  wordAlignment?: WordAlignment;
+  /** Present when timestampType is 'CHARACTER'. */
+  characterAlignment?: CharacterAlignment;
+}
+
+export interface GenerateWithTimestampsOptions extends TtsOptions {
+  /** Required. Whether to align by word or character. */
+  timestampType: TimestampType;
+  /** Write audio to this file path (Node.js only). */
+  outputFile?: string;
+  /** Play audio after generating (Node.js only). */
+  play?: boolean;
+}
+
+export interface StreamWithTimestampsOptions extends TtsOptions {
+  /** Required. Whether to align by word or character. */
+  timestampType: TimestampType;
+  /** Write audio to this file path after streaming completes (Node.js only). */
+  outputFile?: string;
+  /** Play audio after streaming completes (Node.js only). */
+  play?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Voice API types
+// ---------------------------------------------------------------------------
+
+export interface ListVoicesOptions {
+  /** Filter by language(s), e.g. 'EN_US' or ['EN_US', 'es']. */
+  lang?: string | string[];
+}
+
+export interface VoiceSample {
+  audioData: string;
+  transcription?: string;
+}
+
+export interface VoiceInfo {
+  voiceId: string;
+  displayName: string;
+  langCode?: string;
+  description?: string;
+  tags?: string[];
+  name?: string;
+  source?: string;
+}
+
+/** @deprecated Use VoiceInfo instead. */
+export type Voice = VoiceInfo;
+
+export interface CloneVoiceOptions {
+  /** Human-readable name for the cloned voice. Default: 'Cloned Voice'. */
+  displayName?: string;
+  /** Array of audio samples: WAV or MP3 file contents (Uint8Array/Buffer) or file path strings (Node.js only). */
+  audioSamples: Array<Uint8Array | string>;
+  /** Language code. Default: 'EN_US'. */
+  lang?: string;
+  /** Voice description. */
+  description?: string;
+  /** Tags for the voice. */
+  tags?: string[];
+  /** Transcriptions aligned with audioSamples. */
+  transcriptions?: string[];
+  /** Enable background noise removal. */
+  removeBackgroundNoise?: boolean;
+}
+
+export interface AudioSampleValidation {
+  transcription?: string;
+  langCode?: string;
+  warnings?: Array<Record<string, unknown>>;
+  errors?: Array<Record<string, unknown>>;
+  audioData?: string;
+}
+
+export interface CloneVoiceResult {
+  voice: VoiceInfo;
+  audioSamplesValidated?: AudioSampleValidation[];
+}
+
+export interface DesignVoiceOptions {
+  /** Voice description prompt (30-250 characters). */
+  designPrompt: string;
+  /** Text to be spoken in preview audio. */
+  previewText: string;
+  /** Language code. Default: 'EN_US'. */
+  lang?: string;
+  /** Number of preview voice samples to generate (1-3). Default: 1. */
+  numberOfSamples?: number;
+}
+
+export interface PreviewVoice {
+  voiceId: string;
+  previewText?: string;
+  previewAudio?: string;
+}
+
+export interface DesignVoiceResult {
+  previewVoices: PreviewVoice[];
+  langCode?: string;
+}
+
+export interface ElevenLabsMigrateResult {
+  elevenLabsVoiceId: string;
+  elevenLabsName: string;
+  inworldVoiceId: string;
+}
+
+export interface PublishVoiceOptions {
+  /** Voice ID from a design preview or clone. */
+  voice: string;
+  /** Display name for the published voice. */
+  displayName?: string;
+  /** Description. */
+  description?: string;
+  /** Tags. */
+  tags?: string[];
+}
+
+export interface UpdateVoiceOptions {
+  /** Voice ID to update. */
+  voice: string;
+  /** New display name. */
+  displayName?: string;
+  /** New description. */
+  description?: string;
+  /** New tags. */
+  tags?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+export interface ClientOptions {
+  /** API key. Falls back to INWORLD_API_KEY environment variable. Mutually exclusive with token. */
+  apiKey?: string;
+  /** JWT token for browser use. Mutually exclusive with apiKey. */
+  token?: string;
+  /**
+   * Called automatically when the token is about to expire. Must return a fresh JWT string.
+   * Only used when token is provided.
+   */
+  onTokenExpiring?: () => Promise<string>;
+  /**
+   * Allow API key usage in browser environments.
+   * Your key will be visible in DevTools and billed to your account.
+   * Recommended: use token + onTokenExpiring for browser instead.
+   */
+  dangerouslyAllowBrowser?: boolean;
+  /** Override the API base URL. */
+  baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds. Overrides per-method defaults:
+   * generate/stream: 60s, listVoices: 30s, cloneVoice: 120s, designVoice: 60s, publishVoice: 30s.
+   */
+  timeout?: number;
+  /** Max parallel requests for long-text chunking. Default: 2. */
+  maxConcurrentRequests?: number;
+  /** Number of retries on NetworkError or 5xx responses (exponential backoff). Default: 2. */
+  maxRetries?: number;
+  /** Enable debug logging. Also activated by setting DEBUG=inworld-tts env var. */
+  debug?: boolean;
+}
+
+export interface InworldTTSClient {
+  /**
+   * Synthesize speech from text of any length.
+   * Short text (≤2000 chars) → single request.
+   * Long text → auto-chunked, parallelized, merged into one Uint8Array.
+   * Default model: inworld-tts-1.5-max.
+   * @returns Audio data as a Uint8Array (Buffer in Node.js).
+   */
+  generate(options: GenerateOptions): Promise<Uint8Array>;
+
+  /**
+   * Stream TTS audio over HTTP (max 2000 chars per call).
+   * Default model: inworld-tts-1.5-mini (lower latency).
+   * @returns Async iterable of Uint8Array audio chunks (Buffer in Node.js).
+   */
+  stream(options: StreamOptions): AsyncGenerator<Uint8Array>;
+
+  /**
+   * Synthesize speech with word/character timestamp alignment.
+   * Short text (≤2000 chars) → single request.
+   * Long text → auto-chunked, timestamps offset-adjusted and merged.
+   * Default model: inworld-tts-1.5-max.
+   */
+  generateWithTimestamps(options: GenerateWithTimestampsOptions): Promise<{ audio: Uint8Array; timestamps: TimestampInfo }>;
+
+  /**
+   * Stream TTS audio with word/character timestamp alignment (max 2000 chars per call).
+   * Timestamps are delivered synchronously with each audio chunk.
+   * Default model: inworld-tts-1.5-mini.
+   */
+  streamWithTimestamps(options: StreamWithTimestampsOptions): AsyncGenerator<{ audio: Uint8Array; timestamps?: TimestampInfo }>;
+
+  /** List voices in the workspace. */
+  listVoices(options?: ListVoicesOptions): Promise<VoiceInfo[]>;
+
+  /** Get details of a specific voice by ID. */
+  getVoice(voice: string): Promise<VoiceInfo>;
+
+  /** Update a voice's metadata. */
+  updateVoice(options: UpdateVoiceOptions): Promise<VoiceInfo>;
+
+  /** Delete a voice from your workspace. */
+  deleteVoice(voice: string): Promise<void>;
+
+  /** Clone a voice from audio samples. */
+  cloneVoice(options: CloneVoiceOptions): Promise<CloneVoiceResult>;
+
+  /** Design a voice from a text description. */
+  designVoice(options: DesignVoiceOptions): Promise<DesignVoiceResult>;
+
+  /** Publish a designed/cloned voice preview to your library. */
+  publishVoice(options: PublishVoiceOptions): Promise<VoiceInfo>;
+
+  /**
+   * Play audio from a Uint8Array. Encoding detected from magic bytes unless overridden.
+   * - Node.js: writes a temp file, plays via system player, deletes. Does not throw if no player found.
+   * - Browser: uses <audio> element. Supports MP3/WAV/OGG_OPUS/FLAC. Must be called inside a user
+   *   event handler (e.g. button click) — browsers block autoplay outside user gestures.
+   *   Prefer encoding: 'MP3' for widest browser compatibility.
+   */
+  play(audio: Uint8Array | string, options?: { encoding?: string }): Promise<void>;
+
+  /**
+   * Migrate a single ElevenLabs voice to your Inworld workspace.
+   * Fetches metadata and sample audio from ElevenLabs, then clones into Inworld.
+   * Uses only fetch — no ElevenLabs SDK required.
+   */
+  migrateFromElevenLabs(options: { elevenLabsApiKey: string; elevenLabsVoiceId: string }): Promise<ElevenLabsMigrateResult>;
+
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an Inworld TTS client.
+ * Throws MissingApiKeyError immediately if no API key is found.
+ */
+export function createClient(opts?: ClientOptions): InworldTTSClient;
+
+/**
+ * Alias for createClient().
+ */
+export function InworldTTS(opts?: ClientOptions): InworldTTSClient;

package/src/index.js

@@ -0,0 +1,149 @@
+/**
+ * Inworld TTS SDK: generate, stream, and Voice management.
+ */
+
+import {
+  generate as generateReq,
+  stream as streamReq,
+  generateWithTimestamps as generateWithTimestampsReq,
+  streamWithTimestamps as streamWithTimestampsReq,
+} from './client.js';
+import {
+  listVoices as listVoicesReq,
+  getVoice as getVoiceReq,
+  updateVoice as updateVoiceReq,
+  deleteVoice as deleteVoiceReq,
+  cloneVoice as cloneVoiceReq,
+  designVoice as designVoiceReq,
+  publishVoice as publishVoiceReq,
+  migrateFromElevenLabs as migrateFromElevenLabsReq,
+} from './voice.js';
+import { ApiError, InworldTTSError, MissingApiKeyError, NetworkError } from './errors.js';
+import { play } from './player.js';
+import { isRunningInBrowser, ensureFreshToken, getBaseUrl } from './config.js';
+
+export { ApiError, InworldTTSError, MissingApiKeyError, NetworkError };
+
+/**
+ * Create an Inworld TTS client.
+ * @param {{
+ *   apiKey?: string,
+ *   token?: string,
+ *   onTokenExpiring?: () => Promise<string>,
+ *   dangerouslyAllowBrowser?: boolean,
+ *   baseUrl?: string,
+ *   timeout?: number,
+ *   maxConcurrentRequests?: number,
+ *   maxRetries?: number,
+ *   debug?: boolean
+ * }} [opts]
+ * @returns {{ generate, stream, generateWithTimestamps, streamWithTimestamps, play, listVoices, getVoice, updateVoice, deleteVoice, cloneVoice, designVoice, publishVoice, migrateFromElevenLabs }}
+ * @example
+ * import { createClient } from '@inworld/tts';
+ * import { writeFileSync } from 'fs';
+ *
+ * // Node.js — API key from env
+ * const tts = createClient();
+ * const audio = await tts.generate({ text: 'Hello world!' });
+ * writeFileSync('hello.mp3', audio);
+ *
+ * // Browser — JWT token
+ * const tts = createClient({ token: await fetchToken(), onTokenExpiring: fetchToken });
+ * const audio = await tts.generate({ text: 'Hello!', encoding: 'MP3' });
+ * button.onclick = () => tts.play(audio);
+ */
+export function createClient(opts = {}) {
+  const token = opts.token ?? null;
+  const env = typeof process !== 'undefined' ? process.env?.INWORLD_API_KEY : null;
+  const apiKey = token ? null : (opts.apiKey ?? env ?? null);
+
+  // 4b: Warn about redundant/misused options
+  if (opts.token && opts.apiKey) {
+    console.warn('[inworld-tts] Both token and apiKey provided — apiKey will be ignored');
+  }
+  if (opts.onTokenExpiring && !token) {
+    console.warn('[inworld-tts] onTokenExpiring is ignored when no token is provided');
+  }
+
+  // 4c: Browser safety gate
+  if (!token && apiKey && isRunningInBrowser()) {
+    if (!opts.dangerouslyAllowBrowser) {
+      throw new InworldTTSError(
+        'Running in browser with API key is disabled by default. ' +
+        'Your API key would be exposed to end users.\n' +
+        'Recommended: use a JWT token instead: createClient({ token: \'your_jwt\' })\n' +
+        'See: https://docs.inworld.ai/api-reference/introduction#jwt-authentication\n' +
+        'Or to opt in anyway: createClient({ apiKey: \'...\', dangerouslyAllowBrowser: true })'
+      );
+    }
+    console.warn('[inworld-tts] dangerouslyAllowBrowser is set. Your API key is visible to anyone using browser DevTools and can be used to make requests at your expense.');
+  }
+
+  // 4a: Require at least one auth method
+  if (!apiKey && !token) throw new MissingApiKeyError();
+
+  // 4d: Build config with auth header and resolved baseUrl
+  const config = {
+    _baseUrl: getBaseUrl(opts.baseUrl ?? null),
+    _authHeader: token ? `Bearer ${token}` : `Basic ${apiKey}`,
+    _token: token,
+    _onTokenExpiring: (token && opts.onTokenExpiring) ? opts.onTokenExpiring : null,
+    _refreshPromise: null,
+    timeout: opts.timeout ?? null,
+    maxConcurrentRequests: opts.maxConcurrentRequests,
+    maxRetries: opts.maxRetries ?? 2,
+    debug: opts.debug ?? false,
+  };
+
+  return {
+    async generate(options) {
+      await ensureFreshToken(config);
+      return generateReq(options, config);
+    },
+    async *stream(options) {
+      await ensureFreshToken(config);
+      yield* streamReq(options, config);
+    },
+    async generateWithTimestamps(options) {
+      await ensureFreshToken(config);
+      return generateWithTimestampsReq(options, config);
+    },
+    async *streamWithTimestamps(options) {
+      await ensureFreshToken(config);
+      yield* streamWithTimestampsReq(options, config);
+    },
+    async listVoices(options) { await ensureFreshToken(config); return listVoicesReq(options, config); },
+    async getVoice(voice) { await ensureFreshToken(config); return getVoiceReq(voice, config); },
+    async updateVoice(options) { await ensureFreshToken(config); return updateVoiceReq(options, config); },
+    async deleteVoice(voice) { await ensureFreshToken(config); return deleteVoiceReq(voice, config); },
+    async cloneVoice(options) { await ensureFreshToken(config); return cloneVoiceReq(options, config); },
+    async designVoice(options) { await ensureFreshToken(config); return designVoiceReq(options, config); },
+    async publishVoice(options) { await ensureFreshToken(config); return publishVoiceReq(options, config); },
+    async migrateFromElevenLabs(options) { await ensureFreshToken(config); return migrateFromElevenLabsReq(options, config); },
+    async play(audio, options) { return play(audio, options); },
+  };
+}
+
+/**
+ * Alias for createClient(). Accepts the same options.
+ * @param {{
+ *   apiKey?: string,
+ *   token?: string,
+ *   onTokenExpiring?: () => Promise<string>,
+ *   dangerouslyAllowBrowser?: boolean,
+ *   baseUrl?: string,
+ *   timeout?: number,
+ *   maxConcurrentRequests?: number,
+ *   maxRetries?: number,
+ *   debug?: boolean
+ * }} [opts]
+ * @returns {{ generate, stream, generateWithTimestamps, streamWithTimestamps, play, listVoices, getVoice, updateVoice, deleteVoice, cloneVoice, designVoice, publishVoice, migrateFromElevenLabs }}
+ * @example
+ * import { InworldTTS } from '@inworld/tts';
+ *
+ * const tts = InworldTTS(); // reads INWORLD_API_KEY from env
+ * const audio = await tts.generate({ text: 'Hello world!' });
+ */
+export function InworldTTS(opts = {}) {
+  return createClient(opts);
+}