cjpais / Handy

Handy **A free, open source, and extensible speech-to-text application that works completely offline.** Handy is a cross-platform desktop application that provides simple, privacy-focused speech transcription. Press a shortcut, speak, and have your words appear in any text field. This happens on your own computer without sending any information to the cloud. Why Handy? Handy was created to fill the gap for a truly open source, extensible speech-to-text tool. As stated on handy.computer: • **Free**: Accessibility tooling belongs in everyone's hands, not behind a paywall • **Open Source**: Together we can build further. Extend Handy for yourself and contribute to something bigger • **Private**: Your voice stays on your computer. Get transcriptions without sending audio to the cloud • **Simple**: One tool, one job. Transcribe what you say and put it into a text box Handy isn't trying to be the best speech-to-text app—it's trying to be the most forkable one. How It Works • **Press** a configurable keyboard shortcut to start/stop recording (or use push-to-talk mode) • **Speak** your words while the shortcut is active • **Release** and Handy processes your speech using Whisper • **Get** your transcribed text pasted directly into whatever app you're using The process is entirely local: • Silence is filtered using VAD (Voice Activity Detection) with Silero • Transcription uses your choice of models: • **Whisper models** (Small/Medium/Turbo/Large) with GPU acceleration when available • **Parakeet V3** - CPU-optimized model with excellent performance and automatic language detection • Works on Windows, macOS, and Linux Quick Start Installation • Download the latest release from the releases page or the website • **macOS**: Also available via Homebrew cask: • **Windows**: Also available via winget: \ **Note:** The Homebrew cask and winget package are not maintained by the Handy developers. • Install the application • Launch Handy and grant necessary system permissions (microphone, accessibility) • Configure your preferred keyboard shortcuts in Settings • Start transcribing! Development Setup For detailed build instructions including platform-specific requirements, see BUILD.md. Architecture Handy is built as a Tauri application combining: • **Frontend**: React + TypeScript with Tailwind CSS for the settings UI • **Backend**: Rust for system integration, audio processing, and ML inference • **Core Libraries**: • : Local speech recognition with Whisper models • : CPU-optimized speech recognition with Parakeet models • : Cross-platform audio I/O • : Voice Activity Detection • : Global keyboard shortcuts and system events • : Audio resampling Debug Mode Handy includes an advanced debug mode for development and troubleshooting. Access it by pressing: • **macOS**: • **Windows/Linux**: CLI Parameters Handy supports command-line flags for controlling a running instance and customizing startup behavior. These work on all platforms (macOS, Windows, Linux). **Remote control flags** (sent to an already-running instance via the single-instance plugin): **Startup flags:** Flags can be combined for autostart scenarios: > **macOS tip:** When Handy is installed as an app bundle, invoke the binary directly: > > Known Issues & Current Limitations This project is actively being developed and has some known issues. We believe in transparency about the current state: Major Issues (Help Wanted) **Whisper Model Crashes:** • Whisper models crash on certain system configurations (Windows and Linux) • Does not affect all systems - issue is configuration-dependent • If you experience crashes and are a developer, please help to fix and provide debug logs! **Wayland Support (Linux):** • Limited support for Wayland display server • Requires or for text input to work correctly (see Linux Notes below for installation) Linux Notes **Text Input Tools:** For reliable text input on Linux, install the appropriate tool for your display server: | Display Server | Recommended Tool | Install Command | | -------------- | ---------------- | -------------------------------------------------- | | X11 | | | | Wayland | | | | Both | | (requires group) | • **X11**: Install for both direct typing and clipboard paste shortcuts • **Wayland**: Install (preferred) or for text input to work correctly • **dotool setup**: Requires adding your user to the group: (then log out and back in) Without these tools, Handy falls back to enigo which may have limited compatibility, especially on Wayland. **Other Notes:** • **Runtime library dependency ( )**: • Handy links on Linux. If startup fails with , install the runtime package for your distro: | Distro | Package to install | Example command | | ------------- | --------------------- | -------------------------------------- | | Ubuntu/Debian | | | | Fedora/RHEL | | | | Arch Linux | | | • For building from source on Ubuntu/Debian, you may also need . • The recording overlay is disabled by default on Linux ( ) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Handy from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window. • If you are having trouble with the app, running with the environment variable may help • **Global keyboard shortcuts (Wayland):** On Wayland, system-level shortcuts must be configured through your desktop environment or window manager. Use the CLI flags as the command for your custom shortcut. **GNOME:** • Open **Settings > Keyboard > Keyboard Shortcuts > Custom Shortcuts** • Click the **+** button to add a new shortcut • Set the **Name** to • Set the **Command** to • Click **Set Shortcut** and press your desired key combination (e.g., ) **KDE Plasma:** • Open **System Settings > Shortcuts > Custom Shortcuts** • Click **Edit > New > Global Shortcut > Command…