Initial commit

README.md

@@ -0,0 +1,90 @@
+# Local LiveKit Voice Chat
+
+Talk to a locally-running LLM through your browser. Everything runs in Docker — one command to start.
+
+## Stack
+
+| Layer | Tool |
+|---|---|
+| Signalling / WebRTC | LiveKit Server |
+| LLM | Ollama (Heretic-Dolphin3.0-Qwen2.5-3b by default) |
+| VAD | Silero (in agent container) |
+| STT | faster-whisper (in agent container, fully local) |
+| TTS | Kokoro (local, OpenAI-compat API) |
+| UI + token server | FastAPI + plain HTML |
+
+## Prerequisites
+
+- Docker + Docker Compose (that's it)
+
+## Quick start
+
+```bash
+cp .env.example .env   # edit if needed
+./start.sh
+```
+
+Open **http://localhost:7731** — pick a model, click Connect, start talking.
+
+First run will:
+1. Pull Docker images (~2-3 GB total)
+2. Download the default LLM via Ollama (~2 GB)
+3. Download the Kokoro TTS model (~350 MB)
+
+Subsequent starts are fast.
+
+## Configuration (`.env`)
+
+```ini
+# LLM
+DEFAULT_MODEL=hf.co/mradermacher/Heretic-Dolphin3.0-Qwen2.5-3b-i1-GGUF:Q4_K_M
+
+# TTS: kokoro | piper | elevenlabs | openai
+TTS_BACKEND=kokoro
+KOKORO_VOICE=af_heart   # af_heart af_sky am_adam bm_lewis bf_emma ...
+
+# STT (faster-whisper model size)
+WHISPER_MODEL=base      # tiny base small medium large-v3
+
+# ElevenLabs (only if TTS_BACKEND=elevenlabs)
+# ELEVENLABS_API_KEY=sk-...
+# ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM
+```
+
+## Kokoro voices
+
+Browse samples at: https://huggingface.co/hexgrad/Kokoro-82M
+
+Popular voices:
+
+| Voice | Style |
+|---|---|
+| `af_heart` | American female, warm (default) |
+| `af_sky` | American female, airy |
+| `af_bella` | American female, expressive |
+| `am_adam` | American male |
+| `am_michael` | American male, deep |
+| `bm_lewis` | British male |
+| `bf_emma` | British female |
+
+## LLM models
+
+The default is `Heretic-Dolphin3.0-Qwen2.5-3b` (fine-tuned, conversational, ~2 GB GGUF).
+To switch, edit `DEFAULT_MODEL` in `.env` — any `ollama pull`-compatible model name works.
+
+```bash
+# Browse and pull models manually
+docker compose exec ollama ollama list
+docker compose exec ollama ollama pull llama3.2
+```
+
+## Useful commands
+
+```bash
+./start.sh               # start everything (foreground, Ctrl-C to stop)
+./start.sh -d            # start in background
+docker compose down      # stop all services
+docker compose logs -f agent   # watch agent logs
+docker compose logs -f kokoro  # watch TTS logs
+```
+docker compose exec ollama ollama pull hf.co/mradermacher/heretic_magnum-v2-4b-GGUF:Q4_K_M