lyrravoice

Official TypeScript SDK for LyrraVoice — AI text-to-speech with voice cloning powered by XTTS v2.

• Zero dependencies (uses native fetch, Node.js 18+)
• Full TypeScript support with ESM + CJS dual build
• Covers all public API endpoints (TTS, voices, jobs, MCP keys)

Installation

npm install lyrravoice

Quick Start

import { LyrraVoice } from "lyrravoice";

const client = new LyrraVoice({
  apiKey: "lv_...",
  baseUrl: "https://your-server.com",
});

// Generate speech and save to file
const audio = await client.generate({
  text: "Bonjour, bienvenue sur LyrraVoice !",
  voice_id: "marc",
  language: "fr",
});
await audio.save("output.wav");

Usage

Synchronous TTS

const audio = await client.generate({
  text: "Hello world",
  voice_id: "sara",
  language: "en",
  format: "mp3",
  speed: 1.2,
});

// Save to file
await audio.save("hello.mp3");

// Or get raw buffer
const buffer = await audio.buffer();

Async TTS (Celery jobs)

// Submit job
const { job_id } = await client.generateAsync({
  text: "A very long text...",
  voice_id: "marc",
});

// Poll until complete
const job = await client.jobs.poll(job_id, {
  interval: 2000,
  timeout: 60000,
});

// Download result
if (job.download_url) {
  const audio = await client.jobs.download(job.download_url.split("/").pop()!);
  await audio.save("result.wav");
}

SSE Streaming

for await (const event of client.stream({ text: "Streaming audio..." })) {
  console.log(`Chunk ${event.chunk}/${event.total}`);
  // event.audio contains base64-encoded WAV data
  const chunk = Buffer.from(event.audio, "base64");
}

Voice Management

import fs from "node:fs";

// List voices
const voices = await client.voices.list();

// Clone a voice from audio
const result = await client.voices.clone({
  name: "my-voice",
  audio: fs.readFileSync("recording.wav"),
});

// Rename
await client.voices.rename("my-voice", "custom-narrator");

// Delete
await client.voices.delete("custom-narrator");

// Import a built-in preset
await client.voices.importPreset({ speaker_name: "Claribel Dervla" });

Audio Processing

import fs from "node:fs";

const cleaned = await client.audio.clean({
  file: fs.readFileSync("noisy.wav"),
});
await cleaned.save("clean.wav");

MCP API Keys

// Create a key (full key is returned only once)
const key = await client.mcp.createKey("ci-pipeline");
console.log(key.key); // "lv_..."

// List keys
const keys = await client.mcp.listKeys();

// Revoke
await client.mcp.revokeKey(key.id);

// Server info
const info = await client.mcp.info();

Health Check

const health = await client.health();
// { status: "ok", model: "xtts_v2", device: "cpu" }

Error Handling

import { APIError, TimeoutError } from "lyrravoice";

try {
  await client.generate({ text: "" });
} catch (err) {
  if (err instanceof APIError) {
    console.error(err.status); // 422
    console.error(err.detail); // "Text is required"
  }
  if (err instanceof TimeoutError) {
    console.error("Job took too long");
  }
}

Configuration

const client = new LyrraVoice({
  apiKey: "lv_...",             // MCP API key
  // OR
  token: "eyJ...",             // JWT bearer token
  baseUrl: "http://localhost:5050", // Server URL (default)
  timeout: 60000,              // Request timeout in ms (default: 30000)
});

License

MIT