Voice Mode

# Whisper Speech-to-Text Service Local speech recognition service that converts audio to text for voice-mode using OpenAI's Whisper model. ## Quick Start ```bash # Install and configure whisper service voice-mode whisper install # List available models and their status voice-mode whisper models # Download a specific model voice-mode whisper model install large-v2 # Set the active model voice-mode whisper model active large-v2 # Start the service voice-mode whisper start ``` Default endpoint: `http://127.0.0.1:2022/v1` ## Install ### macOS ```bash # Install whisper.cpp brew install whisper.cpp # Download model mkdir -p ~/.voicemode/models/whisper cd ~/.voicemode/models/whisper curl -LO https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v2.bin ``` ### Linux ```bash # Clone and build whisper.cpp git clone https://github.com/ggerganov/whisper.cpp cd whisper.cpp make # Download model mkdir -p ~/.voicemode/models/whisper cd ~/.voicemode/models/whisper wget https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v2.bin ``` ## Model Management Voice Mode provides comprehensive model management commands: ### List Available Models ```bash voice-mode whisper models ``` Shows all available Whisper models with: - Installation status (✓ Installed or Download) - Model sizes - Language support (English only or Multilingual) - Currently selected model (highlighted with →) ### Show/Set Active Model ```bash # Show current active model voice-mode whisper model active # Set a different model as active voice-mode whisper model active small.en ``` Note: After changing the active model, restart the whisper service for changes to take effect. ### Install Models ```bash # Install default model (large-v2) voice-mode whisper model install # Install specific model voice-mode whisper model install medium # Install all available models voice-mode whisper model install all # Force re-download voice-mode whisper model install large-v3 --force # Skip Core ML conversion on Apple Silicon voice-mode whisper model install large-v2 --skip-core-ml ``` ### Remove Models ```bash # Remove a specific model voice-mode whisper model remove tiny # Remove without confirmation voice-mode whisper model remove tiny.en --force ``` ### Available Models - **tiny** (39 MB) - Fastest, least accurate - **tiny.en** (39 MB) - Fastest English model - **base** (142 MB) - Good balance of speed and accuracy - **base.en** (142 MB) - Good English model - **small** (466 MB) - Better accuracy, slower - **small.en** (466 MB) - Better English accuracy - **medium** (1.5 GB) - High accuracy, slow - **medium.en** (1.5 GB) - High English accuracy - **large-v1** (2.9 GB) - Original large model - **large-v2** (2.9 GB) - Improved large model (recommended) - **large-v3** (3.1 GB) - Latest large model - **large-v3-turbo** (1.6 GB) - Faster large model with good accuracy ## Configure Environment variables in `~/.voicemode/voicemode.env`: ```bash VOICEMODE_WHISPER_MODEL=large-v2 VOICEMODE_WHISPER_PORT=2022 VOICEMODE_WHISPER_LANGUAGE=auto VOICEMODE_WHISPER_MODEL_PATH=~/.voicemode/models/whisper ``` ### LaunchAgent (macOS) Create `~/Library/LaunchAgents/com.voicemode.whisper.plist`: ```xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.voicemode.whisper</string> <key>ProgramArguments</key> <array> <string>/opt/homebrew/bin/whisper-server</string> <string>--host</string> <string>0.0.0.0</string> <string>--port</string> <string>2022</string> <string>--model</string> <string>/Users/YOUR_USERNAME/.voicemode/models/whisper/ggml-large-v2.bin</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> </dict> </plist> ``` ### Systemd Service (Linux) Create `~/.config/systemd/user/whisper.service`: ```ini [Unit] Description=Whisper Speech-to-Text Service After=network.target [Service] Type=simple ExecStart=/usr/local/bin/whisper-server \ --host 0.0.0.0 \ --port 2022 \ --model %h/.voicemode/models/whisper/ggml-large-v2.bin Restart=always RestartSec=10 [Install] WantedBy=default.target ``` ## Control ### macOS Commands ```bash # Start service launchctl load ~/Library/LaunchAgents/com.voicemode.whisper.plist # Stop service launchctl unload ~/Library/LaunchAgents/com.voicemode.whisper.plist # Restart service launchctl unload ~/Library/LaunchAgents/com.voicemode.whisper.plist launchctl load ~/Library/LaunchAgents/com.voicemode.whisper.plist # Enable at startup launchctl load -w ~/Library/LaunchAgents/com.voicemode.whisper.plist # Disable at startup launchctl unload -w ~/Library/LaunchAgents/com.voicemode.whisper.plist # Check status launchctl list | grep whisper ``` ### Linux Commands ```bash # Start service systemctl --user start whisper # Stop service systemctl --user stop whisper # Restart service systemctl --user restart whisper # Enable at startup systemctl --user enable whisper # Disable at startup systemctl --user disable whisper # Check status systemctl --user status whisper # View logs journalctl --user -u whisper -f ``` ## Troubleshooting ### Service won't start - Check if port 2022 is already in use: `lsof -i :2022` - Verify model file exists at configured path - Check logs for error messages ### Poor transcription quality - Try a larger model (base → small → medium → large) - Ensure audio input quality is good - Set specific language instead of 'auto' if known ### High CPU usage - Use a smaller model for better performance - Consider using GPU acceleration if available