README.md
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.
Handy was created to fill the gap for a truly open source, extensible speech-to-text tool. As stated on handy.computer:
Handy isn't trying to be the best speech-to-text app—it's trying to be the most forkable one.
The process is entirely local:
brew install --cask handywinget install cjpais.Handy For detailed build instructions including platform-specific requirements, see BUILD.md.
<a href="https://www.raycast.com/mattiacolombomc/handy" title="Install Handy Raycast Extension"></a>
Control Handy from Raycast — start/stop recording, browse transcript history, manage dictionary, switch models and languages.
Source · by @mattiacolombomc
Handy is built as a Tauri application combining:
whisper-rs: Local speech recognition with Whisper modelstranscribe-rs: CPU-optimized speech recognition with Parakeet modelscpal: Cross-platform audio I/Ovad-rs: Voice Activity Detectionrdev: Global keyboard shortcuts and system eventsrubato: Audio resamplingHandy includes an advanced debug mode for development and troubleshooting. Access it by pressing:
Cmd+Shift+DCtrl+Shift+DHandy 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):
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:
bash/Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription
This project is actively being developed and has some known issues. We believe in transparency about the current state:
Whisper Model Crashes:
Wayland Support (Linux):
wtype or dotool for text input to work correctly (see Linux Notes below for installation)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) |
xdotool for both direct typing and clipboard paste shortcutswtype (preferred) or dotool for text input to work correctlyinput 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.
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:
Toggle Handy Transcriptionhandy --toggle-transcriptionSuper+O)KDE Plasma:
Toggle Handy Transcriptionhandy --toggle-transcriptionSway / i3:
Add to your config file (~/.config/sway/config or ~/.config/i3/config):
bindsym $mod+o exec handy --toggle-transcription
Hyprland:
Add to your config file (~/.config/hypr/hyprland.conf):
bind = $mainMod, O, exec, handy --toggle-transcription
You can also manage global shortcuts outside of Handy via Unix signals, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings:
| Signal | Action | Example |
|---|---|---|
SIGUSR2 | Toggle transcription | pkill -USR2 -n handy |
SIGUSR1 | Toggle transcription with post-processing | pkill -USR1 -n handy |
Example Sway config:
bindsym $mod+o exec pkill -USR2 -n handy
bindsym $mod+p exec pkill -USR1 -n handy
pkill here simply delivers the signal—it does not terminate the process.
The following are recommendations for running Handy on your own machine. If you don't meet the system requirements, the performance of the application may be degraded. We are working on improving the performance across all kinds of computers and hardware.
For Whisper Models:
For Parakeet V3 Model:
We're actively working on several features and improvements. Contributions and feedback are welcome!
Debug Logging:
macOS Keyboard Improvements:
Opt-in Analytics:
Settings Refactoring:
Tauri Commands Cleanup:
Handy release artifacts are signed with Tauri's updater signature format. The public key is stored in src-tauri/tauri.conf.json under plugins.updater.pubkey.
To verify a release manually, set ARTIFACT to the filename you downloaded, save the pubkey value from src-tauri/tauri.conf.json to handy.pub.b64, then decode the public key and matching .sig file from base64 and verify the artifact with minisign:
# Replace with the file you downloaded
ARTIFACT="Handy_0.8.1_amd64.AppImage"
python3 - "$ARTIFACT" <<'PY'
import base64, pathlib, sys
artifact = sys.argv[1]
pub = pathlib.Path("handy.pub.b64").read_text().strip()
pathlib.Path("handy.pub").write_bytes(base64.b64decode(pub))
sig = pathlib.Path(f"{artifact}.sig").read_text().strip()
pathlib.Path(f"{artifact}.minisig").write_bytes(base64.b64decode(sig))
PY
minisign -Vm "$ARTIFACT" \
-p handy.pub \
-x "$ARTIFACT.minisig"
On success, minisign prints:
Signature and comment signature verified
Do not use gpg for these .sig files.
If you're behind a proxy, firewall, or in a restricted network environment where Handy cannot download models automatically, you can manually download and install them. The URLs are publicly accessible from any browser.
Cmd+Shift+D to open debug menuCtrl+Shift+D to open debug menuThe typical paths are:
~/Library/Application Support/com.pais.handy/C:\Users\{username}\AppData\Roaming\com.pais.handy\~/.config/com.pais.handy/Inside your app data directory, create a models folder if it doesn't already exist:
# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.pais.handy/models
# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.pais.handy\models"
Download the models you want from below
Whisper Models (single .bin files):
https://blob.handy.computer/ggml-small.binhttps://blob.handy.computer/whisper-medium-q4_1.binhttps://blob.handy.computer/ggml-large-v3-turbo.binhttps://blob.handy.computer/ggml-large-v3-q5_0.binParakeet Models (compressed archives):
https://blob.handy.computer/parakeet-v2-int8.tar.gzhttps://blob.handy.computer/parakeet-v3-int8.tar.gzFor Whisper Models (.bin files):
Simply place the .bin file directly into the models directory:
{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin
For Parakeet Models (.tar.gz archives):
.tar.gz filemodels folderparakeet-tdt-0.6b-v2-int8parakeet-tdt-0.6b-v3-int8Final structure should look like:
{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/ (directory with model files inside)
│ ├── (model files)
│ └── (config files)
└── parakeet-tdt-0.6b-v3-int8/ (directory with model files inside)
├── (model files)
└── (config files)
Important Notes:
.bin files for Whisper models—use the exact filenames from the download URLsHandy can auto-discover custom Whisper GGML models placed in the models directory. This is useful for users who want to use fine-tuned or community models not included in the default model list.
How to use:
.bin format (e.g., from Hugging Face).bin file in your models directory (see paths above)Important:
.bin file)my-custom-model.bin → "My Custom Model")If Handy fails to start reliably on Linux — for example, it crashes shortly after launch, never shows its window, or reports a Wayland protocol error — try the steps below in order.
1. Install (or reinstall) gtk-layer-shell
Handy uses gtk-layer-shell for its recording overlay and links against it at runtime. A missing or broken installation is the most common cause of startup failures and can manifest as a crash or a hang well before any window is shown. Make sure the runtime package is installed 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 |
If it is already installed and you still see startup problems, try reinstalling it (e.g. sudo pacman -S gtk-layer-shell again) in case the library files were corrupted by a partial upgrade.
2. Disable the GTK layer shell overlay (HANDY_NO_GTK_LAYER_SHELL)
If installing the library does not help, you can skip gtk-layer-shell initialization entirely as a workaround. On some compositors (notably KDE Plasma under Wayland) it has been reported to interact poorly with the recording overlay. With this variable set, the overlay falls back to a regular always-on-top window:
HANDY_NO_GTK_LAYER_SHELL=1 handy
3. Disable WebKit DMA-BUF renderer (WEBKIT_DISABLE_DMABUF_RENDERER)
On some GPU/driver combinations the WebKitGTK DMA-BUF renderer can cause the window to fail to render or to crash. Try:
WEBKIT_DISABLE_DMABUF_RENDERER=1 handy
Making a workaround permanent
Once you've found a flag that helps, export it from your shell profile (~/.bashrc, ~/.zshenv, …) or from the desktop autostart entry that launches Handy. If you launch Handy from a .desktop file, you can prefix the Exec= line, e.g.:
Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy
If a workaround helps you, please open an issue describing your distro, desktop environment, and session type — that information helps us narrow down the underlying bug.
The goal is to create both a useful tool and a foundation for others to build upon—a well-patterned, simple codebase that serves the community.
MIT License - see LICENSE file for details.