Node.js SDK

The @inworld/tts Node.js SDK wraps the Inworld TTS REST API with a clean, typed interface. It handles chunking for long text, retries with exponential backoff, and connection management automatically — reducing typical integrations from 30+ lines of raw HTTP to just a few lines of code.

npm install @inworld/tts

Quick Start

import { InworldTTS } from '@inworld/tts';
import fs from 'fs';

const tts = InworldTTS(); // reads INWORLD_API_KEY from env

const audio = await tts.generate({
  text: 'What a wonderful day to be a text-to-speech model!',
  voice: 'Ashley',
});

fs.writeFileSync('output.mp3', audio);

Speech Synthesis

generate(options)

Synthesize speech and return the complete audio as a Uint8Array. Text longer than 2,000 characters is automatically chunked and sent in parallel.

const audio = await tts.generate({
  text: 'Hello, world!',
  voice: 'Ashley',
  model: 'inworld-tts-2',
  encoding: 'MP3',
  outputFile: 'output.mp3', // optional — also writes to disk
});

Returns: Uint8Array — raw audio bytes in the requested encoding.

stream(options)

Stream audio chunks over HTTP as they are generated. Lower time-to-first-audio than generate(). Text of any length is accepted: longer input is split at sentence boundaries and streamed as sequential requests. See Long Text.

const chunks = [];

for await (const chunk of tts.stream({
  text: 'Streaming is great for real-time playback!',
  voice: 'Ashley',
})) {
  chunks.push(chunk);
}

const audio = Buffer.concat(chunks);

Parameters are the same as generate(), plus an optional maxChunkChars that overrides the default 3,900-character chunk ceiling. See Long Text.

Yields: Uint8Array — audio chunks as they arrive.

generateWithTimestamps(options)

Same as generate() but also returns word- or character-level timing data. Useful for lip-sync, karaoke, and subtitle alignment.

const { audio, timestamps } = await tts.generateWithTimestamps({
  text: 'Timestamps are useful for lip sync.',
  voice: 'Ashley',
  timestampType: 'WORD',
});

// timestamps.wordAlignment.words → ['Timestamps', 'are', 'useful', ...]
// timestamps.wordAlignment.wordStartTimeSeconds → [0.0, 0.42, 0.61, ...]

Takes all the same parameters as generate(), plus:

Returns: { audio: Uint8Array, timestamps: TimestampInfo }

streamWithTimestamps(options)

Stream audio chunks, each paired with optional timestamp data. Text of any length is accepted: longer input is split at sentence boundaries and streamed as sequential requests. See Long Text.

for await (const chunk of tts.streamWithTimestamps({
  text: 'Streaming with timestamps!',
  voice: 'Ashley',
  timestampType: 'WORD',
})) {
  // chunk.audio: Uint8Array
  // chunk.timestamps: TimestampInfo | undefined
}

Takes all the same parameters as stream(), plus timestampType (required).

Yields: { audio: Uint8Array, timestamps?: TimestampInfo }

play(audio, options)

Play audio from a Uint8Array or file path. Encoding is auto-detected from magic bytes unless overridden.

const audio = await tts.generate({ text: 'Listen to this!', voice: 'Ashley' });
await tts.play(audio);

// Or play from a file
await tts.play('output.mp3');

Voice Management

listVoices(options)

List available voices, optionally filtered by language.

const voices = await tts.listVoices();

// Filter by language
const enVoices = await tts.listVoices({ lang: 'EN_US' });
const multiLang = await tts.listVoices({ lang: ['EN_US', 'ES_ES'] });

Returns: VoiceInfo[]

getVoice(voice)

Get details for a single voice. Works with custom voices in your workspace (cloned or designed voices).

const voice = await tts.getVoice('my-custom-voice-id');
// voice.voiceId, voice.displayName, voice.langCode, ...

Returns: VoiceInfo

cloneVoice(options)

Clone a voice from one or more audio recordings — as little as 3 seconds works, and longer samples (up to 30 seconds) improve similarity.

const result = await tts.cloneVoice({
  audioSamples: ['./recording.wav'],
  displayName: 'My Cloned Voice',
  lang: 'EN_US',
});

console.log(result.voice.voiceId); // use this ID in generate()

Returns: CloneVoiceResult — the cloned voice ID is at result.voice.voiceId.

designVoice(options)

Design a new voice from a text description — no audio recording needed.

const result = await tts.designVoice({
  designPrompt: 'A warm, friendly female voice with a slight British accent',
  previewText: 'Hello! Welcome to our application.',
  numberOfSamples: 3,
});

// Listen to previews, then publish the one you like
const chosenVoice = result.previewVoices[0];

Returns: DesignVoiceResult — preview voices at result.previewVoices.

publishVoice(options)

Publish a designed or cloned voice preview to your library so it can be used in generate() and stream().

const voice = await tts.publishVoice({
  voice: chosenVoice.voiceId,
  displayName: 'My Designed Voice',
});

Returns: VoiceInfo

migrateFromElevenLabs(options)

Migrate a voice from ElevenLabs to your Inworld workspace. Fetches the voice's audio samples directly from ElevenLabs and clones them into Inworld. No ElevenLabs SDK required.

const result = await tts.migrateFromElevenLabs({
  elevenLabsApiKey: process.env.ELEVEN_LABS_API_KEY,
  elevenLabsVoiceId: 'abc123',
});

console.log(`Migrated "${result.elevenLabsName}" → ${result.inworldVoiceId}`);

Returns: { elevenLabsVoiceId, elevenLabsName, inworldVoiceId }

Configuration

Create a client with InworldTTS() or the equivalent createClient():

import { InworldTTS, createClient } from '@inworld/tts';

const tts = InworldTTS();                       // reads INWORLD_API_KEY from env
const tts = InworldTTS({ apiKey: 'your_key' }); // or pass explicitly
const tts = createClient();                     // alias for InworldTTS()

Browser

The SDK works in browsers (Vite, webpack 5, Rollup, esbuild) with no extra configuration. Use JWT tokens instead of API keys to keep your credentials safe.

Authentication with JWT

In production, your backend generates short-lived JWT tokens and your frontend uses them to authenticate. See the session token guide and the sample Node.js JWT app for how to set up the server-side token endpoint.

import { InworldTTS } from '@inworld/tts';

async function fetchToken() {
  const res = await fetch('/api/tts-token');
  const { token } = await res.json();
  return token;
}

const tts = InworldTTS({
  token: await fetchToken(),
  onTokenExpiring: fetchToken, // called automatically ~5 min before expiry
});

The onTokenExpiring callback fires automatically when the current token is about to expire. It must return a fresh JWT string. The SDK uses a stale-while-revalidate strategy — requests continue with the current token while the refresh happens in the background.

Example: text-to-speech button

A minimal browser example — user clicks a button, the SDK generates audio and plays it:

<button id="speak">Speak</button>
<script type="module">
  import { InworldTTS } from '@inworld/tts';

  async function fetchToken() {
    const res = await fetch('/api/tts-token');
    const { token } = await res.json();
    return token;
  }

  const tts = InworldTTS({
    token: await fetchToken(),
    onTokenExpiring: fetchToken,
  });

  document.getElementById('speak').addEventListener('click', async () => {
    const audio = await tts.generate({
      text: 'Hello from the browser!',
      voice: 'Ashley',
      encoding: 'MP3', // recommended for cross-browser support
    });
    await tts.play(audio);
  });
</script>

Browser encoding compatibility

Not all audio encodings are playable in all browsers. Use MP3 for the widest compatibility.

For LINEAR16/PCM formats, use the Web Audio API directly with the Uint8Array returned by generate() instead of play().

Browser limitations

• outputFile — not supported, throws an error. Use the returned Uint8Array directly.
• play() with file paths — not supported, pass a Uint8Array instead.
• cloneVoice() with file paths — not supported, pass Uint8Array buffers for audio samples.

Development shortcut

For quick prototyping, you can use an API key directly in the browser by setting dangerouslyAllowBrowser:

// ⚠️ Development only — your API key will be visible in DevTools
const tts = InworldTTS({
  apiKey: 'your_key',
  dangerouslyAllowBrowser: true,
});

Long Text

generate() and generateWithTimestamps() automatically chunk text longer than 2,000 characters and send chunks in parallel (controlled by maxConcurrentRequests). The resulting audio is seamlessly concatenated, and timestamp offsets are merged correctly.

stream() and streamWithTimestamps() accept text of any length. The streaming endpoint takes up to 4,000 characters per request, so the SDK splits longer input at sentence boundaries into chunks of at most 3,900 characters and streams them as sequential requests. The audio arrives as one continuous sequence of chunks.

The 100-character margin is deliberate. The SDK splits on estimated audio-equivalent length, where a <break> tag counts as roughly 12 characters per second of silence and each CJK character counts as three. That estimate can differ from the raw character count the endpoint enforces.

To set your own ceiling, pass maxChunkChars. The SDK does not check it against the endpoint limit, so a value above 4,000 produces requests that the API rejects.

Error Handling

The SDK exports three error classes, all extending InworldTTSError:

import { InworldTTS, ApiError, NetworkError, MissingApiKeyError } from '@inworld/tts';

const tts = InworldTTS(); // reads INWORLD_API_KEY from env

try {
  const audio = await tts.generate({ text: 'Hello!', voice: 'Ashley' });
} catch (err) {
  if (err instanceof MissingApiKeyError) {
    // No API key or token provided
  } else if (err instanceof ApiError) {
    console.error(`HTTP ${err.code}: ${err.message}`, err.details);
  } else if (err instanceof NetworkError) {
    console.error(`Network error: ${err.message}`);
  } else {
    throw err;
  }
}

Next Steps