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 How It Works Press a configurable keyboard shortcut: hold it to record and release to stop, or tap it to toggle recording on and off (Hold-only and Toggle-only modes are also available) 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 : brew install --cask handy Windows : Also available via winget : winget install cjpais.Handy Note: The Homebrew cask and winget package are not maintained by the Handy developers. Debian/Ubuntu : Install the downloaded .deb with APT so required dependencies are installed automatically: sudo apt install ./Handy_ * .deb Do not use dpkg -i unless the dependencies are already installed. If you already used it, run sudo apt --fix-broken install . 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 . Sponsors We're grateful for the support of our sponsors who help make Handy possible: Integrations Control Handy from Raycast — start/stop recording, browse transcript history, manage dictionary, switch models and languages. Source · by @mattiacolombomc Debug Mode Handy includes an advanced debug mode for development and troubleshooting. Access it by pressing: macOS : Cmd+Shift+D Windows/Linux : Ctrl+Shift+D CLI Parameters Handy supports command-line flags for controlling a running instance and customizing startup behavior. These work on all platforms (macOS, Windows, Linux). Largely this is a beta feature. Remote control flags (sent to an already-running instance via the single-instance plugin): handy --toggle-transcription # Toggle recording on/off handy --toggle-post-process # Toggle recording with post-processing on/off handy --cancel # Cancel the current operation Startup flags: handy --start-hidden # Start without showing the main window handy --no-tray # Start without the system tray icon handy --debug # Enable debug mode with verbose logging handy --help # Show all available flags Flags can be combined for autostart scenarios: handy --start-hidden --no-tray macOS tip: When Handy is installed as an app bundle, invoke the binary directly: /Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription Known Issues & Current Limitations This project is actively being developed and has some known issues . We believe in transparency about the current state: Bluetooth Headset Microphones (macOS) Using a Bluetooth headset microphone on macOS may temporarily reduce playback quality or volume while recording because Bluetooth switches to bidirectional audio. Keep your headphones as the output device and select your Mac's built-in or an external microphone in Handy to avoid this. fn and Globe Key Shortcuts (macOS) Shortcuts that include the fn (Globe) key only work on Apple keyboards — your Mac's built-in keyboard or an Apple external keyboard. They will never trigger on a third-party keyboard, even while it is connected to the same Mac. This is a hardware limitation rather than a Handy bug. fn is not part of the standard USB HID keyboard specification: Apple reports it through a vendor-specific usage that macOS honors only from Apple devices, while third-party keyboards handle their Fn key entirely in firmware and send nothing to the computer. There is no event for Handy to listen for. If you switch between a MacBook keyboard and an external one, pick a shortcut built from standard modifiers ( ctrl , option , shift , command ) or a regular key instead. 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 xdotool sudo apt install xdotool Wayland wtype sudo apt install wtype Both dotool sudo apt install dotool (requires input group) X11 : Install xdotool for both direct typing and clipboard paste shortcuts Ubuntu 26.04 : Has Wayland display server by default. wtype does not work, you need to install ydotool and configure systemd as described here . Wayland : Install wtype (preferred) or dotool for text input to work correctly dotool setup : Requires adding your user to the input group: sudo usermod -aG input $USER (then log out and back in) Without these tools, Handy falls back to enigo which may have limited compatibility, especially on Wayland. Wayland Support (Linux): Limited support for Wayland display server Requires wtype or dotool for text input to work correctly (see Linux Notes below for installation) Other Notes: Runtime library dependency ( libgtk-layer-shell.so.0 ) : Handy links gtk-layer-shell on Linux. If startup fails with error while loading shared libraries: libgtk-layer-shell.so.0 , install the runtime package for your distro: Distro Package to install Example command Ubuntu/Debian libgtk-layer-shell0 sudo apt install libgtk-layer-shell0 Fedora/RHEL gtk-layer-shell sudo dnf install gtk-layer-shell Arch Linux gtk-layer-shell sudo pacman -S gtk-layer-shell For building from source on Ubuntu/Debian, you may also need libgtk-layer-shell-dev . The recording overlay is disabled by default on Linux ( Overlay Position: None ) 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 WEBKIT_DISABLE_DMABUF_RENDERER=1 may help If Handy fails to start reliably on Linux, see Troubleshooting → Linux Startup Crashes or Instability . 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 Toggle Handy Transcription Set the Command to handy --toggle-transcription Click Set Shortcut and press your desired key combination (e.g., Super+O ) KDE Plasma: Open System Settings > Shortcuts > Custom Shortcuts Click Edit > New > Global Shortcut > Command/URL Name it Toggle Handy Transcription In the Trigger tab, set your desired key combination In the Action tab, set the command to handy --toggle-transcription Sway / i3: Add to your config file ( ~/.