@sudocode-ai/local-server 0.1.16 → 0.1.18-dev.0

package/dist/services/tts-sidecar-manager.d.ts

@@ -0,0 +1,276 @@
+/**
+ * TTS Sidecar Manager Service
+ *
+ * Manages the lifecycle of the Python Kokoro TTS sidecar process.
+ * Handles installation, startup, health checks, and graceful shutdown.
+ *
+ * The sidecar communicates via JSON-lines protocol over stdin/stdout:
+ * - stdin: {"id": "req-123", "type": "generate", "text": "Hello", "voice": "af_heart", "speed": 1.0}
+ * - stdout: {"id": "req-123", "type": "audio", "chunk": "<base64>", "index": 0}
+ *
+ * Audio format: mono, 24kHz, float32 PCM (base64 encoded)
+ */
+import { EventEmitter } from "events";
+/**
+ * Sidecar state machine states
+ */
+export type SidecarState = "idle" | "installing" | "starting" | "ready" | "error" | "shutdown";
+/**
+ * Request to generate TTS audio
+ */
+export interface TTSGenerateRequest {
+    /** Unique request ID for correlating responses */
+    id: string;
+    /** Text to synthesize */
+    text: string;
+    /** Voice identifier (e.g., "af_heart", "af_sarah") */
+    voice?: string;
+    /** Speech speed multiplier (default: 1.0) */
+    speed?: number;
+}
+/**
+ * Base response from sidecar
+ */
+interface SidecarResponseBase {
+    id: string;
+    type: string;
+}
+/**
+ * Ready signal from sidecar
+ */
+export interface SidecarReadyResponse extends SidecarResponseBase {
+    type: "ready";
+}
+/**
+ * Audio chunk response
+ */
+export interface SidecarAudioResponse extends SidecarResponseBase {
+    type: "audio";
+    /** Base64-encoded PCM audio (mono, 24kHz, float32) */
+    chunk: string;
+    /** Zero-based chunk index */
+    index: number;
+}
+/**
+ * Generation complete response
+ */
+export interface SidecarDoneResponse extends SidecarResponseBase {
+    type: "done";
+    /** Total number of chunks sent */
+    total_chunks: number;
+}
+/**
+ * Error response
+ */
+export interface SidecarErrorResponse extends SidecarResponseBase {
+    type: "error";
+    /** Error message */
+    error: string;
+    /** Whether the error is recoverable */
+    recoverable: boolean;
+}
+/**
+ * Pong response (health check)
+ */
+export interface SidecarPongResponse extends SidecarResponseBase {
+    type: "pong";
+}
+/**
+ * Union of all sidecar response types
+ */
+export type SidecarResponse = SidecarReadyResponse | SidecarAudioResponse | SidecarDoneResponse | SidecarErrorResponse | SidecarPongResponse;
+/**
+ * Events emitted by the sidecar manager
+ */
+export interface TTSSidecarManagerEvents {
+    state: (state: SidecarState) => void;
+    response: (response: SidecarResponse) => void;
+    audio: (response: SidecarAudioResponse) => void;
+    done: (response: SidecarDoneResponse) => void;
+    error: (response: SidecarErrorResponse) => void;
+}
+/**
+ * Installation status result
+ */
+export interface InstallationStatus {
+    installed: boolean;
+    venvPath?: string;
+    pythonPath?: string;
+    error?: string;
+}
+/**
+ * ONNX runtime variant based on platform
+ */
+type OnnxRuntime = "onnxruntime" | "onnxruntime-silicon" | "onnxruntime-gpu" | "onnxruntime-directml";
+/**
+ * Manages the Python Kokoro TTS sidecar process lifecycle.
+ *
+ * Features:
+ * - Lazy initialization (only installs/starts when first TTS request arrives)
+ * - Platform-specific ONNX runtime detection
+ * - Health monitoring with auto-restart on crash
+ * - Exponential backoff for restart attempts
+ * - Graceful shutdown with timeout
+ *
+ * @example
+ * ```typescript
+ * const manager = getTTSSidecarManager();
+ *
+ * manager.on('audio', (response) => {
+ *   console.log('Received audio chunk:', response.index);
+ * });
+ *
+ * await manager.ensureReady();
+ * await manager.generate({
+ *   id: 'req-1',
+ *   text: 'Hello, world!',
+ *   voice: 'af_heart',
+ * });
+ * ```
+ */
+export declare class TTSSidecarManager extends EventEmitter {
+    private state;
+    private process;
+    private healthCheckTimer;
+    private restartDelay;
+    private restartTimer;
+    private lineBuffer;
+    private readyPromise;
+    private readyResolve;
+    private readyReject;
+    private shuttingDown;
+    private consecutiveHealthFailures;
+    private readonly maxHealthFailures;
+    constructor();
+    /**
+     * Get the current state of the sidecar manager.
+     */
+    getState(): SidecarState;
+    /**
+     * Get the cross-platform TTS directory path.
+     *
+     * - Windows: %APPDATA%/sudocode/tts
+     * - macOS/Linux: ~/.config/sudocode/tts
+     */
+    getTTSDirectory(): string;
+    /**
+     * Get the path to the Python virtual environment.
+     */
+    getVenvPath(): string;
+    /**
+     * Get the path to the Python executable in the venv.
+     */
+    getPythonPath(): string;
+    /**
+     * Get the path to the models directory.
+     */
+    getModelsPath(): string;
+    /**
+     * Get the path to the sidecar Python script.
+     */
+    getSidecarScriptPath(): string;
+    /**
+     * Check if the TTS environment is installed.
+     */
+    isInstalled(): Promise<InstallationStatus>;
+    /**
+     * Detect the appropriate ONNX runtime for the current platform.
+     *
+     * Note: This is a synchronous method that does a quick filesystem check
+     * for NVIDIA drivers on Linux. For most platforms, no I/O is performed.
+     */
+    detectOnnxRuntime(): OnnxRuntime;
+    /**
+     * Install the TTS environment (venv, kokoro-onnx, appropriate ONNX runtime, model files).
+     *
+     * @throws Error if installation fails
+     */
+    install(): Promise<void>;
+    /**
+     * Start the sidecar process.
+     *
+     * @throws Error if start fails or ready signal not received
+     */
+    start(): Promise<void>;
+    /**
+     * Ensure the sidecar is ready for TTS generation.
+     * Installs if necessary, then starts the sidecar.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Generate TTS audio from text.
+     *
+     * @param request - The TTS generation request
+     * @throws Error if sidecar is not ready
+     */
+    generate(request: TTSGenerateRequest): Promise<void>;
+    /**
+     * Gracefully shutdown the sidecar process.
+     *
+     * Sends shutdown command, waits for graceful exit.
+     * If timeout expires, sends SIGKILL.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Set the current state and emit state event.
+     */
+    private setState;
+    /**
+     * Find the system Python interpreter.
+     */
+    private findSystemPython;
+    /**
+     * Download a file from URL to disk.
+     */
+    private downloadFile;
+    /**
+     * Handle stdout data from the sidecar process.
+     * Parses JSON-lines and emits appropriate events.
+     */
+    private handleStdout;
+    /**
+     * Handle a parsed response from the sidecar.
+     */
+    private handleResponse;
+    /**
+     * Handle sidecar process exit.
+     */
+    private handleProcessExit;
+    /**
+     * Clean up resources.
+     */
+    private cleanup;
+    /**
+     * Schedule a restart with exponential backoff.
+     */
+    private scheduleRestart;
+    /**
+     * Start the health check timer.
+     */
+    private startHealthChecks;
+    /**
+     * Stop the health check timer.
+     */
+    private stopHealthChecks;
+    /**
+     * Perform a health check by sending a ping.
+     */
+    private performHealthCheck;
+    /**
+     * Check if consecutive health failures exceed threshold.
+     */
+    private checkHealthFailures;
+}
+/**
+ * Get or create the global TTS sidecar manager instance.
+ *
+ * @returns The TTS sidecar manager instance
+ */
+export declare function getTTSSidecarManager(): TTSSidecarManager;
+/**
+ * Reset the global TTS sidecar manager instance (for testing).
+ * Shuts down any running sidecar before resetting.
+ */
+export declare function resetTTSSidecarManager(): Promise<void>;
+export {};
+//# sourceMappingURL=tts-sidecar-manager.d.ts.map

package/dist/services/tts-sidecar-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-sidecar-manager.d.ts","sourceRoot":"","sources":["../../src/services/tts-sidecar-manager.ts"],"names":[],"mappings":"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"}