From 6376ad25724b1619095783b7e1c11217b16a3626 Mon Sep 17 00:00:00 2001 From: leonardotrapani Date: Sun, 1 Feb 2026 02:15:58 +0100 Subject: [PATCH] docs: update config.md with all providers and options --- docs/config.md | 244 +++++++++++++++++++++++++++++++++++++++++++++++- progress.txt | 14 +++ tasks/prd.jsonc | 2 +- 3 files changed, 256 insertions(+), 4 deletions(-) diff --git a/docs/config.md b/docs/config.md index 7e1d4a3..77ecb9d 100644 --- a/docs/config.md +++ b/docs/config.md @@ -12,6 +12,11 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app - [Unified Provider System](#unified-provider-system) - [Transcription Providers](#transcription-providers) + - [Cloud Providers](#cloud-providers) + - [Local Transcription (whisper-cpp)](#local-transcription-whisper-cpp) + - [Streaming Transcription](#streaming-transcription) +- [Language Configuration](#language-configuration) +- [Model Management](#model-management) - [LLM Post-Processing](#llm-post-processing) - [Keywords](#keywords) - [Recording Configuration](#recording-configuration) @@ -37,6 +42,9 @@ Hyprvoice uses a unified provider system where API keys are configured once and [providers.elevenlabs] api_key = "..." # Or set ELEVENLABS_API_KEY env var + +[providers.deepgram] + api_key = "..." # Or set DEEPGRAM_API_KEY env var ``` **API key resolution order:** @@ -46,7 +54,9 @@ Hyprvoice uses a unified provider system where API keys are configured once and ## Transcription Providers -Hyprvoice supports multiple transcription backends: +Hyprvoice supports multiple transcription backends. See [docs/providers.md](./providers.md) for detailed comparisons. + +### Cloud Providers ### OpenAI Whisper API @@ -114,13 +124,199 @@ model = "voxtral-mini-latest" # Or "voxtral-mini-2507" ### ElevenLabs Scribe -Transcription using ElevenLabs' Scribe API with 99 language support: +Transcription using ElevenLabs' Scribe API with 57+ language support: ```toml [transcription] provider = "elevenlabs" language = "" -model = "scribe_v1" # Or "scribe_v2" for real-time, lower latency +model = "scribe_v1" # Or "scribe_v2" for lower latency +``` + +**Features:** + +- 57+ languages supported +- Both batch and streaming models available +- Ultra-low latency streaming options + +### Deepgram Nova + +Fast streaming transcription using Deepgram's Nova models: + +```toml +[providers.deepgram] + api_key = "..." # Or set DEEPGRAM_API_KEY env var + +[transcription] +provider = "deepgram" +language = "" +model = "nova-3" # Or "nova-2" for different language support +``` + +**Features:** + +- All models are streaming-only +- Nova-3: 42 languages, best accuracy +- Nova-2: 33 languages, faster with filler word detection +- Excellent for real-time transcription and live captions + +### Local Transcription (whisper-cpp) + +Run Whisper models locally on your machine. No API keys, no network latency, complete privacy. + +**Prerequisites:** + +1. Install whisper-cli: https://github.com/ggerganov/whisper.cpp +2. Download a model: `hyprvoice model download base.en` + +```toml +[transcription] +provider = "whisper-cpp" +language = "" # Empty for auto-detect +model = "base.en" # English-only model (fastest) +threads = 0 # 0 = auto (uses NumCPU - 1) +``` + +**Available models:** + +| Model | Size | Languages | Best For | +|-------|------|-----------|----------| +| `tiny.en` | 75MB | English only | Quick tests, low-power devices | +| `base.en` | 142MB | English only | Daily use, good balance | +| `small.en` | 466MB | English only | Better accuracy | +| `medium.en` | 1.5GB | English only | Best English accuracy | +| `tiny` | 75MB | 57 languages | Quick multilingual | +| `base` | 142MB | 57 languages | Daily multilingual use | +| `small` | 466MB | 57 languages | Better multilingual | +| `medium` | 1.5GB | 57 languages | Great accuracy | +| `large-v3` | 3GB | 57 languages | Best accuracy | + +**Threads configuration:** + +- `threads = 0` (default): auto-detects, uses NumCPU - 1 to leave one core free +- `threads = 4`: explicitly use 4 threads +- Higher thread count = faster transcription but more CPU usage + +### Streaming Transcription + +For real-time transcription, use streaming models: + +```toml +# ElevenLabs streaming +[transcription] +provider = "elevenlabs" +model = "scribe_v1-streaming" # Or "scribe_v2-streaming" for <150ms latency + +# Deepgram streaming (all models are streaming) +[transcription] +provider = "deepgram" +model = "nova-3" + +# OpenAI Realtime +[transcription] +provider = "openai" +model = "gpt-4o-realtime-preview" +``` + +**Streaming models:** + +| Provider | Model | Latency | Languages | +|----------|-------|---------|-----------| +| ElevenLabs | `scribe_v1-streaming` | Low | 57+ | +| ElevenLabs | `scribe_v2-streaming` | <150ms | 57+ | +| Deepgram | `nova-3` | Low | 42 | +| Deepgram | `nova-2` | Very Low | 33 | +| OpenAI | `gpt-4o-realtime-preview` | Low | 57 | + +## Language Configuration + +Configure the expected spoken language for better accuracy: + +```toml +[transcription] +language = "" # Empty for auto-detect (recommended) +# Or specify a language code: +# language = "en" # English +# language = "es" # Spanish +# language = "fr" # French +# language = "zh" # Chinese +# language = "ja" # Japanese +``` + +**Recommendations:** + +- Use auto-detect (`language = ""`) for most cases - it works well +- Specify a language if you always speak the same language (slight accuracy boost) +- Required for English-only models if you speak English + +### Supported Languages + +Hyprvoice supports 57 languages: + +Afrikaans (af), Arabic (ar), Armenian (hy), Azerbaijani (az), Belarusian (be), Bosnian (bs), Bulgarian (bg), Catalan (ca), Chinese (zh), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Estonian (et), Finnish (fi), French (fr), Galician (gl), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Icelandic (is), Indonesian (id), Italian (it), Japanese (ja), Kannada (kn), Kazakh (kk), Korean (ko), Latvian (lv), Lithuanian (lt), Macedonian (mk), Malay (ms), Marathi (mr), Maori (mi), Nepali (ne), Norwegian (no), Persian (fa), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Serbian (sr), Slovak (sk), Slovenian (sl), Spanish (es), Swahili (sw), Swedish (sv), Tagalog (tl), Tamil (ta), Thai (th), Turkish (tr), Ukrainian (uk), Urdu (ur), Vietnamese (vi), Welsh (cy) + +### Language-Model Compatibility + +Some models only support English. Hyprvoice validates compatibility: + +**English-only models:** + +| Provider | Model | +|----------|-------| +| Groq | `distil-whisper-large-v3-en` | +| whisper-cpp | `tiny.en`, `base.en`, `small.en`, `medium.en` | + +**Deepgram models** support fewer languages than the full 57 - see [providers.md](./providers.md#deepgram-language-support). + +**Validation behavior:** + +1. **At config time (TUI/validation):** Selecting an English-only model with a non-English language shows an error and prevents saving +2. **At runtime (safety net):** If config was manually edited to an invalid combination, hyprvoice logs a warning, sends a desktop notification, and falls back to auto-detect + +``` +# This combination will be rejected: +[transcription] +provider = "groq-transcription" +model = "distil-whisper-large-v3-en" # English only! +language = "es" # Error: model does not support Spanish +``` + +## Model Management + +Manage local whisper models with CLI commands: + +### List Models + +```bash +# List all models +hyprvoice model list + +# Filter by provider +hyprvoice model list --provider whisper-cpp + +# Filter by type +hyprvoice model list --type transcription +``` + +Shows installed status `[x]` for local models and model details. + +### Download Models + +```bash +# Download a whisper model +hyprvoice model download base.en + +# Download with progress +hyprvoice model download large-v3 +``` + +Cloud models (OpenAI, Groq, etc.) don't require download - this is for local models only. + +### Remove Models + +```bash +# Remove a downloaded model +hyprvoice model remove base.en ``` ## LLM Post-Processing @@ -391,6 +587,48 @@ You can customize notification text via the `[notifications.messages]` section: model = "gpt-4o-mini" ``` +### Local Transcription (Privacy-First) + +```toml +# No API keys needed! + +[transcription] + provider = "whisper-cpp" + model = "base.en" + threads = 0 # Auto-detect (NumCPU - 1) + +[llm] + enabled = false # No LLM for full privacy +``` + +### Real-Time Streaming with Deepgram + +```toml +[providers.deepgram] + api_key = "..." + +[transcription] + provider = "deepgram" + model = "nova-3" # All Deepgram models are streaming + +[llm] + enabled = false # Streaming doesn't need LLM post-processing +``` + +### Ultra-Low Latency Streaming + +```toml +[providers.elevenlabs] + api_key = "..." + +[transcription] + provider = "elevenlabs" + model = "scribe_v2-streaming" # <150ms latency + +[llm] + enabled = false +``` + ## Migration from Old Config Format If you're upgrading from an older version with `transcription.api_key`: diff --git a/progress.txt b/progress.txt index a61c4f5..0564699 100644 --- a/progress.txt +++ b/progress.txt @@ -491,4 +491,18 @@ Started: Sun Feb 1 12:22:47 AM CET 2026 - Language support section: full 57-language list, English-only models clearly marked, Deepgram subset languages - Streaming vs Batch explanation with use cases - Local vs Cloud comparison with pros/cons and when-to-choose guidelines +- Typecheck passes + +### Task 46: Update docs/config.md with all providers and options +- Added whisper-cpp provider section with provider, model, threads options and model table +- Added Deepgram provider section with api_key/DEEPGRAM_API_KEY, models (nova-3, nova-2) +- Added Deepgram to unified provider system section +- Documented streaming models: scribe_v1-streaming, scribe_v2-streaming, nova-3, nova-2, gpt-4o-realtime-preview +- Added streaming models table with Provider/Model/Latency/Languages +- Added Model Management section with hyprvoice model list/download/remove commands and examples +- Added Language Configuration section with auto-detect recommendation and language code examples +- Added Supported Languages subsection listing all 57 language codes +- Added Language-Model Compatibility section with English-only models table +- Documented validation behavior: config-time hard error + runtime fallback with notification +- Added example configurations: Local Transcription, Deepgram Streaming, Ultra-Low Latency Streaming - Typecheck passes \ No newline at end of file diff --git a/tasks/prd.jsonc b/tasks/prd.jsonc index fa8af1c..4be22f8 100644 --- a/tasks/prd.jsonc +++ b/tasks/prd.jsonc @@ -1082,7 +1082,7 @@ "Examples are copy-paste ready", "Typecheck passes" ], - "passes": false + "passes": true } ] }