lyrravoice 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# lyrravoice
+
+Official TypeScript SDK for [LyrraVoice](https://github.com/pc152/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
+
+```bash
+npm install lyrravoice
+```
+
+## Quick Start
+
+```ts
+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
+
+```ts
+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)
+
+```ts
+// 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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+import fs from "node:fs";
+
+const cleaned = await client.audio.clean({
+  file: fs.readFileSync("noisy.wav"),
+});
+await cleaned.save("clean.wav");
+```
+
+### MCP API Keys
+
+```ts
+// 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
+
+```ts
+const health = await client.health();
+// { status: "ok", model: "xtts_v2", device: "cpu" }
+```
+
+## Error Handling
+
+```ts
+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
+
+```ts
+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

package/dist/index.d.mts

@@ -0,0 +1,333 @@
+interface LyrraVoiceOptions {
+    /** API key (e.g. "lv_...") */
+    apiKey?: string;
+    /** Bearer token (JWT) — alternative to apiKey */
+    token?: string;
+    /** Base URL of the LyrraVoice server (default: "http://localhost:5050") */
+    baseUrl?: string;
+    /** Default timeout in ms (default: 30000) */
+    timeout?: number;
+}
+type Language = "fr" | "en" | "es" | "de" | "it" | "pt" | "pl" | "tr" | "ru" | "nl" | "cs" | "ar" | "zh-cn" | "ja" | "ko" | "hu";
+type AudioFormat = "wav" | "mp3";
+interface GenerateParams {
+    /** Text to synthesize (1-1000 chars) */
+    text: string;
+    /** Voice identifier */
+    voice_id?: string;
+    /** Language code (default: "fr") */
+    language?: Language;
+    /** Output format (default: "wav") */
+    format?: AudioFormat;
+    /** Speed multiplier 0.5-2.0 (default: 1.0) */
+    speed?: number;
+    /** Sampling temperature 0.1-1.0 (default: 0.65) */
+    temperature?: number;
+    /** Repetition penalty 1.0-10.0 (default: 2.0) */
+    repetition_penalty?: number;
+    /** Top-K sampling 1-100 (default: 50) */
+    top_k?: number;
+    /** Top-P sampling 0.1-1.0 (default: 0.8) */
+    top_p?: number;
+}
+interface AsyncJobResponse {
+    job_id: string;
+    status: "pending";
+    message: string;
+}
+interface StreamEvent {
+    chunk: number;
+    total: number;
+    audio: string;
+}
+interface StreamDoneEvent {
+    done: true;
+}
+interface StreamErrorEvent {
+    error: string;
+}
+interface TTSJob {
+    id: string;
+    text: string;
+    voice_id: string;
+    language: string;
+    format: string;
+    speed: number;
+    status: string;
+    file_size: number | null;
+    duration_seconds: number | null;
+    error: string | null;
+    created_at: string | null;
+    completed_at: string | null;
+    download_url?: string;
+}
+interface JobListResponse {
+    jobs: TTSJob[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface JobListParams {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+interface PollOptions {
+    /** Polling interval in ms (default: 1000) */
+    interval?: number;
+    /** Maximum wait time in ms (default: 300000 = 5min) */
+    timeout?: number;
+}
+interface Voice {
+    id: string;
+    name: string;
+    type: "embedding" | "reference" | "empty";
+    gender: "male" | "female" | null;
+    samples_count: number;
+    samples: string[];
+    is_official: boolean;
+    quality_rating: number | null;
+    preview_url?: string | null;
+}
+interface VoiceCloneParams {
+    /** Display name for the cloned voice */
+    name: string;
+    /** Audio file (WAV recommended, 6-30s) */
+    audio: Blob | Buffer | ReadableStream;
+    /** Filename hint (default: "audio.wav") */
+    filename?: string;
+}
+interface VoiceCloneResponse {
+    success: boolean;
+    voice_id: string;
+    message: string;
+}
+interface VoiceUploadResponse {
+    success: boolean;
+    voice_id: string;
+    filename: string;
+    size: number;
+    embedding_extracted?: boolean;
+    voice_type?: string;
+}
+interface VoiceRenameResponse {
+    success: boolean;
+    old_id: string;
+    new_id: string;
+}
+interface VoiceDeleteResponse {
+    success: boolean;
+    voice_id: string;
+}
+interface VoiceExtractEmbeddingResponse {
+    success: boolean;
+    message: string;
+    voice_type: string;
+}
+interface VoicePresetsResponse {
+    speakers: string[];
+    count: number;
+}
+interface VoicePresetImportParams {
+    speaker_name: string;
+    voice_id?: string;
+}
+interface VoicePresetImportResponse {
+    success: boolean;
+    message: string;
+    voice_id: string;
+    display_name: string;
+    gender: string | null;
+}
+interface AudioCleanParams {
+    /** Audio file to clean */
+    file: Blob | Buffer | ReadableStream;
+    /** Filename hint (default: "audio.wav") */
+    filename?: string;
+}
+interface McpKey {
+    id: string;
+    name: string;
+    key_prefix: string;
+    is_active: boolean;
+    last_used_at: string | null;
+    created_at: string;
+}
+interface McpKeyCreateResponse {
+    id: string;
+    name: string;
+    /** Full API key — returned only once */
+    key: string;
+    key_prefix: string;
+}
+interface McpInfo {
+    endpoint: string;
+    auth_enabled: boolean;
+    transport: string;
+    version: string;
+}
+interface HealthResponse {
+    status: "ok" | "loading";
+    model: string;
+    device: string;
+}
+
+/**
+ * Wraps a binary audio response with convenience methods.
+ */
+declare class AudioResponse {
+    private readonly _response;
+    private _buffer;
+    constructor(response: Response);
+    /** The raw Response object. */
+    get response(): Response;
+    /** Content-Type header value. */
+    get contentType(): string;
+    /** Read the full response as an ArrayBuffer (cached). */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Read the full response as a Node.js Buffer. */
+    buffer(): Promise<Buffer>;
+    /** Get a ReadableStream of the response body. Only works if buffer() hasn't been called yet. */
+    stream(): ReadableStream<Uint8Array> | null;
+    /** Save audio to a file. */
+    save(path: string): Promise<void>;
+    /** Return as a Blob (useful in non-Node environments). */
+    blob(): Promise<Blob>;
+}
+
+declare class Voices {
+    private readonly _client;
+    constructor(_client: LyrraVoiceClient);
+    /** List all voices accessible to the current user. */
+    list(): Promise<Voice[]>;
+    /** List voices with preview URLs. */
+    listWithPreviews(language?: string): Promise<Voice[]>;
+    /** Get a test/preview audio for a voice. */
+    test(voiceId: string, language?: string): Promise<AudioResponse>;
+    /** Clone a voice from an audio sample. */
+    clone(params: VoiceCloneParams): Promise<VoiceCloneResponse>;
+    /** Upload a file (.wav, .mp3, .pth) to an existing voice. */
+    upload(voiceId: string, file: Blob | Buffer, filename?: string): Promise<VoiceUploadResponse>;
+    /** Rename a voice. */
+    rename(voiceId: string, newName: string): Promise<VoiceRenameResponse>;
+    /** Delete a voice. */
+    delete(voiceId: string): Promise<VoiceDeleteResponse>;
+    /** Extract .pth embedding from voice audio references. */
+    extractEmbedding(voiceId: string, force?: boolean): Promise<VoiceExtractEmbeddingResponse>;
+    /** List built-in XTTS v2 speaker presets. */
+    presets(): Promise<VoicePresetsResponse>;
+    /** Import a built-in preset as a user voice. */
+    importPreset(params: VoicePresetImportParams): Promise<VoicePresetImportResponse>;
+}
+
+declare class Jobs {
+    private readonly _client;
+    constructor(_client: LyrraVoiceClient);
+    /** List TTS jobs. */
+    list(params?: JobListParams): Promise<JobListResponse>;
+    /** Get a single job by ID. */
+    get(jobId: string): Promise<TTSJob>;
+    /**
+     * Poll a job until it reaches a terminal state (completed / failed).
+     * Returns the final job object.
+     */
+    poll(jobId: string, options?: PollOptions): Promise<TTSJob>;
+    /** Download the audio output of a completed job. */
+    download(fileId: string): Promise<AudioResponse>;
+}
+
+declare class AudioProcessing {
+    private readonly _client;
+    constructor(_client: LyrraVoiceClient);
+    /**
+     * Clean an audio file (noise reduction + normalization).
+     * Returns the cleaned audio as an AudioResponse.
+     */
+    clean(params: AudioCleanParams): Promise<AudioResponse>;
+}
+
+declare class Mcp {
+    private readonly _client;
+    constructor(_client: LyrraVoiceClient);
+    /** List all MCP API keys for the current user. */
+    listKeys(): Promise<McpKey[]>;
+    /**
+     * Create a new MCP API key.
+     * The full key is returned only once — store it securely.
+     */
+    createKey(name: string): Promise<McpKeyCreateResponse>;
+    /** Revoke an MCP API key. */
+    revokeKey(keyId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Get MCP server info (endpoint, version, transport). */
+    info(): Promise<McpInfo>;
+}
+
+/** Internal interface — exposed for resource classes via `LyrraVoiceClient`. */
+interface LyrraVoiceClient {
+    _get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    _getRaw(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<AudioResponse>;
+    _post<T>(path: string, body?: unknown, query?: Record<string, string | undefined>): Promise<T>;
+    _postRaw(path: string, body?: unknown): Promise<AudioResponse>;
+    _postForm<T>(path: string, form: FormData): Promise<T>;
+    _postFormRaw(path: string, form: FormData): Promise<AudioResponse>;
+    _putForm<T>(path: string, form: FormData): Promise<T>;
+    _delete<T>(path: string): Promise<T>;
+}
+declare class LyrraVoice implements LyrraVoiceClient {
+    private readonly _baseUrl;
+    private readonly _apiKey;
+    private readonly _token;
+    private readonly _timeout;
+    /** Voice management (list, clone, rename, delete, presets...) */
+    readonly voices: Voices;
+    /** Async TTS job management (list, get, poll, download) */
+    readonly jobs: Jobs;
+    /** Audio processing (clean/denoise) */
+    readonly audio: AudioProcessing;
+    /** MCP API key management */
+    readonly mcp: Mcp;
+    constructor(options?: LyrraVoiceOptions);
+    /** Synchronous TTS — returns audio. */
+    generate(params: GenerateParams): Promise<AudioResponse>;
+    /** Async TTS — submits a Celery job, returns job_id for polling. */
+    generateAsync(params: GenerateParams): Promise<AsyncJobResponse>;
+    /**
+     * SSE streaming TTS — yields audio chunks as they are generated.
+     *
+     * ```ts
+     * for await (const event of client.stream({ text: "Hello" })) {
+     *   // event.audio is base64-encoded WAV chunk
+     * }
+     * ```
+     */
+    stream(params: GenerateParams): AsyncGenerator<StreamEvent, void, undefined>;
+    /** Health check. */
+    health(): Promise<HealthResponse>;
+    _get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    _getRaw(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<AudioResponse>;
+    _post<T>(path: string, body?: unknown, query?: Record<string, string | undefined>): Promise<T>;
+    _postRaw(path: string, body?: unknown): Promise<AudioResponse>;
+    _postForm<T>(path: string, form: FormData): Promise<T>;
+    _postFormRaw(path: string, form: FormData): Promise<AudioResponse>;
+    _putForm<T>(path: string, form: FormData): Promise<T>;
+    _delete<T>(path: string): Promise<T>;
+    private _url;
+    private _fetch;
+}
+
+declare class LyrraVoiceError extends Error {
+    constructor(message: string);
+}
+declare class APIError extends LyrraVoiceError {
+    readonly status: number;
+    readonly detail: string | undefined;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+declare class TimeoutError extends LyrraVoiceError {
+    constructor(message?: string);
+}
+
+export { APIError, type AsyncJobResponse, type AudioCleanParams, type AudioFormat, AudioProcessing, AudioResponse, type GenerateParams, type HealthResponse, type JobListParams, type JobListResponse, Jobs, type Language, LyrraVoice, type LyrraVoiceClient, LyrraVoiceError, type LyrraVoiceOptions, Mcp, type McpInfo, type McpKey, type McpKeyCreateResponse, type PollOptions, type StreamDoneEvent, type StreamErrorEvent, type StreamEvent, type TTSJob, TimeoutError, type Voice, type VoiceCloneParams, type VoiceCloneResponse, type VoiceDeleteResponse, type VoiceExtractEmbeddingResponse, type VoicePresetImportParams, type VoicePresetImportResponse, type VoicePresetsResponse, type VoiceRenameResponse, type VoiceUploadResponse, Voices };