diff --git a/README.md b/README.md index 3579229..34ae952 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,7 @@ hyprvoice configure The wizard guides you through all settings with a user-friendly interface: - **Providers** - API keys for OpenAI, Groq, Mistral, ElevenLabs, Deepgram +- **Language** - Global language setting for all transcription (57 languages + auto-detect) - **Transcription** - Speech-to-text provider and model selection (cloud or local) - **LLM** - Post-processing to clean up transcriptions (enabled by default) - **Keywords** - Domain-specific terms for better accuracy @@ -299,10 +300,12 @@ For complete offline privacy, use whisper.cpp for local transcription - no API k ### Configuration ```toml +[general] +language = "" # empty for auto-detect, or "en", "es", etc. + [transcription] provider = "whisper-cpp" model = "base.en" # or "base" for multilingual -language = "" # empty for auto-detect threads = 0 # 0 = auto (NumCPU - 1) ``` @@ -321,6 +324,9 @@ For real-time transcription results as you speak, use streaming providers. Text ### Configuration ```toml +[general] +language = "" # empty for auto-detect + # ElevenLabs streaming [providers.elevenlabs] api_key = "..." diff --git a/docs/config.md b/docs/config.md index 77ecb9d..0d5cc8d 100644 --- a/docs/config.md +++ b/docs/config.md @@ -10,6 +10,7 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app ## Table of Contents +- [General Settings](#general-settings) - [Unified Provider System](#unified-provider-system) - [Transcription Providers](#transcription-providers) - [Cloud Providers](#cloud-providers) @@ -25,6 +26,41 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app - [Example Configurations](#example-configurations) - [Migration from Old Config Format](#migration-from-old-config-format) +## General Settings + +The `[general]` section contains application-wide settings: + +```toml +[general] +language = "" # ISO 639-1 code (e.g., "en", "es", "de"). Empty for auto-detect. +``` + +### Language + +The global language setting applies to all transcription providers: + +```toml +[general] +language = "" # Auto-detect (recommended) +# language = "en" # English +# language = "es" # Spanish +# language = "de" # German +``` + +**Override behavior:** You can override the global language for a specific transcription provider: + +```toml +[general] +language = "en" # Default to English + +[transcription] +# language = "es" # Uncomment to override for this provider only +``` + +When `transcription.language` is set, it takes precedence over `general.language`. This allows you to set a default language but override it for specific use cases. + +See [Language Configuration](#language-configuration) for the full list of supported languages and model compatibility. + ## Unified Provider System Hyprvoice uses a unified provider system where API keys are configured once and shared between transcription and LLM features: @@ -63,9 +99,11 @@ Hyprvoice supports multiple transcription backends. See [docs/providers.md](./pr Cloud-based transcription using OpenAI's Whisper API: ```toml +[general] +language = "" # Empty for auto-detect, or "en", "es", "fr", etc. + [transcription] provider = "openai" -language = "" # Empty for auto-detect, or "en", "es", "fr", etc. model = "whisper-1" ``` @@ -80,9 +118,11 @@ model = "whisper-1" Fast cloud-based transcription using Groq's Whisper API: ```toml +[general] +language = "" # Empty for auto-detect, or "en", "es", "fr", etc. + [transcription] provider = "groq-transcription" -language = "" # Empty for auto-detect, or "en", "es", "fr", etc. model = "whisper-large-v3" # Or "whisper-large-v3-turbo" for faster processing ``` @@ -116,9 +156,11 @@ model = "whisper-large-v3" Transcription using Mistral's Voxtral API, excellent for European languages: ```toml +[general] +language = "" # Empty for auto-detect + [transcription] provider = "mistral-transcription" -language = "" model = "voxtral-mini-latest" # Or "voxtral-mini-2507" ``` @@ -127,9 +169,11 @@ model = "voxtral-mini-latest" # Or "voxtral-mini-2507" Transcription using ElevenLabs' Scribe API with 57+ language support: ```toml +[general] +language = "" # Empty for auto-detect + [transcription] provider = "elevenlabs" -language = "" model = "scribe_v1" # Or "scribe_v2" for lower latency ``` @@ -144,12 +188,14 @@ model = "scribe_v1" # Or "scribe_v2" for lower latency Fast streaming transcription using Deepgram's Nova models: ```toml +[general] +language = "" # Empty for auto-detect + [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 ``` @@ -170,9 +216,11 @@ Run Whisper models locally on your machine. No API keys, no network latency, com 2. Download a model: `hyprvoice model download base.en` ```toml +[general] +language = "" # Empty for auto-detect + [transcription] provider = "whisper-cpp" -language = "" # Empty for auto-detect model = "base.en" # English-only model (fastest) threads = 0 # 0 = auto (uses NumCPU - 1) ``` @@ -230,10 +278,10 @@ model = "gpt-4o-realtime-preview" ## Language Configuration -Configure the expected spoken language for better accuracy: +Configure the expected spoken language for better accuracy. Language is set globally in `[general]`: ```toml -[transcription] +[general] language = "" # Empty for auto-detect (recommended) # Or specify a language code: # language = "en" # English @@ -243,6 +291,16 @@ language = "" # Empty for auto-detect (recommended) # language = "ja" # Japanese ``` +**Override per-provider:** If you need different languages for different setups: + +```toml +[general] +language = "en" # Global default + +[transcription] +# language = "es" # Uncomment to override for transcription only +``` + **Recommendations:** - Use auto-detect (`language = ""`) for most cases - it works well @@ -273,12 +331,14 @@ Some models only support English. Hyprvoice validates compatibility: 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 -``` +```toml # This combination will be rejected: +[general] +language = "es" # Error: model does not support Spanish + [transcription] provider = "groq-transcription" model = "distil-whisper-large-v3-en" # English only! -language = "es" # Error: model does not support Spanish ``` ## Model Management @@ -525,6 +585,9 @@ You can customize notification text via the `[notifications.messages]` section: ### Fast Transcription Only (No LLM) ```toml +[general] +language = "" # Auto-detect + [providers.groq] api_key = "gsk_..." @@ -539,6 +602,9 @@ You can customize notification text via the `[notifications.messages]` section: ### High Quality with OpenAI (Default) ```toml +[general] +language = "" # Auto-detect + [providers.openai] api_key = "sk-..." @@ -555,6 +621,9 @@ You can customize notification text via the `[notifications.messages]` section: ### Budget-Friendly with Groq ```toml +[general] +language = "" # Auto-detect + [providers.groq] api_key = "gsk_..." @@ -571,6 +640,9 @@ You can customize notification text via the `[notifications.messages]` section: ### Mixed Providers (Groq Transcription + OpenAI LLM) ```toml +[general] +language = "" # Auto-detect + [providers.openai] api_key = "sk-..." @@ -592,6 +664,9 @@ You can customize notification text via the `[notifications.messages]` section: ```toml # No API keys needed! +[general] +language = "" # Auto-detect + [transcription] provider = "whisper-cpp" model = "base.en" @@ -604,6 +679,9 @@ You can customize notification text via the `[notifications.messages]` section: ### Real-Time Streaming with Deepgram ```toml +[general] +language = "" # Auto-detect + [providers.deepgram] api_key = "..." @@ -618,6 +696,9 @@ You can customize notification text via the `[notifications.messages]` section: ### Ultra-Low Latency Streaming ```toml +[general] +language = "" # Auto-detect + [providers.elevenlabs] api_key = "..." @@ -629,8 +710,56 @@ You can customize notification text via the `[notifications.messages]` section: enabled = false ``` +### Multilingual Setup with Specific Language + +```toml +[general] +language = "es" # Always transcribe as Spanish + +[providers.openai] + api_key = "sk-..." + +[transcription] + provider = "openai" + model = "whisper-1" + +[llm] + enabled = true + provider = "openai" + model = "gpt-4o-mini" +``` + ## Migration from Old Config Format +### Language Migration + +If you have `transcription.language` set in your config, it will continue to work but is now an override. The recommended approach is to move it to `[general]`: + +**Old format (still works as override):** + +```toml +[transcription] + provider = "openai" + language = "en" # Works but is now an override + model = "whisper-1" +``` + +**New format (recommended):** + +```toml +[general] + language = "en" # Global setting + +[transcription] + provider = "openai" + model = "whisper-1" + # language = "es" # Only set here to override [general] +``` + +When loading, if `transcription.language` is set but `general.language` is not, the language is automatically migrated to the general section. Run `hyprvoice configure` and save to persist this change. + +### API Key Migration + If you're upgrading from an older version with `transcription.api_key`: **Old format (still works):** diff --git a/progress.txt b/progress.txt index a11c454..47129ca 100644 --- a/progress.txt +++ b/progress.txt @@ -608,4 +608,20 @@ Started: Sun Feb 1 12:22:47 AM CET 2026 - `TestConfig_Validate_GeneralLanguage/transcription.language_override_validated_against_model` - `TestConfig_Validate_GeneralLanguage/valid_override_with_compatible_language` - `TestConfig_Validate_GeneralLanguage/auto_language_always_passes` -- All tests passing, typecheck passes \ No newline at end of file +- All tests passing, typecheck passes + +### Task 12: Update README and docs for general language setting +- Updated README.md: + - Local Transcription config example: language moved to `[general]` section + - Streaming Transcription config example: added `[general]` section with language + - Configuration wizard list: added Language menu item +- Updated docs/config.md: + - Added General Settings section at top with language field documentation + - Added override behavior explanation (transcription.language overrides general.language) + - Updated all provider examples to show language in `[general]` section + - Updated Language Configuration section to show `[general]` format + - Updated Language-Model Compatibility example to use `[general]` format + - Updated all Example Configurations with `[general]` section + - Added "Multilingual Setup with Specific Language" example + - Added Language Migration section explaining the change from transcription.language +- Typecheck passes \ No newline at end of file diff --git a/tasks/prd.jsonc b/tasks/prd.jsonc index 9225297..ec2e557 100644 --- a/tasks/prd.jsonc +++ b/tasks/prd.jsonc @@ -200,7 +200,7 @@ "Override behavior documented", "Typecheck passes" ], - "passes": false + "passes": true }, { "title": "Add migration for existing configs",