{"id":50493450,"url":"https://github.com/AgenticToaster/whisprd","last_synced_at":"2026-06-18T22:00:47.858Z","repository":{"id":300495058,"uuid":"1006242105","full_name":"AgenticToaster/whisprd","owner":"AgenticToaster","description":"A powerful, real-time dictation system for Linux","archived":false,"fork":false,"pushed_at":"2025-06-22T01:49:20.000Z","size":600,"stargazers_count":6,"open_issues_count":4,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T10:46:04.411Z","etag":null,"topics":["dictation","linux","speech-to-text","whisper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgenticToaster.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-21T20:11:29.000Z","updated_at":"2026-01-28T20:05:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"e5b1e1a6-b81d-4c51-befb-d236d7ea14d5","html_url":"https://github.com/AgenticToaster/whisprd","commit_stats":null,"previous_names":["agentictoaster/whisprd"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AgenticToaster/whisprd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenticToaster%2Fwhisprd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenticToaster%2Fwhisprd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenticToaster%2Fwhisprd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenticToaster%2Fwhisprd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgenticToaster","download_url":"https://codeload.github.com/AgenticToaster/whisprd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenticToaster%2Fwhisprd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34508867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dictation","linux","speech-to-text","whisper"],"created_at":"2026-06-02T05:00:36.702Z","updated_at":"2026-06-18T22:00:47.849Z","avatar_url":"https://github.com/AgenticToaster.png","language":"Python","funding_links":[],"categories":["By Platform"],"sub_categories":["Linux"],"readme":"# whisprd\n\n![alt text](whisprd_small.png)\n\n**Real-time Whisper-powered dictation system for Linux**\nA powerful, real-time dictation system for Linux that uses OpenAI's Whisper model to convert speech to text and inject keystrokes into any application. Whisprd provides Windows-like dictation functionality with voice commands, auto-punctuation, and low-latency transcription.\n\nFYI this is a personal project by [@AgenticToaster](https://github.com/AgenticToaster) - built to solve a specific problem I had with dictation. This is not a business or community project, just something I found helpful and wanted to share.\n\n## What This Is\n\n- **Personal Project**: Built by me, for me, shared with you\n- **Problem Solver**: Created to address my own dictation needs\n- **Open Source**: Feel free to use, modify, or take ownership\n- **Low Maintenance**: I'll update when I can, but it's not my top priority\n\n## Contributing\n\n**You're welcome to contribute!** But please understand:\n\n- This is a **personal project**, not a community-driven one\n- I may not respond quickly to issues or PRs\n- Feel free to fork and take ownership if you want to maintain it actively\n- Don't be a jerk - I'm sharing this to help others, not to start a business\n\nIf you find this useful and want to keep it updated, consider:\n- Forking the repository and maintaining your own version\n- Submitting PRs (I'll review when I can)\n- Taking over maintenance if you're passionate about it\n\n## Features\n\n- **Real-time Speech Recognition**: Uses faster-whisper for GPU-accelerated transcription\n- **CUDA GPU Support**: Automatic GPU acceleration with fallback to CPU\n- **Voice Commands**: Customizable voice commands for text editing and system control\n- **Keystroke Injection**: Low-latency input injection using uinput\n- **Auto-punctuation**: Automatic punctuation insertion based on voice cues\n- **Global Hotkey**: Toggle dictation with Ctrl+Alt+D (configurable)\n- **Command Mode**: Say \"computer\" to activate command mode for special actions\n- **System Integration**: Systemd service for auto-start and daemon mode\n- **Rich CLI**: Beautiful terminal interface with real-time status and statistics\n- **Configuration**: YAML-based configuration for easy customization\n- **Transcript Logging**: Save all transcriptions to file for review\n- **Pause Duration Control**: Configurable silence detection for utterance boundaries\n- **Alternate Prompts**: Load custom prompts from YAML files for different use cases\n\n## GUI Interface\n\nWhisprd now includes a modern DearPyGui-based graphical interface for easy control and configuration:\n\n- **Modern DearPyGui Interface**: Fast, cross-platform GUI with automatic HiDPI/fractional scaling support\n- **Control Panel**: Start/stop engine, toggle dictation, pause/resume with visual buttons\n- **Status Panel**: Real-time engine status, queue sizes, and statistics display\n- **Transcription Panel**: Live transcription display with historical view and save functionality\n- **Configuration Panel**: 6 organized tabs for all settings (Audio, Whisper, Whisprd, Commands, Output, Performance)\n- **Auto-scaling**: Automatically detects and adapts to your display scaling (including fractional scaling on 4K displays)\n- **Manual Scaling**: Override with `--scale` or adjust auto-scaling multiplier with `--auto-scale-multiplier`\n\n### GUI Usage\n\n```bash\n# Launch the GUI\nwhisprd-gui\n\n# Or directly\npython3 whisprd_gui.py\n\n# Demo mode (no engine required)\npython3 demo_gui.py\n\n# With custom scaling\nwhisprd-gui --scale 1.5\nwhisprd-gui --auto-scale-multiplier 1.15\n```\n\nThe GUI provides the same functionality as the CLI but with an intuitive visual interface and real-time status updates.\n\n## Use Cases\n\n- **Document Writing**: Dictate emails, documents, and notes\n- **Programming**: Voice code with custom commands\n- **Accessibility**: Assist users with typing difficulties\n- **Productivity**: Faster text input for power users\n- **Multilingual**: Support for multiple languages via Whisper\n- **Professional Use**: Business, medical, legal, and technical transcription\n- **Creative Writing**: Storytelling, poetry, and dialogue transcription\n\n## Requirements\n\n### System Requirements\n- Linux (tested on Ubuntu 20.04+, Fedora, Arch)\n- Python 3.8+\n- PulseAudio or PipeWire\n- Microphone access\n- GPU (optional, for faster transcription)\n\n### Hardware Requirements\n- Microphone (USB or built-in)\n- Sufficient RAM (4GB+ recommended)\n- GPU with CUDA support (optional, for faster-whisper)\n\n## Installation\n\n### Quick Install\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/yourusername/whisprd.git\n   cd whisprd\n   ```\n\n2. **Run the installer**:\n   ```bash\n   ./install.sh\n   ```\n\n3. **Follow the post-install instructions**:\n   - Log out and back in for group permissions\n   - Load uinput module: `sudo modprobe uinput`\n   - Test the system: `/opt/whisprd/whisprd_cli.py`\n\n### Manual Installation\n\n1. **Install dependencies**:\n   ```bash\n   pip3 install --user -r requirements.txt\n   ```\n\n2. **Setup permissions**:\n   ```bash\n   sudo usermod -a -G input,audio $USER\n   sudo modprobe uinput\n   echo 'KERNEL==\"uinput\", MODE=\"0660\", GROUP=\"input\"' | sudo tee /etc/udev/rules.d/99-uinput.rules\n   sudo udevadm control --reload-rules\n   ```\n\n3. **Copy files**:\n   ```bash\n   sudo mkdir -p /opt/whisprd\n   sudo cp -r whisprd/ /opt/whisprd/\n   sudo cp whisprd_cli.py config.yaml requirements.txt /opt/whisprd/\n   sudo chown -R $USER:$USER /opt/whisprd\n   sudo chmod +x /opt/whisprd/whisprd_cli.py\n   ```\n\n## Usage\n\n### Basic Usage\n\n1. **Start the system**:\n   ```bash\n   /opt/whisprd/whisprd_cli.py\n   ```\n\n2. **Toggle dictation**: Press `Ctrl+Alt+D`\n\n3. **Start speaking**: The system will transcribe your speech in real-time\n\n4. **Use voice commands**: Say commands like \"new line\", \"backspace\", \"period\"\n\n### Voice Commands\n\n#### Navigation Commands\n- `\"new line\"` - Insert newline\n- `\"new paragraph\"` - Insert double newline\n- `\"backspace\"` - Delete last character\n- `\"delete word\"` - Delete last word\n- `\"delete line\"` - Delete entire line\n\n#### Punctuation Commands\n- `\"period\"` - Insert period\n- `\"comma\"` - Insert comma\n- `\"question mark\"` - Insert question mark\n- `\"exclamation mark\"` - Insert exclamation mark\n- `\"semicolon\"` - Insert semicolon\n- `\"colon\"` - Insert colon\n- `\"open parenthesis\"` - Insert (\n- `\"close parenthesis\"` - Insert )\n- `\"quote\"` - Insert single quote\n- `\"double quote\"` - Insert double quote\n\n#### Text Formatting Commands\n- `\"capitalize\"` - Capitalize selected text\n- `\"select all\"` - Select all text\n- `\"copy\"` - Copy selected text\n- `\"paste\"` - Paste from clipboard\n- `\"cut\"` - Cut selected text\n- `\"undo\"` - Undo last action\n- `\"redo\"` - Redo last action\n\n#### System Commands\n- `\"stop dictation\"` - Stop dictation\n- `\"start dictation\"` - Start dictation\n- `\"clear text\"` - Clear all text\n\n### Command Mode\n\nSay `\"computer\"` to activate command mode, then speak your command:\n\n```\n\"computer new line\" → Inserts newline\n\"computer select all\" → Selects all text\n\"computer copy\" → Copies selected text\n```\n\n### Auto-punctuation\n\nThe system automatically detects punctuation words:\n- Say `\"period\"` or `\"full stop\"` → inserts .\n- Say `\"comma\"` or `\"pause\"` → inserts ,\n- Say `\"question mark\"` → inserts ?\n\n## Configuration\n\nEdit `~/.config/whisprd/config.yaml` to customize the system:\n\n### Audio Settings\n```yaml\naudio:\n  sample_rate: 16000        # Audio sample rate in Hz\n  channels: 1               # Number of audio channels (1 for mono)\n  buffer_size: 8000         # Audio buffer size in samples (0.5s at 16kHz)\n  device: null              # Audio device (null = default device)\n```\n\n### Whisper Settings\n```yaml\nwhisper:\n  model_size: \"small\"       # Model size: tiny, base, small, medium, large\n  language: \"en\"            # Language code (en, es, fr, de, etc.)\n  beam_size: 5              # Beam search size for better accuracy\n  best_of: 5                # Number of candidates to consider\n  temperature: 0.0          # Sampling temperature (0.0 = deterministic)\n  condition_on_previous_text: false  # Use previous text as context\n  initial_prompt: \"Transcribe only what you hear...\"  # Initial prompt for Whisper\n  \n  # GPU/CUDA settings\n  use_cuda: true            # Enable CUDA GPU acceleration (auto-fallback to CPU)\n  cuda_device: 0            # CUDA device index (0 for first GPU)\n  \n  # Alternate prompts configuration\n  alternate_prompts_file: null  # Path to YAML file with alternate prompts\n  use_alternate_prompts: false  # Enable to use prompts from file\n```\n\n### Dictation Settings\n```yaml\nwhisprd:\n  toggle_hotkey: [\"ctrl\", \"shift\", \"d\"]  # Hotkey to toggle dictation\n  command_mode_word: \"computer\"          # Word to activate command mode\n  confidence_threshold: 0.8              # Minimum confidence for transcription\n  auto_punctuation: true                 # Enable auto-punctuation\n  \n  # Auto-punctuation word mappings\n  sentence_end_words: [\"period\", \"full stop\", \"dot\"]\n  comma_words: [\"comma\", \"pause\"]\n  question_words: [\"question mark\", \"question\"]\n  \n  # Pause duration settings\n  pause_duration: 1.0                    # Seconds of silence to trigger utterance boundary\n  min_utterance_duration: 0.7            # Minimum utterance length to transcribe\n  overlap_duration: 0.2                  # Seconds to keep as overlap between utterances\n```\n\n### Voice Commands\n```yaml\ncommands:\n  # Navigation commands\n  \"new line\": \"KEY_ENTER\"\n  \"new paragraph\": \"KEY_ENTER,KEY_ENTER\"\n  \"backspace\": \"KEY_BACKSPACE\"\n  \"delete word\": \"KEY_CTRL+KEY_BACKSPACE\"\n  \"delete line\": \"KEY_CTRL+KEY_A,KEY_DELETE\"\n  \n  # Punctuation commands\n  \"period\": \"KEY_DOT\"\n  \"comma\": \"KEY_COMMA\"\n  \"question mark\": \"KEY_LEFTSHIFT+KEY_SLASH\"\n  \"exclamation mark\": \"KEY_LEFTSHIFT+KEY_1\"\n  \n  # Text formatting commands\n  \"capitalize\": \"KEY_CTRL+KEY_A,KEY_CTRL+KEY_U\"\n  \"select all\": \"KEY_CTRL+KEY_A\"\n  \"copy\": \"KEY_CTRL+KEY_C\"\n  \"paste\": \"KEY_CTRL+KEY_V\"\n  \"cut\": \"KEY_CTRL+KEY_X\"\n  \"undo\": \"KEY_CTRL+KEY_Z\"\n  \"redo\": \"KEY_CTRL+KEY_Y\"\n  \n  # System commands\n  \"stop dictation\": \"STOP_DICTATION\"\n  \"start dictation\": \"START_DICTATION\"\n  \"clear text\": \"KEY_CTRL+KEY_A,KEY_DELETE\"\n```\n\n### Output Settings\n```yaml\noutput:\n  save_to_file: true                    # Save transcriptions to file\n  transcript_file: \"~/whisprd_transcript.txt\"  # Transcript file path\n  console_output: true                  # Show transcriptions in console\n  inject_keystrokes: true               # Inject keystrokes into applications\n```\n\n### Performance Settings\n```yaml\nperformance:\n  transcription_threads: 2              # Number of transcription worker threads\n  audio_buffer_seconds: 1.0             # Audio buffer size in seconds\n  max_latency: 2.0                      # Maximum transcription latency in seconds\n  gpu_memory_fraction: 0.8              # Fraction of GPU memory to use (0.0-1.0)\n  enable_memory_efficient_attention: true  # Use memory-efficient attention for large models\n```\n\n### Alternate Prompts Configuration\n\nCreate a YAML file with different prompts for various use cases:\n\n```yaml\n# whisprd_prompts.yaml\ngeneral:\n  default: \"Transcribe only what you hear...\"\n  formal: \"Transcribe the spoken words accurately. Use formal language...\"\n\nprofessional:\n  business: \"Transcribe business communication. Use professional language...\"\n  technical: \"Transcribe technical content. Preserve technical terms...\"\n  medical: \"Transcribe medical terminology. Maintain accuracy...\"\n\ncreative:\n  storytelling: \"Transcribe storytelling content. Maintain narrative flow...\"\n  poetry: \"Transcribe poetic content. Preserve rhythm and structure...\"\n```\n\nThen enable in config.yaml:\n```yaml\nwhisper:\n  use_alternate_prompts: true\n  alternate_prompts_file: \"~/whisprd_prompts.yaml\"\n```\n\n## GPU Acceleration\n\nWhisprd supports CUDA GPU acceleration for faster transcription:\n\n### CUDA Requirements\n- NVIDIA GPU with CUDA support\n- CUDA drivers installed\n- PyTorch with CUDA support\n\n### Installation with CUDA Support\n```bash\n# Install with CUDA support\nuv sync --extra cuda\n\n# Or install PyTorch with CUDA manually\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118\n```\n\n### CUDA Configuration\n```yaml\nwhisper:\n  use_cuda: true            # Enable CUDA (auto-fallback to CPU if not available)\n  cuda_device: 0            # Use first GPU (change for multi-GPU systems)\n```\n\n### Automatic Fallback\n- If CUDA is not available, Whisprd automatically falls back to CPU\n- No configuration changes needed\n- Logs will indicate which device is being used\n\n### Performance Tips\n- Use `model_size: \"small\"` or `\"medium\"` for best GPU performance\n- Adjust `gpu_memory_fraction` based on your GPU memory\n- Enable `enable_memory_efficient_attention` for large models\n\n## Advanced Usage\n\n### Daemon Mode\n\nRun as a background service:\n```bash\n/opt/whisprd/whisprd_cli.py --daemon\n```\n\n### Systemd Service\n\nEnable auto-start:\n```bash\nsystemctl --user enable whisprd\nsystemctl --user start whisprd\n```\n\n### Custom Commands\n\nAdd custom voice commands in the configuration:\n```yaml\ncommands:\n  \"save document\": \"KEY_CTRL+KEY_S\"\n  \"open file\": \"KEY_CTRL+KEY_O\"\n  \"find text\": \"KEY_CTRL+KEY_F\"\n  \"bold text\": \"KEY_CTRL+KEY_B\"\n  \"italic text\": \"KEY_CTRL+KEY_I\"\n```\n\n### Multiple Languages\n\nChange the language in config.yaml:\n```yaml\nwhisper:\n  language: \"es\"  # Spanish\n  # or \"fr\" for French, \"de\" for German, etc.\n```\n\n### Pause Duration Tuning\n\nAdjust pause duration for your speaking style:\n```yaml\nwhisprd:\n  pause_duration: 1.5        # Longer pause for slower speakers\n  min_utterance_duration: 0.5  # Shorter minimum for quick phrases\n  overlap_duration: 0.3      # More overlap for better context\n```\n\n### Professional Prompts\n\nUse specialized prompts for different domains:\n```yaml\n# In whisprd_prompts.yaml\nprofessional:\n  legal: \"Transcribe legal content. Preserve legal terminology...\"\n  medical: \"Transcribe medical terminology. Maintain accuracy...\"\n  technical: \"Transcribe technical content. Preserve technical terms...\"\n```\n\n## Monitoring\n\n### CLI Status\nThe interactive CLI shows real-time status:\n- Engine status\n- Dictation state\n- Audio queue size\n- Transcription statistics\n- Error count\n\n### Logs\nView system logs:\n```bash\njournalctl --user -u whisprd -f\n```\n\n### Transcripts\nAll transcriptions are saved to:\n```\n~/.local/share/whisprd/whisprd_transcript.txt\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Permission denied\" for uinput**:\n   ```bash\n   sudo usermod -a -G input $USER\n   sudo modprobe uinput\n   # Log out and back in\n   ```\n\n2. **No audio input detected**:\n   ```bash\n   # Check audio devices\n   pactl list short sources\n   \n   # Test microphone\n   arecord -d 5 test.wav\n   ```\n\n3. **Whisper model not loading**:\n   ```bash\n   # Check GPU support\n   nvidia-smi\n   \n   # Use CPU-only mode\n   # Edit config.yaml: model_size: \"tiny\"\n   ```\n\n4. **Hotkey not working**:\n   ```bash\n   # Check if another application uses the hotkey\n   # Change hotkey in config.yaml\n   ```\n\n5. **Poor transcription quality**:\n   ```bash\n   # Adjust pause duration\n   # Edit config.yaml: pause_duration: 1.5\n   \n   # Use larger model\n   # Edit config.yaml: model_size: \"medium\"\n   ```\n\n6. **Alternate prompts not loading**:\n   ```bash\n   # Check file path\n   # Ensure use_alternate_prompts: true\n   # Verify YAML syntax in prompts file\n   ```\n\n### Debug Mode\n\nRun with verbose logging:\n```bash\n/opt/whisprd/whisprd_cli.py --verbose\n```\n\n### Testing Components\n\nTest individual components:\n```bash\n# Test audio capture\npython3 -c \"import sounddevice; print(sounddevice.query_devices())\"\n\n# Test Whisper\npython3 -c \"from faster_whisper import WhisperModel; print('Whisper OK')\"\n\n# Test uinput\npython3 -c \"import uinput; print('uinput OK')\"\n```\n\n## Security\n\n- The system runs as a user service, not root\n- Audio data is processed locally (no cloud upload)\n- Keystroke injection is limited to the user's session\n- Configuration files are user-specific\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to:\n\n- Report bugs\n- Request features\n- Submit code changes\n- Set up development environment\n- Follow coding standards\n\nCode of Conduct: Don't be a jerk. It's freeware.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a complete history of changes and releases.\n\n## Changelog\n\n### Version 1.0.0 (Initial Release)\n- Complete real-time dictation system\n- Voice command support\n- System integration\n- Comprehensive documentation\n\nFor detailed changes, see [CHANGELOG.md](CHANGELOG.md).\n\n## Acknowledgments\n\n- [OpenAI Whisper](https://github.com/openai/whisper) - Speech recognition model\n- [faster-whisper](https://github.com/guillaumekln/faster-whisper) - Optimized Whisper implementation\n- [sounddevice](https://python-sounddevice.readthedocs.io/) - Audio capture\n- [python-uinput](https://github.com/tuomasjjrasanen/python-uinput) - Keystroke injection\n- [pynput](https://github.com/moses-palmer/pynput) - Global hotkey detection\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/yourusername/whisprd/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/whisprd/discussions)\n- **Wiki**: [GitHub Wiki](https://github.com/yourusername/whisprd/wiki)\n\n## Changelog\n\n### v1.1.0\n- Added pause duration configuration\n- Added alternate prompts support from YAML files\n- Improved configuration documentation\n- Enhanced pause detection and utterance segmentation\n\n### v1.0.0\n- Initial release\n- Real-time Whisper transcription\n- Voice command system\n- Keystroke injection\n- Systemd integration\n- Rich CLI interface\n\n---\n\n**Note**: This system requires appropriate permissions for audio capture and keystroke injection. Make sure to follow the installation instructions carefully and test the system in a safe environment first. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAgenticToaster%2Fwhisprd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAgenticToaster%2Fwhisprd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAgenticToaster%2Fwhisprd/lists"}