feat: better configuration
This commit is contained in:
leonardotrapani
+432
@@ -0,0 +1,432 @@
|
||||
# Configuration Reference
|
||||
|
||||
This document covers manual configuration of hyprvoice via the `config.toml` file. For most users, the interactive wizard is recommended:
|
||||
|
||||
```bash
|
||||
hyprvoice configure
|
||||
```
|
||||
|
||||
Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are applied immediately without restarting the daemon.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Unified Provider System](#unified-provider-system)
|
||||
- [Transcription Providers](#transcription-providers)
|
||||
- [LLM Post-Processing](#llm-post-processing)
|
||||
- [Keywords](#keywords)
|
||||
- [Recording Configuration](#recording-configuration)
|
||||
- [Text Injection](#text-injection)
|
||||
- [Notifications](#notifications)
|
||||
- [Example Configurations](#example-configurations)
|
||||
- [Migration from Old Config Format](#migration-from-old-config-format)
|
||||
|
||||
## Unified Provider System
|
||||
|
||||
Hyprvoice uses a unified provider system where API keys are configured once and shared between transcription and LLM features:
|
||||
|
||||
```toml
|
||||
# Configure API keys for providers you want to use
|
||||
[providers.openai]
|
||||
api_key = "sk-..." # Or set OPENAI_API_KEY env var
|
||||
|
||||
[providers.groq]
|
||||
api_key = "gsk_..." # Or set GROQ_API_KEY env var
|
||||
|
||||
[providers.mistral]
|
||||
api_key = "..." # Or set MISTRAL_API_KEY env var
|
||||
|
||||
[providers.elevenlabs]
|
||||
api_key = "..." # Or set ELEVENLABS_API_KEY env var
|
||||
```
|
||||
|
||||
**API key resolution order:**
|
||||
|
||||
1. `[providers.X]` section in config
|
||||
2. Environment variable (`OPENAI_API_KEY`, `GROQ_API_KEY`, etc.)
|
||||
|
||||
## Transcription Providers
|
||||
|
||||
Hyprvoice supports multiple transcription backends:
|
||||
|
||||
### OpenAI Whisper API
|
||||
|
||||
Cloud-based transcription using OpenAI's Whisper API:
|
||||
|
||||
```toml
|
||||
[transcription]
|
||||
provider = "openai"
|
||||
language = "" # Empty for auto-detect, or "en", "es", "fr", etc.
|
||||
model = "whisper-1"
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- High-quality transcription
|
||||
- Supports 50+ languages
|
||||
- Auto-detection or specify language for better accuracy
|
||||
|
||||
### Groq Whisper API (Transcription)
|
||||
|
||||
Fast cloud-based transcription using Groq's Whisper API:
|
||||
|
||||
```toml
|
||||
[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
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Ultra-fast transcription (significantly faster than OpenAI)
|
||||
- Same Whisper model quality
|
||||
- Supports 50+ languages
|
||||
- Free tier available with generous limits
|
||||
|
||||
### Groq Translation API
|
||||
|
||||
Fast translation of audio to English using Groq's Whisper API:
|
||||
|
||||
```toml
|
||||
[transcription]
|
||||
provider = "groq-translation"
|
||||
language = "es" # Optional: hint source language for better accuracy
|
||||
model = "whisper-large-v3"
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Translates any language audio → English text
|
||||
- Ultra-fast processing
|
||||
- Language field hints at source language (improves accuracy)
|
||||
- Always outputs English regardless of input language
|
||||
|
||||
### Mistral Voxtral
|
||||
|
||||
Transcription using Mistral's Voxtral API, excellent for European languages:
|
||||
|
||||
```toml
|
||||
[transcription]
|
||||
provider = "mistral-transcription"
|
||||
language = ""
|
||||
model = "voxtral-mini-latest" # Or "voxtral-mini-2507"
|
||||
```
|
||||
|
||||
### ElevenLabs Scribe
|
||||
|
||||
Transcription using ElevenLabs' Scribe API with 99 language support:
|
||||
|
||||
```toml
|
||||
[transcription]
|
||||
provider = "elevenlabs"
|
||||
language = ""
|
||||
model = "scribe_v1" # Or "scribe_v2" for real-time, lower latency
|
||||
```
|
||||
|
||||
## LLM Post-Processing
|
||||
|
||||
LLM post-processing is **enabled by default** and significantly improves transcription quality. After transcription, the text is processed by an LLM to:
|
||||
|
||||
- Remove stutters and repeated words ("I I I want" → "I want")
|
||||
- Add proper punctuation
|
||||
- Fix grammar errors
|
||||
- Remove filler words ("um", "uh", "like", "you know", etc.)
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```toml
|
||||
[llm]
|
||||
enabled = true # Disable with false if you want raw transcriptions
|
||||
provider = "openai" # "openai" or "groq"
|
||||
model = "gpt-4o-mini" # OpenAI: "gpt-4o-mini", Groq: "llama-3.3-70b-versatile"
|
||||
```
|
||||
|
||||
### Post-Processing Options
|
||||
|
||||
All options are enabled by default. Disable specific ones as needed:
|
||||
|
||||
```toml
|
||||
[llm.post_processing]
|
||||
remove_stutters = true # "I I I want" → "I want"
|
||||
add_punctuation = true # Adds periods, commas, etc.
|
||||
fix_grammar = true # Fixes grammatical errors
|
||||
remove_filler_words = true # Removes "um", "uh", "like", "you know"
|
||||
```
|
||||
|
||||
### Custom Prompts
|
||||
|
||||
Add custom instructions for specific use cases:
|
||||
|
||||
```toml
|
||||
[llm.custom_prompt]
|
||||
enabled = true
|
||||
prompt = "Format as bullet points"
|
||||
```
|
||||
|
||||
**Use cases for custom prompts:**
|
||||
|
||||
- "Format as bullet points" - for note-taking
|
||||
- "Keep technical terms exactly as spoken" - for programming dictation
|
||||
- "Use formal language" - for professional documents
|
||||
- "Translate to Spanish" - for translation workflows
|
||||
|
||||
### LLM Provider Recommendations
|
||||
|
||||
| Provider | Model | Best For |
|
||||
| -------- | ----------------------- | ----------------------------------- |
|
||||
| OpenAI | gpt-4o-mini | Best quality/cost balance (default) |
|
||||
| Groq | llama-3.3-70b-versatile | Fastest processing, free tier |
|
||||
|
||||
## Keywords
|
||||
|
||||
Keywords help both transcription and LLM understand domain-specific terms, names, and technical vocabulary:
|
||||
|
||||
```toml
|
||||
keywords = ["Hyprland", "Wayland", "PipeWire", "Claude", "TypeScript"]
|
||||
```
|
||||
|
||||
**How keywords work:**
|
||||
|
||||
- **Transcription**: Passed as initial_prompt to Whisper, improving recognition of these terms
|
||||
- **LLM**: Included in the system prompt to ensure correct spelling
|
||||
|
||||
**When to use keywords:**
|
||||
|
||||
- Names of people, companies, or products
|
||||
- Technical terminology specific to your field
|
||||
- Acronyms or abbreviations
|
||||
- Words commonly misheard by speech-to-text
|
||||
|
||||
## Recording Configuration
|
||||
|
||||
Audio capture settings:
|
||||
|
||||
```toml
|
||||
[recording]
|
||||
sample_rate = 16000 # Audio sample rate in Hz (16000 recommended for speech)
|
||||
channels = 1 # Number of audio channels (1 = mono, 2 = stereo)
|
||||
format = "s16" # Audio format (s16 = 16-bit signed integers)
|
||||
buffer_size = 8192 # Internal buffer size in bytes (larger = less CPU, more latency)
|
||||
device = "" # PipeWire device name (empty = default microphone)
|
||||
channel_buffer_size = 30 # Audio frame buffer size (frames to buffer)
|
||||
timeout = "5m" # Maximum recording duration (e.g., "30s", "2m", "5m")
|
||||
```
|
||||
|
||||
### Recording Timeout
|
||||
|
||||
- Prevents accidental long recordings that could consume resources
|
||||
- Default: 5 minutes (`"5m"`)
|
||||
- Format: Go duration strings like `"30s"`, `"2m"`, `"10m"`
|
||||
- Recording automatically stops when timeout is reached
|
||||
|
||||
## Text Injection
|
||||
|
||||
Configurable text injection with multiple backends:
|
||||
|
||||
```toml
|
||||
[injection]
|
||||
backends = ["ydotool", "wtype", "clipboard"] # Ordered fallback chain
|
||||
ydotool_timeout = "5s"
|
||||
wtype_timeout = "5s"
|
||||
clipboard_timeout = "3s"
|
||||
```
|
||||
|
||||
### Injection Backends
|
||||
|
||||
- **`ydotool`**: Uses ydotool (requires `ydotoold` daemon for ydotool v1.0.0+). Most compatible with Chromium/Electron apps.
|
||||
- **`wtype`**: Uses wtype for Wayland. May have issues with some Chromium-based apps (known upstream bug).
|
||||
- **`clipboard`**: Copies text to clipboard only. Most reliable, but requires manual paste.
|
||||
|
||||
### Fallback Chain
|
||||
|
||||
Backends are tried in order. The first successful one wins. Example configurations:
|
||||
|
||||
```toml
|
||||
# Clipboard only (safest, always works)
|
||||
backends = ["clipboard"]
|
||||
|
||||
# wtype with clipboard fallback
|
||||
backends = ["wtype", "clipboard"]
|
||||
|
||||
# Full fallback chain (default) - best compatibility
|
||||
backends = ["ydotool", "wtype", "clipboard"]
|
||||
|
||||
# ydotool only (if you have it set up)
|
||||
backends = ["ydotool"]
|
||||
```
|
||||
|
||||
### ydotool Setup
|
||||
|
||||
ydotool requires the `ydotoold` daemon running (for ydotool v1.0.0+) and access to `/dev/uinput`:
|
||||
|
||||
```bash
|
||||
# Start ydotool daemon (systemd)
|
||||
systemctl --user enable --now ydotool
|
||||
|
||||
# Or add user to input group
|
||||
sudo usermod -aG input $USER
|
||||
# Then logout/login
|
||||
|
||||
# For Hyprland, add to config to set correct keyboard layout:
|
||||
# device:ydotoold-virtual-device {
|
||||
# kb_layout = us
|
||||
# }
|
||||
```
|
||||
|
||||
## Notifications
|
||||
|
||||
Desktop notification settings:
|
||||
|
||||
```toml
|
||||
[notifications]
|
||||
enabled = true # Enable/disable notifications
|
||||
type = "desktop" # "desktop", "log", or "none"
|
||||
```
|
||||
|
||||
### Notification Types
|
||||
|
||||
- **`desktop`**: Use notify-send for desktop notifications
|
||||
- **`log`**: Log messages to console only
|
||||
- **`none`**: Disable all notifications
|
||||
|
||||
### Custom Notification Messages
|
||||
|
||||
You can customize notification text via the `[notifications.messages]` section:
|
||||
|
||||
```toml
|
||||
[notifications.messages]
|
||||
[notifications.messages.recording_started]
|
||||
title = "Hyprvoice"
|
||||
body = "Recording Started"
|
||||
[notifications.messages.transcribing]
|
||||
title = "Hyprvoice"
|
||||
body = "Recording Ended... Transcribing"
|
||||
[notifications.messages.llm_processing]
|
||||
title = "Hyprvoice"
|
||||
body = "Processing..."
|
||||
[notifications.messages.config_reloaded]
|
||||
title = "Hyprvoice"
|
||||
body = "Config Reloaded"
|
||||
[notifications.messages.operation_cancelled]
|
||||
title = "Hyprvoice"
|
||||
body = "Operation Cancelled"
|
||||
[notifications.messages.recording_aborted]
|
||||
body = "Recording Aborted"
|
||||
[notifications.messages.injection_aborted]
|
||||
body = "Injection Aborted"
|
||||
```
|
||||
|
||||
**Emoji-only example** (for minimal pill-style notifications):
|
||||
|
||||
```toml
|
||||
[notifications.messages.recording_started]
|
||||
title = ""
|
||||
body = "🎙️"
|
||||
```
|
||||
|
||||
## Example Configurations
|
||||
|
||||
### Fast Transcription Only (No LLM)
|
||||
|
||||
```toml
|
||||
[providers.groq]
|
||||
api_key = "gsk_..."
|
||||
|
||||
[transcription]
|
||||
provider = "groq-transcription"
|
||||
model = "whisper-large-v3-turbo"
|
||||
|
||||
[llm]
|
||||
enabled = false
|
||||
```
|
||||
|
||||
### High Quality with OpenAI (Default)
|
||||
|
||||
```toml
|
||||
[providers.openai]
|
||||
api_key = "sk-..."
|
||||
|
||||
[transcription]
|
||||
provider = "openai"
|
||||
model = "whisper-1"
|
||||
|
||||
[llm]
|
||||
enabled = true
|
||||
provider = "openai"
|
||||
model = "gpt-4o-mini"
|
||||
```
|
||||
|
||||
### Budget-Friendly with Groq
|
||||
|
||||
```toml
|
||||
[providers.groq]
|
||||
api_key = "gsk_..."
|
||||
|
||||
[transcription]
|
||||
provider = "groq-transcription"
|
||||
model = "whisper-large-v3-turbo"
|
||||
|
||||
[llm]
|
||||
enabled = true
|
||||
provider = "groq"
|
||||
model = "llama-3.3-70b-versatile"
|
||||
```
|
||||
|
||||
### Mixed Providers (Groq Transcription + OpenAI LLM)
|
||||
|
||||
```toml
|
||||
[providers.openai]
|
||||
api_key = "sk-..."
|
||||
|
||||
[providers.groq]
|
||||
api_key = "gsk_..."
|
||||
|
||||
[transcription]
|
||||
provider = "groq-transcription"
|
||||
model = "whisper-large-v3-turbo"
|
||||
|
||||
[llm]
|
||||
enabled = true
|
||||
provider = "openai"
|
||||
model = "gpt-4o-mini"
|
||||
```
|
||||
|
||||
## Migration from Old Config Format
|
||||
|
||||
If you're upgrading from an older version with `transcription.api_key`:
|
||||
|
||||
**Old format (still works):**
|
||||
|
||||
```toml
|
||||
[transcription]
|
||||
provider = "openai"
|
||||
api_key = "sk-..." # Legacy location
|
||||
model = "whisper-1"
|
||||
```
|
||||
|
||||
**New format (recommended):**
|
||||
|
||||
```toml
|
||||
[providers.openai]
|
||||
api_key = "sk-..." # Unified location
|
||||
|
||||
[transcription]
|
||||
provider = "openai"
|
||||
model = "whisper-1"
|
||||
|
||||
[llm]
|
||||
enabled = true
|
||||
provider = "openai"
|
||||
model = "gpt-4o-mini"
|
||||
```
|
||||
|
||||
Run `hyprvoice configure` to interactively update your config to the new format.
|
||||
|
||||
## Configuration Hot-Reloading
|
||||
|
||||
The daemon automatically watches the config file for changes and applies them immediately:
|
||||
|
||||
- **Notification settings**: Applied instantly
|
||||
- **Injection settings**: Applied to current and future operations
|
||||
- **Recording/Transcription/LLM settings**: Applied to new recording sessions
|
||||
- **Invalid configs**: Rejected with error notification, daemon continues with previous config
|
||||
Reference in New Issue
Block a user