\n Self-hosted AI speaking coach for American English learners. \n Real conversation practice · Pronunciation coaching · Vocabulary notebook · Spaced-repetition review\n
\n\n---\n\n## Features\n\n- **Real-time conversation** with an AI coach (streaming LLM)\n- **Speech-to-text** via local [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (GPU or CPU)\n- **Text-to-speech** via [edge-tts](https://github.com/rany2/edge-tts) (free, no API key)\n- **Tap-to-lookup** — click any word in coach replies for instant meaning + auto-save to notebook\n- **Phrase selection** — select a phrase for contextual translation\n- **Spaced-repetition notebook** with Leitner box review\n- **6 conversation scenarios** (Daily Chat, Business, Travel, Interview, Discussion, Stories)\n- **3 difficulty levels** (Beginner / Intermediate / Advanced)\n- **Zero external STT API cost** — Whisper runs 100% locally\n- **Single-file frontend** — no build step, no Node.js\n\n## Architecture\n\n```text\n┌───────────────────────────────────┐\n│ Browser (index.html) │\n│ mic → WebM → /api/transcribe │\n│ text → /api/chat (SSE stream) │\n│ audio ← /api/tts │\n└──────────────┬────────────────────┘\n │ HTTPS (self-signed)\n┌──────────────▼────────────────────┐\n│ FastAPI backend │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ Whisper │ │ OpenAI-compat │ │\n│ │ (local) │ │ LLM API │ │\n│ └──────────┘ └───────────────┘ │\n│ ┌──────────┐ ┌───────────────┐ │\n│ │ edge-tts │ │ JSON storage │ │\n│ └──────────┘ └───────────────┘ │\n└───────────────────────────────────┘\n```\n\n## Directory Structure\n\n```text\nai-accent-coach/\n├── app.py # FastAPI backend (all APIs)\n├── coach.sh # Service manager (start/stop/restart/status/log)\n├── requirements.txt\n├── .env.example # ← copy to .env and fill in\n├── static/\n│ └── index.html # Single-file frontend\n└── assets/\n └── logo.png\n```\n\n## Quick Start\n\n```bash\ngit clone https://github.com/Carl-AI-Lab/ai-accent-coach.git\ncd ai-accent-coach\n\npython3 -m venv venv && source venv/bin/activate # recommended\npip install -r requirements.txt\n\ncp .env.example .env\n# Edit .env — at minimum set OPENAI_API_KEY\n```\n\nStart the server:\n\n```bash\nbash coach.sh start # background, logs to accent-coach.log\n# or\npython app.py # foreground with live output\n```\n\nOpen **https://localhost:8443** in your browser (accept the self-signed certificate).\n\nStop:\n\n```bash\nbash coach.sh stop\n```\n\n## Configuration\n\nAll settings live in **`.env`** (see [.env.example](.env.example)):\n\n| Variable | Default | Description |\n|---|---|---|\n| `OPENAI_API_KEY` | *(required)* | API key for any OpenAI-compatible service |\n| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | LLM endpoint. Works with OpenAI, DeepSeek, Ollama, etc. |\n| `LLM_MODEL` | `gpt-4.1-mini` | Model name |\n| `WHISPER_DEVICE` | `cuda` | `cuda` for GPU, `cpu` for CPU-only |\n| `WHISPER_MODEL` | `distil-large-v3` | Whisper model size |\n| `WHISPER_UNLOAD_TIMEOUT` | `120` | Seconds idle before auto-unloading the model from memory |\n| `TTS_VOICE` | `en-US-AndrewMultilingualNeural` | edge-tts voice name |\n| `PORT` | `8443` | HTTPS listen port |\n\n### Using a Different LLM Provider\n\nAccentCoach works with any OpenAI-compatible API:\n\n```bash\n# OpenAI (default)\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=gpt-4.1-mini\n\n# DeepSeek\nOPENAI_BASE_URL=https://api.deepseek.com/v1\nOPENAI_API_KEY=sk-...\nLLM_MODEL=deepseek-chat\n\n# Ollama (local, free)\nOPENAI_BASE_URL=http://localhost:11434/v1\nOPENAI_API_KEY=ollama\nLLM_MODEL=llama3.1\n```\n\n## GPU vs CPU\n\nWhisper runs locally for speech-to-text. You can choose GPU or CPU mode.\n\n### GPU Mode (recommended)\n\n```bash\nWHISPER_DEVICE=cuda\n```\n\nRequires NVIDIA GPU with **cuBLAS** and **cuDNN** for CUDA 12.\n\nIf you installed CUDA libraries via pip (`nvidia-cublas-cu12`, `nvidia-cudnn-cu12`), you need to set `LD_LIBRARY_PATH` so that `faster-whisper` can find them:\n\n```bash\n# Find the library paths installed by pip\npython3 -c \"import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0]); print(nvidia.cudnn.lib.__path__[0])\"\n\n# Example output:\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cublas/lib\n# /home/you/venv/lib/python3.11/site-packages/nvidia/cudnn/lib\n\n# Set before starting (or uncomment the line in coach.sh):\nexport LD_LIBRARY_PATH=\"/home/you/venv/.../nvidia/cublas/lib:/home/you/venv/.../nvidia/cudnn/lib\"\n```\n\n### CPU Mode\n\n```bash\nWHISPER_DEVICE=cpu\n```\n\nNo GPU required. Works on any machine. Significantly slower — see benchmark below.\n\n> **Tip:** On CPU, consider using a smaller model for faster response:\n> ```bash\n> WHISPER_MODEL=base # fastest, lower accuracy\n> WHISPER_MODEL=small # good balance\n> WHISPER_MODEL=medium # better accuracy, slower\n> ```\n\n### Benchmark (actual measurements)\n\nTested on the same machine with a 10-second audio clip, `distil-large-v3` model, `beam_size=5`, `vad_filter=True`:\n\n| | Device | Compute Type | Model Load | Transcription (avg of 3) |\n|---|---|---|---|---|\n| **GPU** | NVIDIA RTX 4060 Laptop (8 GB) | float16 | 16.5 s | **0.51 s** |\n| **CPU** | Intel i7-12700H (20 threads) | int8 | 5.7 s | **5.52 s** |\n\n> **CPU is ~11× slower for transcription**, but model loading is actually 3× faster since it skips CUDA initialization. For casual practice the CPU latency (~5 s per utterance) is acceptable. For fluid conversation, **GPU is strongly recommended**.\n\n## Requirements\n\n- Python ≥ 3.9\n- An OpenAI-compatible API key (for the LLM)\n- *(GPU mode)* NVIDIA GPU + CUDA 12 + cuBLAS + cuDNN 9\n- *(CPU mode)* No extra hardware — works on any x86_64 or ARM machine\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}}}}
![\"Accent](\"assets/logo.png\"){kind=logo}
\n