Text-to-Speech

TTSClient opens a WebSocket to /ws/tts, sends your text, and hands you audio chunks as they are generated. In JavaScript, synthesize() returns a promise that resolves when the server has sent all the audio and rejects with a LokutorError if the server returns an error or the stream stalls.

Basic usage

Node.js (save to file)
Browser
Python

Node.js 22 or later.

import { TTSClient, VoiceStyle, Language } from '@lokutor/sdk';
import fs from 'node:fs';

const client = new TTSClient({ apiKey: process.env.LOKUTOR_API_KEY! });
const chunks: Buffer[] = [];

await client.synthesize({
  text: 'Hello, this is Lokutor speaking.',
  voice: VoiceStyle.F1,
  language: Language.ENGLISH,
  onAudio: (data) => chunks.push(Buffer.from(data)),
  onTTFB: (ms) => console.log(`first audio after ${Math.round(ms)} ms`),
});

fs.writeFileSync('output.raw', Buffer.concat(chunks));
// Convert: ffmpeg -f s16le -ar 44100 -ac 1 -i output.raw output.wav

Pass a short-lived ticket from your backend, never your API key (Secure browser setup).

import { TTSClient, VoiceStyle, Language } from '@lokutor/sdk';

const { ticket } = await fetch('/api/lokutor-ticket', { method: 'POST' }).then((r) => r.json());
const client = new TTSClient({ apiKey: ticket });

const audioCtx = new AudioContext(); // inside a click handler
let nextTime = audioCtx.currentTime;

await client.synthesize({
  text: 'Hello, this is Lokutor speaking.',
  voice: VoiceStyle.F1,
  language: Language.ENGLISH,
  onAudio: (pcm16) => {
    const int16 = new Int16Array(pcm16.buffer, pcm16.byteOffset, pcm16.byteLength / 2);
    const float32 = new Float32Array(int16.length);
    for (let i = 0; i < int16.length; i++) float32[i] = int16[i] / 32768;

    const buffer = audioCtx.createBuffer(1, float32.length, 44100);
    buffer.getChannelData(0).set(float32);

    const source = audioCtx.createBufferSource();
    source.buffer = buffer;
    source.connect(audioCtx.destination);

    const start = Math.max(audioCtx.currentTime, nextTime);
    source.start(start);
    nextTime = start + buffer.duration;
  },
});

play=True needs pip install "lokutor[audio]"; with play=False, collect the audio in on_audio.

import os
from lokutor import TTSClient, VoiceStyle, Language

client = TTSClient(api_key=os.environ["LOKUTOR_API_KEY"])

client.synthesize(
    text="Hello, this is Lokutor speaking.",
    voice=VoiceStyle.F1,
    language=Language.ENGLISH,
    play=True,
    block=True,
)

Options

Option	Type	Default	Description
`text`	`string`	required	Text to synthesize. At most 5,000 characters.
`voice`	`VoiceStyle` or a string id	`F1`	Voice slot or `clone_…` id. The speaker depends on `language` (Voices).
`language`	`Language`	`ENGLISH`	Language. (Python also accepts a plain string such as `"es"`.)
`speed`	`number`	not sent	Sent only if you set it. Accepted for compatibility; no effect on versa-2.0.
`steps`	`number`	not sent	Sent only if you set it. Accepted for compatibility; no effect on versa-2.0.
`visemes`	`boolean`	`false`	Lip-sync data. Not available on the current model (Visemes).
`onAudio`	`(Uint8Array) => void`	—	Called with each audio chunk
`onTTFB`	`(ms: number) => void`	—	Time from sending the request to the first audio
`onError`	`(error) => void`	—	Called with the same error the promise rejects with

The Python client sends speed and steps on every request (defaults 1.05 and 24); they have no effect.

Completion and errors (JavaScript)

The promise resolves when the server signals the end of the stream (EOS).
It rejects with a LokutorError carrying the server’s code (for example validation.invalid_voice or tts.synthesis_failed) when the server sends an error frame.
It rejects with internal.timeout when no audio arrives within 30 seconds, or no further chunk within 15 seconds.
It rejects if the socket closes before the end of the stream, unless audio had arrived and the close was clean.

try {
  await client.synthesize({ text, voice: VoiceStyle.F1, language: Language.ENGLISH, onAudio });
} catch (err) {
  console.error(err.code, err.message, err.retryable);
}

Each call opens its own WebSocket. To send many short requests over one connection, use the WebSocket API directly.

Audio format

Property	Value
Format	Signed 16-bit PCM, little-endian
Sample rate	44.1 kHz
Channels	1 (mono)

Get Started

SDK

API Reference

Resources

Basic usage

Options

Completion and errors (JavaScript)

Audio format

​Basic usage

​Options

​Completion and errors (JavaScript)

​Audio format

Basic usage

Options

Completion and errors (JavaScript)

Audio format