kugelaudio 0.8.0 → 0.9.0

package/dist/livekit/index.d.mts

@@ -0,0 +1,222 @@
+import { tts, TimedString, APIConnectOptions } from '@livekit/agents';
+
+/**
+ * Models, constants, and language validation for the KugelAudio LiveKit
+ * Agents TTS plugin.
+ *
+ * This module has NO dependency on `@livekit/agents`, so it can be imported
+ * and unit-tested without the (heavy, native) LiveKit runtime.
+ */
+/**
+ * Available TTS models. Legacy ids (`kugel-2.5`, `kugel-2-turbo`,
+ * `kugel-1-turbo`, `kugel-1`) remain accepted for back-compat — server-side
+ * they all alias to `kugel-3` — but new code should use `'kugel-3'`.
+ */
+type TTSModels = 'kugel-3' | 'kugel-2.5' | 'kugel-2-turbo' | 'kugel-1-turbo' | 'kugel-1';
+/** Default model (matches the public API default; server-side `is_default=kugel-3`). */
+declare const DEFAULT_MODEL: TTSModels;
+/**
+ * Supported output sample rates. The model generates at 24 kHz natively;
+ * other rates use server-side resampling.
+ */
+declare const SUPPORTED_SAMPLE_RATES: readonly [24000, 22050, 16000, 8000];
+/** Default output sample rate. */
+declare const DEFAULT_SAMPLE_RATE = 24000;
+/** Default voice id (`null` means use the server default voice). */
+declare const DEFAULT_VOICE_ID: number | null;
+/** Default classifier-free guidance scale. */
+declare const DEFAULT_CFG_SCALE = 2;
+/** Default maximum number of tokens to generate. */
+declare const DEFAULT_MAX_NEW_TOKENS = 2048;
+/**
+ * ISO 639-1 language codes accepted by the API for text normalization.
+ * Mirrors `kugelaudio.livekit.tts.SUPPORTED_LANGUAGES` in the Python SDK.
+ */
+declare const SUPPORTED_LANGUAGES: ReadonlySet<string>;
+/**
+ * Validate that `language` is an ISO 639-1 code supported by the API.
+ *
+ * @param language - The language code, or `undefined`/`null` to leave unset.
+ * @returns The validated code, or `undefined` when none was supplied.
+ * @throws {Error} If `language` is not a supported ISO 639-1 code. A common
+ *   mistake is passing a BCP 47 locale tag such as `'de-DE'` instead of `'de'`.
+ */
+declare function validateLanguage(language: string | null | undefined): string | undefined;
+
+/**
+ * Pure wire-protocol helpers for the KugelAudio `/ws/tts/multi` endpoint used
+ * by the LiveKit plugin.
+ *
+ * Kept free of any `@livekit/agents` import so the message-shaping logic can be
+ * unit-tested without the LiveKit runtime. Mirrors the send loop of
+ * `kugelaudio.livekit.tts._Connection` in the Python SDK.
+ */
+/** Generation parameters carried on the first message of each context. */
+interface WireOptions {
+    model: string;
+    voiceId: number | null;
+    sampleRate: number;
+    cfgScale: number;
+    maxNewTokens: number;
+    wordTimestamps: boolean;
+    normalize: boolean;
+    language?: string;
+}
+
+/**
+ * KugelAudio TTS plugin for the LiveKit Agents (Node.js) framework.
+ *
+ * A TypeScript translation of `kugelaudio.livekit.tts` (Python SDK). Uses a
+ * single persistent WebSocket to `/ws/tts/multi` with per-call context IDs; the
+ * shared connection multiplexes every context. On barge-in (the framework
+ * aborting a stream) the context is closed with `immediate=true` and any late
+ * server frames for it are silently discarded. A context's waiter resolves only
+ * on the server's `context_closed` frame — sent after every audio frame has
+ * been drained — so the audio tail is never clipped.
+ */
+
+/** Options accepted by the {@link TTS} constructor. */
+interface TTSOptions {
+    /**
+     * KugelAudio API key. Falls back to the `KUGELAUDIO_API_KEY` environment
+     * variable. Prefix with `"eu-"` to select the direct EU endpoint; the prefix
+     * is stripped before auth.
+     */
+    apiKey?: string;
+    /** TTS model. Defaults to `'kugel-3'`. */
+    model?: TTSModels | string;
+    /** Voice id. `null`/omitted uses the server default voice. */
+    voiceId?: number | null;
+    /** Output sample rate in Hz (24000, 22050, 16000, 8000). Defaults to 24000. */
+    sampleRate?: number;
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5]. Defaults to 2.0. */
+    cfgScale?: number;
+    /** Maximum tokens to generate. Defaults to 2048. */
+    maxNewTokens?: number;
+    /** Apply loudness normalization to the output audio. Defaults to true. */
+    normalize?: boolean;
+    /**
+     * Request per-chunk word-level timestamps for aligned transcript / barge-in.
+     * Defaults to false. Enabling advertises the `alignedTranscript` capability.
+     */
+    wordTimestamps?: boolean;
+    /**
+     * ISO 639-1 language code for text normalization (e.g. `'de'`). When set,
+     * skips server-side auto-detection, saving ~60-150ms per request.
+     */
+    language?: string;
+    /** API base URL. Overrides the default geo-routed endpoint. */
+    baseURL?: string;
+}
+interface ResolvedTTSOptions extends WireOptions {
+    apiKey: string;
+    baseURL: string;
+}
+/** A resolvable/rejectable promise handle. */
+interface Deferred {
+    promise: Promise<void>;
+    resolve: () => void;
+    reject: (err: Error) => void;
+    settled: boolean;
+}
+/**
+ * Turns raw PCM byte chunks into LiveKit {@link AudioFrame}s, deferring the
+ * last produced frame so it can be flagged `final` once the segment ends. Word
+ * timings are attached to the next emitted frame. Mirrors the frame-emission
+ * behaviour of the Python plugin's `AudioEmitter`.
+ */
+declare class AudioSink {
+    #private;
+    private readonly put;
+    private readonly requestId;
+    private readonly segmentId;
+    constructor(sampleRate: number, put: (audio: tts.SynthesizedAudio) => void, requestId: string, segmentId: string);
+    pushAudio(bytes: Buffer): void;
+    pushTimed(words: TimedString[]): void;
+    /** Flush any buffered audio and emit the terminal (`final`) frame. */
+    end(): void;
+}
+interface ContextData {
+    sink: AudioSink;
+    waiter: Deferred;
+    isStreaming: boolean;
+    lastActivityAt: number;
+}
+/**
+ * Single persistent WebSocket to `/ws/tts/multi` with background send/recv
+ * loops. Each synthesis registers a unique `context_id`; the recv loop routes
+ * server messages by id and silently drops messages for unknown/closed
+ * contexts, which is what makes barge-in safe.
+ */
+declare class Connection {
+    #private;
+    constructor(opts: ResolvedTTSOptions);
+    get isCurrent(): boolean;
+    get closed(): boolean;
+    markNonCurrent(): void;
+    connect(timeoutMs?: number): Promise<void>;
+    registerContext(contextId: string, sink: AudioSink, waiter: Deferred, isStreaming: boolean): ContextData | null;
+    sendText(contextId: string, text: string, flush: boolean): void;
+    closeContext(contextId: string, immediate: boolean): void;
+    cleanupContext(contextId: string): void;
+    close(): Promise<void>;
+}
+/**
+ * KugelAudio Text-to-Speech plugin for LiveKit Agents.
+ *
+ * @example
+ * ```ts
+ * import { TTS } from 'kugelaudio/livekit';
+ * import { AgentSession } from '@livekit/agents';
+ *
+ * const session = new AgentSession({
+ *   tts: new TTS({ voiceId: 1071, model: 'kugel-3', language: 'en' }),
+ *   // ...stt, llm, vad
+ * });
+ * ```
+ */
+declare class TTS extends tts.TTS {
+    #private;
+    label: string;
+    constructor(opts?: TTSOptions);
+    get model(): string;
+    get provider(): string;
+    /** Get or create the persistent `/ws/tts/multi` connection. */
+    currentConnection(timeoutMs?: number): Promise<Connection>;
+    /**
+     * Eagerly establish the WebSocket connection to remove handshake latency
+     * from the first synthesis. Errors are logged and retried on first use.
+     */
+    prewarm(): void;
+    /**
+     * Update TTS options at runtime. Changing any option marks the current
+     * connection non-current so the next synthesis opens a fresh one.
+     */
+    updateOptions(opts: Partial<Omit<TTSOptions, 'apiKey' | 'baseURL'>>): void;
+    synthesize(text: string, connOptions?: APIConnectOptions, abortSignal?: AbortSignal): ChunkedStream;
+    stream(options?: {
+        connOptions?: APIConnectOptions;
+    }): SynthesizeStream;
+    close(): Promise<void>;
+}
+/** Non-streaming (one-shot) synthesis over the shared `/ws/tts/multi` connection. */
+declare class ChunkedStream extends tts.ChunkedStream {
+    #private;
+    label: string;
+    constructor(ttsInstance: TTS, text: string, opts: ResolvedTTSOptions, connOptions?: APIConnectOptions, abortSignal?: AbortSignal);
+    protected run(): Promise<void>;
+}
+/**
+ * Streaming synthesis: text tokens are pushed via the LiveKit input channel and
+ * forwarded to the shared connection; audio is routed back by `context_id`.
+ */
+declare class SynthesizeStream extends tts.SynthesizeStream {
+    #private;
+    label: string;
+    constructor(ttsInstance: TTS, opts: ResolvedTTSOptions, connOptions?: APIConnectOptions);
+    /** The server-side context id of the current (latest) run attempt. */
+    get contextId(): string | undefined;
+    protected run(): Promise<void>;
+}
+
+export { ChunkedStream, DEFAULT_CFG_SCALE, DEFAULT_MAX_NEW_TOKENS, DEFAULT_MODEL, DEFAULT_SAMPLE_RATE, DEFAULT_VOICE_ID, SUPPORTED_LANGUAGES, SUPPORTED_SAMPLE_RATES, SynthesizeStream, TTS, type TTSModels, type TTSOptions, validateLanguage };

package/dist/livekit/index.d.ts

@@ -0,0 +1,222 @@
+import { tts, TimedString, APIConnectOptions } from '@livekit/agents';
+
+/**
+ * Models, constants, and language validation for the KugelAudio LiveKit
+ * Agents TTS plugin.
+ *
+ * This module has NO dependency on `@livekit/agents`, so it can be imported
+ * and unit-tested without the (heavy, native) LiveKit runtime.
+ */
+/**
+ * Available TTS models. Legacy ids (`kugel-2.5`, `kugel-2-turbo`,
+ * `kugel-1-turbo`, `kugel-1`) remain accepted for back-compat — server-side
+ * they all alias to `kugel-3` — but new code should use `'kugel-3'`.
+ */
+type TTSModels = 'kugel-3' | 'kugel-2.5' | 'kugel-2-turbo' | 'kugel-1-turbo' | 'kugel-1';
+/** Default model (matches the public API default; server-side `is_default=kugel-3`). */
+declare const DEFAULT_MODEL: TTSModels;
+/**
+ * Supported output sample rates. The model generates at 24 kHz natively;
+ * other rates use server-side resampling.
+ */
+declare const SUPPORTED_SAMPLE_RATES: readonly [24000, 22050, 16000, 8000];
+/** Default output sample rate. */
+declare const DEFAULT_SAMPLE_RATE = 24000;
+/** Default voice id (`null` means use the server default voice). */
+declare const DEFAULT_VOICE_ID: number | null;
+/** Default classifier-free guidance scale. */
+declare const DEFAULT_CFG_SCALE = 2;
+/** Default maximum number of tokens to generate. */
+declare const DEFAULT_MAX_NEW_TOKENS = 2048;
+/**
+ * ISO 639-1 language codes accepted by the API for text normalization.
+ * Mirrors `kugelaudio.livekit.tts.SUPPORTED_LANGUAGES` in the Python SDK.
+ */
+declare const SUPPORTED_LANGUAGES: ReadonlySet<string>;
+/**
+ * Validate that `language` is an ISO 639-1 code supported by the API.
+ *
+ * @param language - The language code, or `undefined`/`null` to leave unset.
+ * @returns The validated code, or `undefined` when none was supplied.
+ * @throws {Error} If `language` is not a supported ISO 639-1 code. A common
+ *   mistake is passing a BCP 47 locale tag such as `'de-DE'` instead of `'de'`.
+ */
+declare function validateLanguage(language: string | null | undefined): string | undefined;
+
+/**
+ * Pure wire-protocol helpers for the KugelAudio `/ws/tts/multi` endpoint used
+ * by the LiveKit plugin.
+ *
+ * Kept free of any `@livekit/agents` import so the message-shaping logic can be
+ * unit-tested without the LiveKit runtime. Mirrors the send loop of
+ * `kugelaudio.livekit.tts._Connection` in the Python SDK.
+ */
+/** Generation parameters carried on the first message of each context. */
+interface WireOptions {
+    model: string;
+    voiceId: number | null;
+    sampleRate: number;
+    cfgScale: number;
+    maxNewTokens: number;
+    wordTimestamps: boolean;
+    normalize: boolean;
+    language?: string;
+}
+
+/**
+ * KugelAudio TTS plugin for the LiveKit Agents (Node.js) framework.
+ *
+ * A TypeScript translation of `kugelaudio.livekit.tts` (Python SDK). Uses a
+ * single persistent WebSocket to `/ws/tts/multi` with per-call context IDs; the
+ * shared connection multiplexes every context. On barge-in (the framework
+ * aborting a stream) the context is closed with `immediate=true` and any late
+ * server frames for it are silently discarded. A context's waiter resolves only
+ * on the server's `context_closed` frame — sent after every audio frame has
+ * been drained — so the audio tail is never clipped.
+ */
+
+/** Options accepted by the {@link TTS} constructor. */
+interface TTSOptions {
+    /**
+     * KugelAudio API key. Falls back to the `KUGELAUDIO_API_KEY` environment
+     * variable. Prefix with `"eu-"` to select the direct EU endpoint; the prefix
+     * is stripped before auth.
+     */
+    apiKey?: string;
+    /** TTS model. Defaults to `'kugel-3'`. */
+    model?: TTSModels | string;
+    /** Voice id. `null`/omitted uses the server default voice. */
+    voiceId?: number | null;
+    /** Output sample rate in Hz (24000, 22050, 16000, 8000). Defaults to 24000. */
+    sampleRate?: number;
+    /** Classifier-free guidance scale. Clamped to [1.2, 2.5]. Defaults to 2.0. */
+    cfgScale?: number;
+    /** Maximum tokens to generate. Defaults to 2048. */
+    maxNewTokens?: number;
+    /** Apply loudness normalization to the output audio. Defaults to true. */
+    normalize?: boolean;
+    /**
+     * Request per-chunk word-level timestamps for aligned transcript / barge-in.
+     * Defaults to false. Enabling advertises the `alignedTranscript` capability.
+     */
+    wordTimestamps?: boolean;
+    /**
+     * ISO 639-1 language code for text normalization (e.g. `'de'`). When set,
+     * skips server-side auto-detection, saving ~60-150ms per request.
+     */
+    language?: string;
+    /** API base URL. Overrides the default geo-routed endpoint. */
+    baseURL?: string;
+}
+interface ResolvedTTSOptions extends WireOptions {
+    apiKey: string;
+    baseURL: string;
+}
+/** A resolvable/rejectable promise handle. */
+interface Deferred {
+    promise: Promise<void>;
+    resolve: () => void;
+    reject: (err: Error) => void;
+    settled: boolean;
+}
+/**
+ * Turns raw PCM byte chunks into LiveKit {@link AudioFrame}s, deferring the
+ * last produced frame so it can be flagged `final` once the segment ends. Word
+ * timings are attached to the next emitted frame. Mirrors the frame-emission
+ * behaviour of the Python plugin's `AudioEmitter`.
+ */
+declare class AudioSink {
+    #private;
+    private readonly put;
+    private readonly requestId;
+    private readonly segmentId;
+    constructor(sampleRate: number, put: (audio: tts.SynthesizedAudio) => void, requestId: string, segmentId: string);
+    pushAudio(bytes: Buffer): void;
+    pushTimed(words: TimedString[]): void;
+    /** Flush any buffered audio and emit the terminal (`final`) frame. */
+    end(): void;
+}
+interface ContextData {
+    sink: AudioSink;
+    waiter: Deferred;
+    isStreaming: boolean;
+    lastActivityAt: number;
+}
+/**
+ * Single persistent WebSocket to `/ws/tts/multi` with background send/recv
+ * loops. Each synthesis registers a unique `context_id`; the recv loop routes
+ * server messages by id and silently drops messages for unknown/closed
+ * contexts, which is what makes barge-in safe.
+ */
+declare class Connection {
+    #private;
+    constructor(opts: ResolvedTTSOptions);
+    get isCurrent(): boolean;
+    get closed(): boolean;
+    markNonCurrent(): void;
+    connect(timeoutMs?: number): Promise<void>;
+    registerContext(contextId: string, sink: AudioSink, waiter: Deferred, isStreaming: boolean): ContextData | null;
+    sendText(contextId: string, text: string, flush: boolean): void;
+    closeContext(contextId: string, immediate: boolean): void;
+    cleanupContext(contextId: string): void;
+    close(): Promise<void>;
+}
+/**
+ * KugelAudio Text-to-Speech plugin for LiveKit Agents.
+ *
+ * @example
+ * ```ts
+ * import { TTS } from 'kugelaudio/livekit';
+ * import { AgentSession } from '@livekit/agents';
+ *
+ * const session = new AgentSession({
+ *   tts: new TTS({ voiceId: 1071, model: 'kugel-3', language: 'en' }),
+ *   // ...stt, llm, vad
+ * });
+ * ```
+ */
+declare class TTS extends tts.TTS {
+    #private;
+    label: string;
+    constructor(opts?: TTSOptions);
+    get model(): string;
+    get provider(): string;
+    /** Get or create the persistent `/ws/tts/multi` connection. */
+    currentConnection(timeoutMs?: number): Promise<Connection>;
+    /**
+     * Eagerly establish the WebSocket connection to remove handshake latency
+     * from the first synthesis. Errors are logged and retried on first use.
+     */
+    prewarm(): void;
+    /**
+     * Update TTS options at runtime. Changing any option marks the current
+     * connection non-current so the next synthesis opens a fresh one.
+     */
+    updateOptions(opts: Partial<Omit<TTSOptions, 'apiKey' | 'baseURL'>>): void;
+    synthesize(text: string, connOptions?: APIConnectOptions, abortSignal?: AbortSignal): ChunkedStream;
+    stream(options?: {
+        connOptions?: APIConnectOptions;
+    }): SynthesizeStream;
+    close(): Promise<void>;
+}
+/** Non-streaming (one-shot) synthesis over the shared `/ws/tts/multi` connection. */
+declare class ChunkedStream extends tts.ChunkedStream {
+    #private;
+    label: string;
+    constructor(ttsInstance: TTS, text: string, opts: ResolvedTTSOptions, connOptions?: APIConnectOptions, abortSignal?: AbortSignal);
+    protected run(): Promise<void>;
+}
+/**
+ * Streaming synthesis: text tokens are pushed via the LiveKit input channel and
+ * forwarded to the shared connection; audio is routed back by `context_id`.
+ */
+declare class SynthesizeStream extends tts.SynthesizeStream {
+    #private;
+    label: string;
+    constructor(ttsInstance: TTS, opts: ResolvedTTSOptions, connOptions?: APIConnectOptions);
+    /** The server-side context id of the current (latest) run attempt. */
+    get contextId(): string | undefined;
+    protected run(): Promise<void>;
+}
+
+export { ChunkedStream, DEFAULT_CFG_SCALE, DEFAULT_MAX_NEW_TOKENS, DEFAULT_MODEL, DEFAULT_SAMPLE_RATE, DEFAULT_VOICE_ID, SUPPORTED_LANGUAGES, SUPPORTED_SAMPLE_RATES, SynthesizeStream, TTS, type TTSModels, type TTSOptions, validateLanguage };