diff --git a/.env.example b/.env.example index 066b7c3..24cbcc8 100644 --- a/.env.example +++ b/.env.example @@ -7,8 +7,8 @@ # Option A: Connect to OpenClaw Gateway (recommended) # This gives your voice assistant full agent context, memory, and tools -CLAWDBOT_GATEWAY_URL=http://localhost:18789 -CLAWDBOT_GATEWAY_TOKEN=your-gateway-token +OPENCLAW_GATEWAY_URL=http://localhost:18789 +OPENCLAW_GATEWAY_TOKEN=your-gateway-token # Option B: Direct OpenAI (standalone, no agent features) # OPENAI_API_KEY=sk-your-key-here diff --git a/README.md b/README.md index c0a6180..d321002 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,20 @@ **Open-source browser-based voice interface for AI assistants.** -Talk to your AI like you talk to Alexa — but self-hosted, private, and free from subscription fees. +Talk to your AI like you talk to Alexa — but self-hosted, private, and powered by your own agent. ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Python](https://img.shields.io/badge/python-3.10+-green.svg) -## Why? - -Voice AI platforms like ElevenLabs Agents ($0.08-0.12/min) and Retell.ai ($0.13-0.31/min) are expensive. OpenClaw Voice runs entirely on your own hardware for ~$0.003/min at scale. - ## Features - 🎙️ **Browser voice widget** — Push-to-talk or hands-free continuous mode -- 🚗 **Continuous mode** — Like Grok voice. Auto-listens after each response. Perfect for Tesla browser! -- 🔊 **Self-hosted STT** — Whisper Large V3 Turbo (runs on Mac/Linux/GPU) -- 🗣️ **Self-hosted TTS** — Chatterbox (MIT license, ElevenLabs quality) +- 🚗 **Continuous mode** — Auto-listens after each response. Perfect for hands-free use! +- 🔊 **Local STT** — Whisper runs locally via faster-whisper. Your voice stays on your machine. +- 🗣️ **Premium TTS** — ElevenLabs for natural, expressive speech (Chatterbox available for self-hosted) - 🔌 **Pluggable backend** — Connect to any AI (OpenAI, Claude, OpenClaw gateway, etc.) - 🦞 **OpenClaw integration** — Full agent context, memory, and tools via gateway -- 🌐 **WebRTC audio** — Low latency (<500ms end-to-end achievable) +- 🌐 **WebSocket streaming** — Low latency audio over secure WebSockets - 🏠 **Fully self-hosted** — Your data stays on your servers ## Quick Start @@ -27,8 +23,8 @@ Voice AI platforms like ElevenLabs Agents ($0.08-0.12/min) and Retell.ai ($0.13- ### Prerequisites - Python 3.10+ -- Node.js 18+ (for client dev) -- CUDA GPU recommended (CPU works but slower) +- ElevenLabs API key (recommended) or local TTS +- OpenAI API key (or OpenClaw gateway) ### Installation @@ -37,38 +33,38 @@ Voice AI platforms like ElevenLabs Agents ($0.08-0.12/min) and Retell.ai ($0.13- git clone https://github.com/Purple-Horizons/openclaw-voice.git cd openclaw-voice -# Install Python dependencies +# Create virtual environment +python -m venv .venv +source .venv/bin/activate # or .venv\Scripts\activate on Windows + +# Install dependencies pip install -r requirements.txt -# Download models (first run only) -python scripts/download_models.py +# Configure environment +cp .env.example .env +# Edit .env with your API keys # Start the voice server -python -m src.server.main +PYTHONPATH=. python -m src.server.main # Open http://localhost:8765 in your browser ``` -### Docker (Recommended) - -```bash -docker compose up -``` - ## Architecture ``` -┌─────────────────┐ WebRTC ┌─────────────────┐ -│ Browser │ ◄─────────────► │ Voice Gateway │ -│ (Voice Widget) │ Audio/Text │ (Python) │ -└─────────────────┘ └────────┬────────┘ - │ - ┌────────────────────────┼────────────────────────┐ - │ │ │ - ┌─────▼─────┐ ┌───────▼───────┐ ┌──────▼──────┐ - │ Whisper │ │ Your AI │ │ Chatterbox │ - │ (STT) │ │ Backend │ │ (TTS) │ - └───────────┘ └───────────────┘ └─────────────┘ +┌─────────────────┐ WebSocket ┌─────────────────┐ +│ Browser │ ◄──────────────► │ Voice Server │ +│ (Voice Widget) │ Audio/Text │ (Python) │ +└─────────────────┘ └────────┬────────┘ + │ + ┌─────────────────────────┼─────────────────────────┐ + │ │ │ + ┌─────▼─────┐ ┌───────▼───────┐ ┌──────▼──────┐ + │ Whisper │ │ Your AI │ │ ElevenLabs │ + │ (STT) │ │ Backend │ │ (TTS) │ + │ (local) │ │ │ │ │ + └───────────┘ └───────────────┘ └─────────────┘ ``` ## OpenClaw Gateway Integration @@ -77,8 +73,8 @@ For full agent capabilities (memory, tools, context), connect to OpenClaw's gate ```bash # .env -CLAWDBOT_GATEWAY_URL=http://localhost:18789 -CLAWDBOT_GATEWAY_TOKEN=your-gateway-token +OPENCLAW_GATEWAY_URL=http://localhost:18789 +OPENCLAW_GATEWAY_TOKEN=your-gateway-token ELEVENLABS_API_KEY=your-elevenlabs-key ``` @@ -107,9 +103,16 @@ Now voice chat routes through your full agent — same context as text chats. # Via environment variables (.env) OPENCLAW_STT_MODEL=base # tiny, base, small, medium, large-v3-turbo OPENCLAW_STT_DEVICE=auto # auto, cpu, cuda, mps -OPENCLAW_TTS_MODEL=chatterbox # chatterbox, xtts, mock OPENCLAW_PORT=8765 OPENCLAW_REQUIRE_AUTH=false # Set true for production + +# API Keys +ELEVENLABS_API_KEY=your-key # For TTS (recommended) +OPENAI_API_KEY=your-key # For AI backend (if not using gateway) + +# OpenClaw Gateway (optional - for full agent integration) +OPENCLAW_GATEWAY_URL=http://localhost:18789 +OPENCLAW_GATEWAY_TOKEN=your-token ``` ## Supported Models @@ -118,32 +121,24 @@ OPENCLAW_REQUIRE_AUTH=false # Set true for production | Model | Speed | Quality | VRAM | |-------|-------|---------|------| | Whisper Large V3 Turbo | 216x realtime | Best | ~6GB | -| Distil-Whisper | 6x faster | Good | ~3GB | -| Whisper.cpp (CPU) | Slower | Best | N/A | +| Whisper Base | Fast | Good | ~1GB | +| Whisper Tiny | Fastest | Fair | ~500MB | ### Text-to-Speech (TTS) -| Model | Speed | Quality | Voice Cloning | -|-------|-------|---------|---------------| -| Chatterbox | ~1s | Excellent | 5-second samples | -| Kokoro-82M | <0.3s | Very Good | No | -| XTTS-v2 | ~1s | Excellent | 6-second samples | +| Model | Type | Quality | Notes | +|-------|------|---------|-------| +| **ElevenLabs** | Cloud | Excellent | Recommended. Natural voices. | +| Chatterbox | Local | Very Good | MIT license, voice cloning | +| XTTS-v2 | Local | Excellent | Voice cloning supported | ## Browser Widget -Embed the voice widget in any webpage: +The server includes a built-in web interface at the root URL. -```html - - -``` - -Or use React: - -```jsx -import { VoiceWidget } from '@openclaw/voice-widget-react'; - - -``` +For HTTPS (required for mobile microphone access), use: +- Tailscale Funnel +- nginx with SSL +- Cloudflare Tunnel ## API @@ -155,7 +150,7 @@ Connect to `ws://localhost:8765/ws` and send/receive JSON messages: // Start listening { "type": "start_listening" } -// Audio data (base64 PCM) +// Audio data (base64 PCM float32) { "type": "audio", "data": "base64..." } // Stop listening @@ -172,56 +167,14 @@ Connect to `ws://localhost:8765/ws` and send/receive JSON messages: - [x] Basic WebSocket voice gateway - [x] Whisper STT integration -- [x] Chatterbox TTS integration +- [x] ElevenLabs TTS integration - [x] Voice Activity Detection (VAD) - [x] Streaming responses -- [x] Docker GPU support -- [x] React component (`@openclaw/voice-widget-react`) -- [x] API key authentication - [x] Continuous conversation mode +- [x] API key authentication - [ ] WebRTC for lower latency - [ ] Voice cloning UI -- [ ] Vue component -- [ ] Kubernetes Helm chart -- [ ] RunPod template - -## Hosted Service (Coming Soon) - -Don't want to self-host? We offer a managed service: - -| Tier | Minutes/Month | Price | Features | -|------|---------------|-------|----------| -| **Free** | 60 | $0 | Basic voice chat | -| **Pro** | 500 | $29/mo | + Voice cloning | -| **Enterprise** | Unlimited | $99/mo | + Priority, SLA | - -**API Key Authentication:** - -```bash -# Get an API key -curl -X POST "https://voice.openclaw.dev/api/keys?name=myapp&tier=pro" \ - -H "x-master-key: YOUR_MASTER_KEY" - -# Connect with API key -wss://voice.openclaw.dev/ws?api_key=ocv_xxxxx - -# Check usage -curl "https://voice.openclaw.dev/api/usage?api_key=ocv_xxxxx" -``` - -## Cost Comparison - -| Platform | Cost/Minute | -|----------|-------------| -| ElevenLabs Conversational AI | $0.08-0.12 | -| Retell.ai | $0.13-0.31 | -| Vapi.ai | $0.05-0.15 | -| **OpenClaw Voice (hosted)** | **~$0.06** | -| **OpenClaw Voice (self-hosted)** | **~$0.003** | - -## Contributing - -Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). +- [ ] Docker support ## License @@ -229,11 +182,11 @@ MIT License — see [LICENSE](LICENSE). ## Credits -- [Whisper](https://github.com/openai/whisper) — OpenAI -- [Chatterbox](https://github.com/resemble-ai/chatterbox) — Resemble AI -- [Silero VAD](https://github.com/snakers4/silero-vad) — Silero +- [faster-whisper](https://github.com/guillaumekln/faster-whisper) — CTranslate2 Whisper +- [ElevenLabs](https://elevenlabs.io) — Text-to-Speech +- [Silero VAD](https://github.com/snakers4/silero-vad) — Voice Activity Detection - Built for [OpenClaw](https://openclaw.ai) --- -**Made with 🦀 by [Purple Horizons](https://purplehorizons.io)** +**Made with 🦞 by [Purple Horizons](https://purplehorizons.io)** diff --git a/SKILL.md b/SKILL.md index d0e60fc..55ac38b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -9,7 +9,7 @@ Adds voice chat capability to your OpenClaw agent. Users can speak to your agent ## Stack - **STT**: faster-whisper (local, no API costs) -- **TTS**: ElevenLabs (or Chatterbox for self-hosted) +- **TTS**: ElevenLabs (cloud, high quality) or Chatterbox (self-hosted) - **Transport**: WebSocket - **Backend**: OpenClaw gateway (chatCompletions endpoint) @@ -59,7 +59,7 @@ uv sync # or pip install -r requirements.txt # Configure cp .env.example .env -# Edit .env with your CLAWDBOT_GATEWAY_URL, CLAWDBOT_GATEWAY_TOKEN, ELEVENLABS_API_KEY +# Edit .env with your OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, ELEVENLABS_API_KEY # Run PYTHONPATH=. python -m src.server.main @@ -75,8 +75,8 @@ For HTTPS (required for mobile mic), use Tailscale Funnel or your own SSL. | Variable | Required | Description | |----------|----------|-------------| -| `CLAWDBOT_GATEWAY_URL` | Yes* | OpenClaw gateway URL (e.g., `http://localhost:18789`) | -| `CLAWDBOT_GATEWAY_TOKEN` | Yes* | Gateway auth token | +| `OPENCLAW_GATEWAY_URL` | Yes* | OpenClaw gateway URL (e.g., `http://localhost:18789`) | +| `OPENCLAW_GATEWAY_TOKEN` | Yes* | Gateway auth token | | `ELEVENLABS_API_KEY` | Recommended | For high-quality TTS | | `OPENAI_API_KEY` | Fallback | Used if gateway not configured | diff --git a/src/server/backend.py b/src/server/backend.py index 6b2617b..4dfa7e5 100644 --- a/src/server/backend.py +++ b/src/server/backend.py @@ -1,5 +1,5 @@ """ -AI Backend module - connects to OpenAI, Clawdbot, or custom backends. +AI Backend module - connects to OpenAI, OpenClaw gateway, or custom backends. """ import asyncio @@ -43,9 +43,9 @@ class AIBackend: logger.info(f"✅ OpenAI client ready (model: {self.model})") except ImportError: logger.error("openai package not installed") - elif self.backend_type == "clawdbot": - # TODO: Implement Clawdbot gateway connection - logger.info("Clawdbot backend (not yet implemented)") + elif self.backend_type == "openclaw": + # OpenClaw gateway uses OpenAI-compatible API + logger.info("OpenClaw gateway backend") else: logger.warning(f"Unknown backend type: {self.backend_type}") diff --git a/src/server/main.py b/src/server/main.py index 6ea2c2a..07deed5 100644 --- a/src/server/main.py +++ b/src/server/main.py @@ -5,7 +5,7 @@ WebSocket server that handles: - Audio input from browser - Speech-to-Text via Whisper - AI backend communication -- Text-to-Speech via Chatterbox +- Text-to-Speech via ElevenLabs - Audio streaming back to browser """ @@ -50,14 +50,14 @@ class Settings(BaseSettings): tts_voice: Optional[str] = None # Path to voice sample for cloning # AI Backend - backend_type: str = "openai" # openai, clawdbot, custom + backend_type: str = "openai" # openai, openclaw, custom backend_url: str = "https://api.openai.com/v1" backend_model: str = "gpt-4o-mini" openai_api_key: Optional[str] = None - # OpenClaw Gateway (auto-detected from CLAWDBOT_GATEWAY_URL + TOKEN) - clawdbot_gateway_url: Optional[str] = None - clawdbot_gateway_token: Optional[str] = None + # OpenClaw Gateway (auto-detected from OPENCLAW_GATEWAY_URL + TOKEN) + openclaw_gateway_url: Optional[str] = None + openclaw_gateway_token: Optional[str] = None # Audio sample_rate: int = 16000 @@ -106,8 +106,8 @@ async def startup(): # Initialize AI backend # Auto-detect OpenClaw gateway - gateway_url = settings.clawdbot_gateway_url or os.getenv("CLAWDBOT_GATEWAY_URL") - gateway_token = settings.clawdbot_gateway_token or os.getenv("CLAWDBOT_GATEWAY_TOKEN") + gateway_url = settings.openclaw_gateway_url or os.getenv("OPENCLAW_GATEWAY_URL") + gateway_token = settings.openclaw_gateway_token or os.getenv("OPENCLAW_GATEWAY_TOKEN") if gateway_url and gateway_token: # Use OpenClaw gateway (connects to Aria!)