use-voice-control 0.1.0 → 0.1.2

package/speech/docs/INTEGRATION.md

@@ -0,0 +1,276 @@
+# Speech API Integration Guide
+
+This document explains how to integrate the new TTS/STT APIs with the existing speech library.
+
+## Overview
+
+The speech system now has three layers:
+
+1. **API Layer** (`/app/api/speech/*`) — Server-side endpoints for TTS and STT
+2. **Client Utilities** (`lib/speech-api.ts`) — High-level functions for frontend use
+3. **Components** (`components/SpeechInput.tsx`, `components/SpeechSettings.tsx`) — Ready-to-use UI
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│      React Components (UI Layer)        │
+│  ┌────────────────────────────────────┐ │
+│  │  SpeechInput (STT + TTS playback)  │ │
+│  │  SpeechSettings (Configuration)    │ │
+│  └────────────────────────────────────┘ │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│      Client Utilities (lib/speech-api)  │
+│  ┌────────────────────────────────────┐ │
+│  │  generateSpeechFromText()           │ │
+│  │  createAudioURL()                   │ │
+│  │  speakText()                        │ │
+│  └────────────────────────────────────┘ │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│         Next.js API Routes              │
+│  ┌────────────────────────────────────┐ │
+│  │  POST /api/speech/tts              │ │
+│  │  GET|POST /api/speech/stt          │ │
+│  └────────────────────────────────────┘ │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│      Speech Libraries & Models          │
+│  ┌────────────────────────────────────┐ │
+│  │  Kokoro TTS (Node.js via lib)      │ │
+│  │  Deepgram TTS (API)                │ │
+│  │  Moonshine STT (Browser-side)      │ │
+│  └────────────────────────────────────┘ │
+└─────────────────────────────────────────┘
+```
+
+## Usage
+
+### Basic Speech Input (STT only)
+
+```tsx
+'use client';
+
+import { SpeechInput } from '@/components/SpeechInput';
+
+export function MyComponent() {
+  const handleTranscription = (text: string) => {
+    console.log('Transcribed:', text);
+    // Do something with the text
+  };
+
+  return (
+    <SpeechInput 
+      onTranscription={handleTranscription}
+    />
+  );
+}
+```
+
+### With TTS Feedback
+
+```tsx
+import { SpeechInput } from '@/components/SpeechInput';
+
+export function MyComponent() {
+  return (
+    <SpeechInput 
+      onTranscription={(text) => console.log(text)}
+      enableTTS={true}
+      ttsProvider="kokoro"
+      ttsVoice="af_heart"
+    />
+  );
+}
+```
+
+### With Settings Panel
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { SpeechInput } from '@/components/SpeechInput';
+import { SpeechSettings, type SpeechSettings } from '@/components/SpeechSettings';
+
+export function MyComponent() {
+  const [settings, setSettings] = useState<SpeechSettings>({
+    ttsEnabled: true,
+    ttsProvider: 'kokoro',
+    ttsVoice: 'af_heart',
+    sttEnabled: true,
+  });
+
+  return (
+    <div className="space-y-4">
+      <SpeechSettings onChange={setSettings} />
+      <SpeechInput
+        onTranscription={(text) => console.log(text)}
+        enableTTS={settings.ttsEnabled}
+        ttsProvider={settings.ttsProvider}
+        ttsVoice={settings.ttsVoice}
+        disabled={!settings.sttEnabled}
+      />
+    </div>
+  );
+}
+```
+
+### Direct API Usage
+
+```tsx
+import { generateSpeechFromText, speakText, createAudioURL } from '@/lib/speech-api';
+
+// Generate audio blob
+const audioBlob = await generateSpeechFromText(
+  'Hello, world!',
+  'kokoro',
+  'af_heart'
+);
+
+// Create object URL for <audio> element
+const url = await createAudioURL('Hello, world!');
+
+// Play audio and wait for completion
+await speakText('Hello, world!', 'kokoro', 'af_heart');
+```
+
+## API Endpoints
+
+### POST /api/speech/tts
+
+Generates speech audio from text.
+
+**Request:**
+```json
+{
+  "text": "Hello, world!",
+  "provider": "kokoro",
+  "voice": "af_heart"
+}
+```
+
+**Response:**
+- 200: Audio data (binary)
+- 400: Invalid text parameter
+- 500: TTS generation failed
+
+**Headers:**
+- `Content-Type`: `audio/wav` or `audio/mpeg`
+- `Cache-Control`: `public, max-age=31536000`
+
+### GET /api/speech/stt
+
+Returns STT API documentation.
+
+**Response:**
+```json
+{
+  "message": "STT (Speech-to-Text) API",
+  "description": "Transcription happens client-side using Moonshine.js",
+  "models": ["moonshine-small"],
+  "note": "For client-side transcription, import SpeechInput component"
+}
+```
+
+### POST /api/speech/stt
+
+Server-side transcription (future implementation).
+
+Currently returns 501 Not Implemented.
+
+## Configuration
+
+### Environment Variables
+
+No environment variables are required for client-side Moonshine STT.
+
+For Deepgram TTS, set:
+```
+DEEPGRAM_API_KEY=xxx
+```
+
+### Component Props
+
+#### SpeechInput
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onTranscription` | `(text: string) => void` | Required | Callback when transcription is complete |
+| `disabled` | `boolean` | `false` | Disable the microphone button |
+| `enableTTS` | `boolean` | `false` | Auto-play TTS for transcribed text |
+| `ttsProvider` | `'kokoro' \| 'deepgram'` | `'kokoro'` | Which TTS provider to use |
+| `ttsVoice` | `string` | `'af_heart'` | Voice ID for TTS |
+
+#### SpeechSettings
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onChange` | `(settings: SpeechSettings) => void` | `undefined` | Callback when settings change |
+
+## Voices
+
+### Kokoro Voices
+
+Default provider with natural-sounding voices:
+- Female: `af_heart`, `af_alloy`, `af_aoede`, `af_bella`, `af_jessica`, `af_nicole`, `af_river`, `af_sarah`, `af_sky`
+- Male: `am_adam`, `am_echo`, `am_fable`, `am_fenrir`, `am_liam`, `am_michael`, `am_onyx`
+
+### Deepgram Speakers
+
+Premium provider with distinct personalities:
+- `angus`, `asteria`, `arcas`, `orion`, `orpheus`, `athena`, `luna`, `zeus`, `perseus`, `helios`, `hera`, `stella`
+
+## Troubleshooting
+
+### Model Download Issues
+
+The first time Moonshine runs, it downloads the model (~150MB). This is cached in the browser.
+
+To debug:
+```tsx
+console.log('Model loading...');
+const Moonshine = await import('@moonshine-ai/moonshine-js');
+console.log('Model loaded');
+```
+
+### Microphone Permission Denied
+
+The browser will prompt for microphone access on first use. If denied:
+1. Check browser settings
+2. Ensure the site is running on HTTPS (localhost OK)
+3. Clear site permissions and retry
+
+### TTS API Failures
+
+Check:
+1. Is `/api/speech/tts` responding? Test with: `curl -X POST http://localhost:3000/api/speech/tts -H "Content-Type: application/json" -d '{"text":"hello"}'`
+2. Are model dependencies installed? Check `node_modules/@huggingface/transformers`
+3. Check server logs for errors
+
+### Performance Tips
+
+- Moonshine model loads on first STT use; consider preloading with `<link rel="preload">`
+- TTS audio is cached server-side; repeated requests are instant
+- For high-frequency TTS, store generated audio URLs in a client-side cache
+
+## Future Enhancements
+
+- [ ] Server-side Moonshine STT as fallback
+- [ ] Streaming TTS (audio chunks as they're generated)
+- [ ] Voice activity detection (VAD) tuning
+- [ ] Audio analytics and error reporting
+- [ ] Multilingual STT/TTS support
+
+## Files
+
+- `/app/api/speech/tts/route.ts` — TTS endpoint
+- `/app/api/speech/stt/route.ts` — STT endpoint (documentation only)
+- `/lib/speech-api.ts` — Client utilities
+- `/components/SpeechInput.tsx` — Speech input component
+- `/components/SpeechSettings.tsx` — Configuration component
+- `/lib/speech/*` — Core speech library (Kokoro, Deepgram, types)

package/speech/docs/MIGRATION.md

@@ -0,0 +1,220 @@
+# TTS Migration Guide
+
+## Changes Summary
+
+The voice API has been refactored from a Deepgram-only implementation to a unified speech library supporting both **Kokoro** (default) and **Deepgram** providers.
+
+### What Changed
+
+**Before:**
+```ts
+// app/api/agent/voice/route.ts
+// Hardcoded Deepgram via Cloudflare Workers AI
+const result = await ai.run("@cf/deepgram/aura-1", {
+  text,
+  speaker: "angus",
+  encoding: "mp3",
+});
+```
+
+**After:**
+```ts
+// lib/speech/index.ts - Unified API
+const result = await generateSpeech({
+  text: "Hello world",
+  provider: "kokoro",  // or "deepgram"
+  voice: "af_heart",
+});
+```
+
+## New Features
+
+### 1. Kokoro Provider (Default)
+- **Faster**: CPU-based inference, no network dependency
+- **Higher Quality**: More natural prosody and intonation
+- **16 Voices**: 9 female, 7 male
+- **WAV Output**: Lossless audio
+- **Model**: `onnx-community/Kokoro-82M-v1.0-ONNX`
+
+### 2. Deepgram Provider (Legacy)
+- **Edge-optimized**: Cloudflare Workers AI
+- **12 Voices**: Aura speakers
+- **MP3 Output**: Smaller file size
+- **Requires**: Cloudflare AI binding
+
+## API Changes
+
+### Request Format
+
+**Backward Compatible** - Old requests still work:
+```json
+{
+  "text": "Hello",
+  "speaker": "angus"
+}
+```
+
+**New Format** (recommended):
+```json
+{
+  "text": "Hello world",
+  "provider": "kokoro",
+  "voice": "af_heart"
+}
+```
+
+### Response
+
+**Headers:**
+- `Content-Type`: `audio/wav` (Kokoro) or `audio/mpeg` (Deepgram)
+- `Cache-Control`: `public, max-age=86400`
+- `Content-Disposition`: `inline; filename="speech.wav"`
+
+**Body:** Audio buffer
+
+## Breaking Changes
+
+### None!
+
+The API maintains backward compatibility:
+- `speaker` field still works (alias for `voice`)
+- Omitting `provider` defaults to Kokoro
+- Old Deepgram requests work by specifying `provider: "deepgram"`
+
+## Migration Path
+
+### For Existing Clients
+
+**Option 1: No changes (use Kokoro automatically)**
+```ts
+// No code changes needed - automatically uses Kokoro
+fetch("/api/agent/voice", {
+  method: "POST",
+  body: JSON.stringify({ text: "Hello" })
+});
+```
+
+**Option 2: Keep using Deepgram**
+```ts
+// Explicitly request Deepgram
+fetch("/api/agent/voice", {
+  method: "POST",
+  body: JSON.stringify({
+    text: "Hello",
+    provider: "deepgram",
+    voice: "angus"
+  })
+});
+```
+
+**Option 3: Switch to Kokoro (recommended)**
+```ts
+fetch("/api/agent/voice", {
+  method: "POST",
+  body: JSON.stringify({
+    text: "Hello",
+    provider: "kokoro",
+    voice: "af_heart"
+  })
+});
+```
+
+## File Structure
+
+```
+lib/speech/
+├── index.ts              # Main API
+├── types.ts              # Shared types & voice lists
+├── kokoro.ts             # Kokoro provider
+├── deepgram.ts           # Deepgram provider
+├── README.md             # Documentation
+├── MIGRATION.md          # This file
+├── client-example.tsx    # React component example
+└── test.ts               # Test script
+```
+
+## Testing
+
+### Run Test Script
+```bash
+cd apps/qwksearch-web
+npx tsx lib/speech/test.ts
+# Creates test-output.wav
+```
+
+### Test API Endpoint
+```bash
+curl -X POST http://localhost:3000/api/agent/voice \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Hello from Kokoro", "provider": "kokoro", "voice": "af_heart"}' \
+  --output test.wav
+```
+
+## Performance Comparison
+
+| Metric | Kokoro | Deepgram |
+|--------|--------|----------|
+| First request | ~2-3s (model download) | ~500ms |
+| Subsequent | ~100-300ms | ~500ms |
+| Quality | ★★★★★ | ★★★★☆ |
+| File size | Larger (WAV) | Smaller (MP3) |
+| Dependencies | Node CPU | Cloudflare AI |
+
+## Voice Mapping
+
+### Kokoro → Deepgram Equivalents
+
+| Use Case | Kokoro | Deepgram |
+|----------|--------|----------|
+| Default female | `af_heart` | `asteria` |
+| Professional female | `af_alloy` | `athena` |
+| Warm female | `af_sarah` | `luna` |
+| Default male | `am_adam` | `angus` |
+| Deep male | `am_echo` | `perseus` |
+| Storyteller | `am_fable` | `orpheus` |
+
+## Troubleshooting
+
+### "Kokoro model loading failed"
+- Check disk space (~82MB needed)
+- Verify network access to Hugging Face
+- Check logs: `console.log` shows model load progress
+
+### "Cloudflare AI binding not available"
+- Expected in local dev without Wrangler
+- Use Kokoro instead: `provider: "kokoro"`
+- For Deepgram, run: `vinext dev`
+
+### WAV files not playing
+- Browser support: All modern browsers support WAV
+- Try converting to MP3: `ffmpeg -i speech.wav speech.mp3`
+- Or use Deepgram provider for native MP3
+
+## Environment Variables
+
+None required! Both providers work out-of-the-box:
+- **Kokoro**: Downloads model automatically
+- **Deepgram**: Uses Cloudflare AI binding (in prod)
+
+## Rollback
+
+To revert to Deepgram-only:
+
+1. Remove Kokoro dependency:
+   ```bash
+   bun remove kokoro-js
+   ```
+
+2. Restore old route:
+   ```bash
+   git checkout HEAD -- app/api/agent/voice/route.ts
+   ```
+
+3. Delete speech lib:
+   ```bash
+   rm -rf lib/speech
+   ```
+
+## Questions?
+
+See `lib/speech/README.md` for detailed documentation.

package/speech/docs/QUICKSTART.md

@@ -0,0 +1,159 @@
+# TTS Quick Start
+
+## 5-Second Summary
+
+Text-to-speech with **Kokoro** (default, faster, better quality) or **Deepgram** (Cloudflare AI).
+
+## API Call
+
+```bash
+curl -X POST http://localhost:3000/api/agent/voice \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Hello world"}' \
+  --output speech.wav
+```
+
+## React Component
+
+```tsx
+import { useState } from "react";
+
+export function TextToSpeech() {
+  const [audio, setAudio] = useState<string | null>(null);
+
+  const speak = async (text: string) => {
+    const res = await fetch("/api/agent/voice", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text }),
+    });
+
+    const blob = await res.blob();
+    setAudio(URL.createObjectURL(blob));
+  };
+
+  return (
+    <div>
+      <button onClick={() => speak("Hello world")}>
+        Speak
+      </button>
+      {audio && <audio controls src={audio} autoPlay />}
+    </div>
+  );
+}
+```
+
+## Request Body
+
+```ts
+{
+  text: string;          // Required, max 5000 chars
+  provider?: "kokoro" | "deepgram";  // Default: kokoro
+  voice?: string;        // Default: af_heart
+}
+```
+
+## Top 5 Voices
+
+**Kokoro (default):**
+- `af_heart` - Warm female (default)
+- `af_alloy` - Professional female
+- `am_adam` - Strong male
+- `am_echo` - Deep male
+- `af_sarah` - Friendly female
+
+**Deepgram:**
+- `angus` - Default male
+- `asteria` - Default female
+- `luna` - Warm female
+- `perseus` - Deep male
+- `athena` - Professional female
+
+## Switch Provider
+
+```ts
+// Use Deepgram instead
+fetch("/api/agent/voice", {
+  method: "POST",
+  body: JSON.stringify({
+    text: "Hello",
+    provider: "deepgram",
+    voice: "angus"
+  })
+});
+```
+
+## Full Voice Lists
+
+**Kokoro (16 voices):**
+```ts
+const KOKORO_VOICES = [
+  "af_heart", "af_alloy", "af_aoede", "af_bella",
+  "af_jessica", "af_nicole", "af_river", "af_sarah", "af_sky",
+  "am_adam", "am_echo", "am_fable", "am_fenrir",
+  "am_liam", "am_michael", "am_onyx"
+];
+```
+
+**Deepgram (12 voices):**
+```ts
+const DEEPGRAM_VOICES = [
+  "angus", "asteria", "arcas", "orion", "orpheus", "athena",
+  "luna", "zeus", "perseus", "helios", "hera", "stella",
+];
+```
+
+## Rate Limits
+
+- **Guests**: 10 requests/day
+- **Authenticated**: Unlimited
+
+## Error Handling
+
+```ts
+const res = await fetch("/api/agent/voice", {
+  method: "POST",
+  body: JSON.stringify({ text: "Hello" })
+});
+
+if (!res.ok) {
+  const error = await res.json();
+  console.error(error.error);
+  // "text is required"
+  // "Daily TTS limit reached (10/day)"
+  // "Cloudflare AI binding not available"
+}
+```
+
+## Direct Library Usage
+
+```ts
+import { generateSpeech } from "@/lib/speech";
+
+const audio = await generateSpeech({
+  text: "Hello world",
+  voice: "af_heart"
+});
+
+// Returns: { audio: ArrayBuffer, contentType: "audio/wav" }
+```
+
+## Test It
+
+```bash
+# Install dependencies
+cd apps/qwksearch-web
+bun install
+
+# Run test script
+npx tsx lib/speech/test.ts
+
+# Play output
+test-output.wav
+```
+
+## Next Steps
+
+- 📖 Full docs: [README.md](./README.md)
+- 🔄 Migration: [MIGRATION.md](./MIGRATION.md)
+- 💻 Example: [client-example.tsx](./client-example.tsx)