wal-kokoro-tts

TypeScript/JavaScript client for Wal-KokoroTTS.

Prerequisites

You need the Kokoro TTS Service running locally:

# Windows one-liner install
irm https://raw.githubusercontent.com/user/kokoro-tts-service/main/install.ps1 | iex

# Start the service
kokoro-tts-server

Installation

npm install wal-kokoro-tts
# or
yarn add wal-kokoro-tts
# or
pnpm add wal-kokoro-tts

Usage

Basic Generation

import { KokoroTTS } from 'wal-kokoro-tts';

const tts = new KokoroTTS(); // defaults to http://127.0.0.1:8787

// Generate audio
const audioBuffer = await tts.generate("Hello world", {
  voice: "af_heart",
  speed: 1.0
});

// In Node.js, save to file
import fs from 'fs';
fs.writeFileSync('output.wav', Buffer.from(audioBuffer));

// In browser, play audio
const blob = new Blob([audioBuffer], { type: 'audio/wav' });
const audio = new Audio(URL.createObjectURL(blob));
audio.play();

Streaming (HTTP)

const tts = new KokoroTTS();

// Stream chunks as they are generated
for await (const chunk of tts.stream("Hello world")) {
  // chunk is Uint8Array
  // Process or play progressively
}

Streaming (WebSocket)

const tts = new KokoroTTS();

tts.streamWs("Hello world", { voice: "af_heart" }, {
  onChunk: (chunk: Uint8Array) => {
    // Play audio chunk
  },
  onDone: (stats) => {
    console.log(`Audio duration: ${stats.audio_duration}s`);
    console.log(`Generation time: ${stats.generation_time}s`);
  },
  onError: (error) => {
    console.error(error);
  }
});

Other Methods

const tts = new KokoroTTS();

// Check service health
const health = await tts.health();
// { status: "ready", model_loaded: true, ... }

// Pre-load model (avoid cold start)
await tts.wake();

// List available voices
const voices = await tts.voices();
// ["af_heart", "af_bella", "am_adam", ...]

API Reference

new KokoroTTS(baseUrl?: string)

Create a new client. Default URL is http://127.0.0.1:8787.

generate(text: string, options?: TTSOptions): Promise<ArrayBuffer>

Generate complete audio. Returns WAV as ArrayBuffer.

stream(text: string, options?: TTSOptions): AsyncGenerator<Uint8Array>

Stream audio chunks via HTTP.

streamWs(text: string, options?: TTSOptions, callbacks?: StreamCallbacks): WebSocket

Stream audio via WebSocket with callbacks.

TTSOptions

interface TTSOptions {
  voice?: string;   // default: "af_heart"
  speed?: number;   // default: 1.0
  lang?: string;    // default: "en-us"
}

License

MIT