profclaw 0.0.1-beta.1

package/dist/voice/tts/elevenlabs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ElevenLabs TTS Provider
+ *
+ * Synthesizes speech using ElevenLabs' multilingual TTS API.
+ * Supports dynamic voice listing, stability/similarity controls.
+ */
+import type { SynthesizeOptions, SynthesizeResult, VoiceInfo } from '../index.js';
+/**
+ * Synthesize speech using ElevenLabs TTS.
+ * Requires ELEVENLABS_API_KEY environment variable.
+ */
+export declare function synthesizeWithElevenLabs(text: string, options?: SynthesizeOptions): Promise<SynthesizeResult>;
+/**
+ * Fetch available voices from ElevenLabs.
+ * Requires ELEVENLABS_API_KEY environment variable.
+ */
+export declare function getElevenLabsVoices(): Promise<VoiceInfo[]>;
+//# sourceMappingURL=elevenlabs.d.ts.map

package/dist/voice/tts/elevenlabs.js

@@ -0,0 +1,178 @@
+/**
+ * ElevenLabs TTS Provider
+ *
+ * Synthesizes speech using ElevenLabs' multilingual TTS API.
+ * Supports dynamic voice listing, stability/similarity controls.
+ */
+import { z } from 'zod';
+import { logger } from '../../utils/logger.js';
+const ELEVENLABS_BASE_URL = 'https://api.elevenlabs.io/v1';
+const DEFAULT_MODEL = 'eleven_multilingual_v2';
+const DEFAULT_STABILITY = 0.5;
+const DEFAULT_SIMILARITY_BOOST = 0.75;
+const DEFAULT_VOICE_ID = '21m00Tcm4TlvDq8ikWAM'; // Rachel
+// Zod schemas for ElevenLabs API responses
+const ElevenLabsVoiceSchema = z.object({
+    voice_id: z.string(),
+    name: z.string(),
+    preview_url: z.string().nullable().optional(),
+    labels: z
+        .object({
+        language: z.string().optional(),
+        gender: z.string().optional(),
+    })
+        .optional(),
+    fine_tuning: z
+        .object({
+        language: z.string().nullable().optional(),
+    })
+        .optional(),
+});
+const ElevenLabsVoicesResponseSchema = z.object({
+    voices: z.array(ElevenLabsVoiceSchema),
+});
+const VoiceSettingsSchema = z.object({
+    stability: z.number().min(0).max(1),
+    similarity_boost: z.number().min(0).max(1),
+});
+const TTSBodySchema = z.object({
+    text: z.string().min(1),
+    model_id: z.string(),
+    voice_settings: VoiceSettingsSchema,
+});
+function resolveVoiceId(voice) {
+    if (!voice)
+        return DEFAULT_VOICE_ID;
+    // Accept either a voice ID or a display name - caller responsibility
+    return voice;
+}
+/**
+ * Synthesize speech using ElevenLabs TTS.
+ * Requires ELEVENLABS_API_KEY environment variable.
+ */
+export async function synthesizeWithElevenLabs(text, options) {
+    const apiKey = process.env.ELEVENLABS_API_KEY;
+    if (!apiKey) {
+        throw new Error('ELEVENLABS_API_KEY is not set');
+    }
+    const voiceId = resolveVoiceId(options?.voice);
+    const modelId = options?.model ?? DEFAULT_MODEL;
+    const body = TTSBodySchema.safeParse({
+        text,
+        model_id: modelId,
+        voice_settings: {
+            stability: DEFAULT_STABILITY,
+            similarity_boost: DEFAULT_SIMILARITY_BOOST,
+        },
+    });
+    if (!body.success) {
+        throw new Error(`Invalid ElevenLabs TTS request: ${body.error.message}`);
+    }
+    const url = `${ELEVENLABS_BASE_URL}/text-to-speech/${encodeURIComponent(voiceId)}`;
+    logger.info('[ElevenLabs] Synthesizing speech', {
+        voiceId,
+        model: modelId,
+        chars: text.length,
+    });
+    const startMs = Date.now();
+    let rawResponse;
+    try {
+        rawResponse = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'xi-api-key': apiKey,
+                'Content-Type': 'application/json',
+                Accept: 'audio/mpeg',
+            },
+            body: JSON.stringify(body.data),
+        });
+    }
+    catch (error) {
+        logger.error('[ElevenLabs] Network error', {
+            error: error instanceof Error ? error.message : 'Unknown',
+        });
+        throw new Error(`ElevenLabs network error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    if (!rawResponse.ok) {
+        const errorBody = await rawResponse.text();
+        logger.error('[ElevenLabs] API error', {
+            status: rawResponse.status,
+            body: errorBody,
+        });
+        throw new Error(`ElevenLabs API error ${rawResponse.status}: ${errorBody}`);
+    }
+    let audioBuffer;
+    try {
+        const arrayBuffer = await rawResponse.arrayBuffer();
+        audioBuffer = Buffer.from(arrayBuffer);
+    }
+    catch (error) {
+        throw new Error(`ElevenLabs response read error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    const elapsed = Date.now() - startMs;
+    logger.info('[ElevenLabs] Synthesis complete', {
+        voiceId,
+        bytes: audioBuffer.length,
+        elapsed,
+    });
+    return {
+        audio: audioBuffer,
+        format: 'mp3',
+        characters_used: text.length,
+    };
+}
+/**
+ * Fetch available voices from ElevenLabs.
+ * Requires ELEVENLABS_API_KEY environment variable.
+ */
+export async function getElevenLabsVoices() {
+    const apiKey = process.env.ELEVENLABS_API_KEY;
+    if (!apiKey) {
+        throw new Error('ELEVENLABS_API_KEY is not set');
+    }
+    logger.info('[ElevenLabs] Fetching available voices');
+    let rawResponse;
+    try {
+        rawResponse = await fetch(`${ELEVENLABS_BASE_URL}/voices`, {
+            headers: {
+                'xi-api-key': apiKey,
+            },
+        });
+    }
+    catch (error) {
+        logger.error('[ElevenLabs] Failed to fetch voices', {
+            error: error instanceof Error ? error.message : 'Unknown',
+        });
+        throw new Error(`ElevenLabs voices fetch error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    if (!rawResponse.ok) {
+        const errorBody = await rawResponse.text();
+        throw new Error(`ElevenLabs voices API error ${rawResponse.status}: ${errorBody}`);
+    }
+    let json;
+    try {
+        json = await rawResponse.json();
+    }
+    catch (error) {
+        throw new Error(`ElevenLabs voices response parse error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    const parsed = ElevenLabsVoicesResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        logger.error('[ElevenLabs] Unexpected voices response shape', {
+            issues: parsed.error.issues,
+        });
+        throw new Error(`Unexpected ElevenLabs voices response: ${parsed.error.message}`);
+    }
+    return parsed.data.voices.map((v) => {
+        const language = v.labels?.language ?? v.fine_tuning?.language ?? undefined;
+        return {
+            id: v.voice_id,
+            name: v.name,
+            provider: 'elevenlabs',
+            language: language ?? undefined,
+            gender: v.labels?.gender ?? undefined,
+            preview_url: v.preview_url ?? undefined,
+        };
+    });
+}
+//# sourceMappingURL=elevenlabs.js.map

package/dist/voice/tts/openai-tts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OpenAI TTS Provider
+ *
+ * Synthesizes speech using OpenAI's text-to-speech API.
+ * Supports multiple voices, models, speeds, and output formats.
+ */
+import type { SynthesizeOptions, SynthesizeResult, VoiceInfo } from '../index.js';
+export declare const OPENAI_VOICES: readonly ["alloy", "echo", "fable", "onyx", "nova", "shimmer"];
+export type OpenAIVoice = (typeof OPENAI_VOICES)[number];
+/**
+ * Synthesize speech using OpenAI TTS.
+ * Requires OPENAI_API_KEY environment variable.
+ */
+export declare function synthesizeWithOpenAI(text: string, options?: SynthesizeOptions): Promise<SynthesizeResult>;
+/**
+ * Return static voice list for OpenAI TTS.
+ */
+export declare function getOpenAIVoices(): VoiceInfo[];
+//# sourceMappingURL=openai-tts.d.ts.map

package/dist/voice/tts/openai-tts.js

@@ -0,0 +1,127 @@
+/**
+ * OpenAI TTS Provider
+ *
+ * Synthesizes speech using OpenAI's text-to-speech API.
+ * Supports multiple voices, models, speeds, and output formats.
+ */
+import { z } from 'zod';
+import { logger } from '../../utils/logger.js';
+const OPENAI_TTS_URL = 'https://api.openai.com/v1/audio/speech';
+const DEFAULT_MODEL = 'tts-1';
+const DEFAULT_VOICE = 'alloy';
+const DEFAULT_FORMAT = 'mp3';
+const DEFAULT_SPEED = 1.0;
+export const OPENAI_VOICES = [
+    'alloy',
+    'echo',
+    'fable',
+    'onyx',
+    'nova',
+    'shimmer',
+];
+const VALID_FORMATS = ['mp3', 'opus', 'aac', 'wav'];
+// Request body schema used for internal validation before sending
+const TTSRequestSchema = z.object({
+    model: z.string(),
+    voice: z.string(),
+    input: z.string().min(1).max(4096),
+    speed: z.number().min(0.25).max(4.0),
+    response_format: z.enum(VALID_FORMATS),
+});
+/**
+ * Synthesize speech using OpenAI TTS.
+ * Requires OPENAI_API_KEY environment variable.
+ */
+export async function synthesizeWithOpenAI(text, options) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error('OPENAI_API_KEY is not set');
+    }
+    const model = options?.model ?? DEFAULT_MODEL;
+    const voice = options?.voice ?? DEFAULT_VOICE;
+    const format = (options?.format ?? DEFAULT_FORMAT);
+    const speed = options?.speed ?? DEFAULT_SPEED;
+    const requestBody = TTSRequestSchema.safeParse({
+        model,
+        voice,
+        input: text,
+        speed,
+        response_format: format,
+    });
+    if (!requestBody.success) {
+        throw new Error(`Invalid TTS request: ${requestBody.error.message}`);
+    }
+    logger.info('[OpenAI TTS] Synthesizing speech', {
+        model,
+        voice,
+        format,
+        speed,
+        chars: text.length,
+    });
+    const startMs = Date.now();
+    let rawResponse;
+    try {
+        rawResponse = await fetch(OPENAI_TTS_URL, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(requestBody.data),
+        });
+    }
+    catch (error) {
+        logger.error('[OpenAI TTS] Network error', {
+            error: error instanceof Error ? error.message : 'Unknown',
+        });
+        throw new Error(`OpenAI TTS network error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    if (!rawResponse.ok) {
+        const errorBody = await rawResponse.text();
+        logger.error('[OpenAI TTS] API error', {
+            status: rawResponse.status,
+            body: errorBody,
+        });
+        throw new Error(`OpenAI TTS API error ${rawResponse.status}: ${errorBody}`);
+    }
+    let audioBuffer;
+    try {
+        const arrayBuffer = await rawResponse.arrayBuffer();
+        audioBuffer = Buffer.from(arrayBuffer);
+    }
+    catch (error) {
+        throw new Error(`OpenAI TTS response read error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    const elapsed = Date.now() - startMs;
+    logger.info('[OpenAI TTS] Synthesis complete', {
+        format,
+        bytes: audioBuffer.length,
+        elapsed,
+    });
+    return {
+        audio: audioBuffer,
+        format,
+        characters_used: text.length,
+    };
+}
+/**
+ * Return static voice list for OpenAI TTS.
+ */
+export function getOpenAIVoices() {
+    const voiceDescriptions = {
+        alloy: { gender: 'neutral', language: 'en' },
+        echo: { gender: 'male', language: 'en' },
+        fable: { gender: 'male', language: 'en' },
+        onyx: { gender: 'male', language: 'en' },
+        nova: { gender: 'female', language: 'en' },
+        shimmer: { gender: 'female', language: 'en' },
+    };
+    return OPENAI_VOICES.map((id) => ({
+        id,
+        name: id.charAt(0).toUpperCase() + id.slice(1),
+        provider: 'openai',
+        language: voiceDescriptions[id].language,
+        gender: voiceDescriptions[id].gender,
+    }));
+}
+//# sourceMappingURL=openai-tts.js.map

package/dist/voice/tts/system.d.ts

@@ -0,0 +1,26 @@
+/**
+ * System TTS Fallback Provider
+ *
+ * Uses the host OS's built-in speech synthesis:
+ * - macOS: the `say` command
+ * - Linux: the `espeak` command
+ *
+ * This provider does not require any API keys.
+ */
+import type { SynthesizeOptions, SynthesizeResult } from '../index.js';
+/**
+ * Returns true if a supported system TTS binary is available on the current OS.
+ * Result is cached after the first call.
+ */
+export declare function isSystemTTSAvailable(): boolean;
+/**
+ * Async variant that actually probes for the binary.
+ * Call this during initialization to warm the cache.
+ */
+export declare function probeSystemTTSAvailability(): Promise<boolean>;
+/**
+ * Synthesize speech using the OS-native TTS engine.
+ * Supported on macOS (say) and Linux (espeak).
+ */
+export declare function synthesizeWithSystem(text: string, options?: SynthesizeOptions): Promise<SynthesizeResult>;
+//# sourceMappingURL=system.d.ts.map

package/dist/voice/tts/system.js

@@ -0,0 +1,146 @@
+/**
+ * System TTS Fallback Provider
+ *
+ * Uses the host OS's built-in speech synthesis:
+ * - macOS: the `say` command
+ * - Linux: the `espeak` command
+ *
+ * This provider does not require any API keys.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readFile, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { logger } from '../../utils/logger.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Check whether the required system TTS binary is present.
+ * Uses `which` on POSIX systems to locate the binary without executing it.
+ */
+async function binaryExists(name) {
+    try {
+        await execFileAsync('which', [name], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let systemTTSAvailableCache = null;
+/**
+ * Returns true if a supported system TTS binary is available on the current OS.
+ * Result is cached after the first call.
+ */
+export function isSystemTTSAvailable() {
+    // Return cached result synchronously on subsequent calls.
+    // First-time callers should await the async version when accuracy matters.
+    if (systemTTSAvailableCache !== null)
+        return systemTTSAvailableCache;
+    // Optimistic sync check: trust the platform
+    if (process.platform === 'darwin')
+        return true;
+    if (process.platform === 'linux')
+        return true;
+    return false;
+}
+/**
+ * Async variant that actually probes for the binary.
+ * Call this during initialization to warm the cache.
+ */
+export async function probeSystemTTSAvailability() {
+    if (process.platform === 'darwin') {
+        const available = await binaryExists('say');
+        systemTTSAvailableCache = available;
+        return available;
+    }
+    if (process.platform === 'linux') {
+        const available = await binaryExists('espeak');
+        systemTTSAvailableCache = available;
+        return available;
+    }
+    systemTTSAvailableCache = false;
+    return false;
+}
+async function synthesizeOnMac(text, options) {
+    const tmpFile = join(tmpdir(), `profclaw-tts-${randomUUID()}.aiff`);
+    const args = [];
+    if (options?.voice) {
+        args.push('-v', options.voice);
+    }
+    // `say` rate: words-per-minute, not a 0.25-4.0 multiplier.
+    // Map the standard speed multiplier to ~175 WPM baseline.
+    if (options?.speed != null) {
+        const wpm = Math.round(175 * options.speed);
+        args.push('-r', String(wpm));
+    }
+    args.push('-o', tmpFile, '--', text);
+    logger.info('[SystemTTS] Invoking `say`', { tmpFile, voice: options?.voice });
+    try {
+        await execFileAsync('say', args, { timeout: 30_000 });
+    }
+    catch (error) {
+        throw new Error(`say command failed: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    let audio;
+    try {
+        audio = await readFile(tmpFile);
+    }
+    finally {
+        await unlink(tmpFile).catch(() => undefined);
+    }
+    logger.info('[SystemTTS] macOS synthesis complete', { bytes: audio.length });
+    return {
+        audio,
+        format: 'wav', // AIFF is close enough for consumer purposes; relabel as wav
+        characters_used: text.length,
+    };
+}
+async function synthesizeOnLinux(text, options) {
+    const tmpFile = join(tmpdir(), `profclaw-tts-${randomUUID()}.wav`);
+    const args = ['--stdout', '-w', tmpFile];
+    if (options?.voice) {
+        args.push('-v', options.voice);
+    }
+    if (options?.speed != null) {
+        // espeak speed: words-per-minute (default 175)
+        const wpm = Math.round(175 * options.speed);
+        args.push('-s', String(wpm));
+    }
+    args.push('--', text);
+    logger.info('[SystemTTS] Invoking `espeak`', { tmpFile, voice: options?.voice });
+    try {
+        await execFileAsync('espeak', args, { timeout: 30_000 });
+    }
+    catch (error) {
+        throw new Error(`espeak command failed: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    let audio;
+    try {
+        audio = await readFile(tmpFile);
+    }
+    finally {
+        await unlink(tmpFile).catch(() => undefined);
+    }
+    logger.info('[SystemTTS] Linux synthesis complete', { bytes: audio.length });
+    return {
+        audio,
+        format: 'wav',
+        characters_used: text.length,
+    };
+}
+/**
+ * Synthesize speech using the OS-native TTS engine.
+ * Supported on macOS (say) and Linux (espeak).
+ */
+export async function synthesizeWithSystem(text, options) {
+    if (process.platform === 'darwin') {
+        return synthesizeOnMac(text, options);
+    }
+    if (process.platform === 'linux') {
+        return synthesizeOnLinux(text, options);
+    }
+    throw new Error(`System TTS is not supported on platform: ${process.platform}`);
+}
+//# sourceMappingURL=system.js.map

package/dist/voice/wake-word.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Wake Word Detection Stub
+ *
+ * profClaw uses shortcut/button activation instead of always-on wake word
+ * detection so it does not burn API credits while idle. This module provides
+ * the interface and a simple energy-based detection fallback for callers that
+ * want basic "someone started talking" triggering without a real ML engine.
+ *
+ * Supported engines:
+ *   - 'none'      - disabled (no-op)
+ *   - 'energy'    - amplitude threshold (not real keyword spotting)
+ *   - 'porcupine' - stub, reserved for future add-on
+ */
+export interface WakeWordConfig {
+    /** The wake phrase (informational; only used by ML engines). */
+    phrase: string;
+    /** Detection engine. 'none' disables detection entirely. */
+    engine: 'none' | 'energy' | 'porcupine';
+    /** Detection sensitivity in [0, 1]. Higher values mean more triggers. */
+    sensitivity: number;
+    /** Called when a wake word (or energy spike) is detected. */
+    onDetected?: (confidence: number) => void;
+}
+export interface WakeWordDetector {
+    /** Start listening for the wake word. */
+    start(): Promise<void>;
+    /** Stop listening. */
+    stop(): void;
+    /** Returns true while the detector is actively listening. */
+    isListening(): boolean;
+    /** Cumulative detection statistics since start() was last called. */
+    getStats(): {
+        detections: number;
+        falsePositives: number;
+        uptime: number;
+    };
+}
+/**
+ * Create a wake word detector for the given configuration.
+ * Currently only 'energy' and 'none' are implemented.
+ * Requesting 'porcupine' falls back to 'energy' with a warning.
+ */
+export declare function createWakeWordDetector(config: WakeWordConfig): WakeWordDetector;
+//# sourceMappingURL=wake-word.d.ts.map