Handy Voice is an offline speech-to-text desktop application designed to provide accurate voice dictation and transcription while prioritizing privacy and accessibility. Built as a fork of Handy, an open-source project, Handy Voice enhances its predecessor with additional features such as improved voice overlay, Windows startup integration, and customizable sound themes.
Key Features:
Handy Voice offers voice-to-text transcription that processes audio entirely offline, ensuring no data is sent to external servers. It supports configurable keyboard shortcuts for starting and stopping recording, push-to-talk mode, and automatic detection of speech activity using voice activity detection (VAD). The application also includes a customizable overlay for displaying transcriptions in real time, Windows startup integration for convenience, and sound themes to provide feedback during use.
Audience & Benefit:
Ideal for content creators, transcription professionals, and individuals with accessibility needs, Handy Voice empowers users by enabling hands-free text input. Its offline functionality ensures privacy, while its customizable features make it adaptable to various workflows. By leveraging Whisper models or Parakeet V3 for transcription, users can achieve high accuracy across multiple languages without compromising on performance.
Handy Voice is a practical tool for anyone seeking a reliable, private, and efficient speech-to-text solution that works seamlessly across platforms. It can be installed via winget.
README
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
Frontend: React + TypeScript with Tailwind CSS for the settings UI
Backend: Rust for system integration, audio processing, and ML inference
Core Libraries:
whisper-rs: Local speech recognition with Whisper models
transcribe-rs: CPU-optimized speech recognition with Parakeet models
cpal: Cross-platform audio I/O
vad-rs: Voice Activity Detection
rdev: Global keyboard shortcuts and system events
rubato: Audio resampling
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).
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 >
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 wtype or dotool 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
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
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.
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
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 (~/.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:
pkill here simply delivers the signal—it does not terminate the process.
Overlay & Pasting Issues (Linux):
The recording overlay window can interfere with pasting transcribed text into target applications on Linux (X11)
Solution: Open Settings > Advanced and set "Overlay Position" to "None" to disable the overlay
Enable "Audio Feedback" (also in Advanced) if you still want audible confirmation of recording state
Users who upgrade from older versions or import settings from other platforms may need to manually apply this change
Platform Support
macOS (both Intel and Apple Silicon)
x64 Windows
x64 Linux
System Requirements/Recommendations
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:
macOS: M series Mac, Intel Mac
Windows: Intel, AMD, or NVIDIA GPU
Linux: Intel, AMD, or NVIDIA GPU
Ubuntu 22.04, 24.04
For Parakeet V3 Model:
CPU-only operation - runs on a wide variety of hardware
Minimum: Intel Skylake (6th gen) or equivalent AMD processors
Performance: ~5x real-time speed on mid-range hardware (tested on i5)
Automatic language detection - no manual language selection required
Roadmap & Active Development
We're actively working on several features and improvements. Contributions and feedback are welcome!
In Progress
Debug Logging:
Adding debug logging to a file to help diagnose issues
macOS Keyboard Improvements:
Support for Globe key as transcription trigger
A rewrite of global shortcut handling for MacOS, and potentially other OS's too.
Opt-in Analytics:
Collect anonymous usage data to help improve Handy
Privacy-first approach with clear opt-in
Settings Refactoring:
Cleanup and refactor settings system which is becoming bloated and messy
Implement better abstractions for settings management
Tauri Commands Cleanup:
Abstract and organize Tauri command patterns
Investigate tauri-specta for improved type safety and organization
Verify Release Signatures
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.
Troubleshooting
Manual Model Installation (For Proxy Users or Network Restrictions)
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.
Step 1: Find Your App Data Directory
Open Handy settings
Navigate to the About section
Copy the "App Data Directory" path shown there, or use the shortcuts:
Place the extracted directory into the models folder
The directory must be named exactly as follows:
Parakeet V2: parakeet-tdt-0.6b-v2-int8
Parakeet V3: parakeet-tdt-0.6b-v3-int8
Final 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:
For Parakeet models, the extracted directory name must match exactly as shown above
Do not rename the .bin files for Whisper models—use the exact filenames from the download URLs
After placing the files, restart Handy to detect the new models
Step 5: Verify Installation
Restart Handy
Open Settings → Models
Your manually installed models should now appear as "Downloaded"
Select the model you want to use and test transcription
Custom Whisper Models
Handy 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:
Obtain a Whisper model in GGML .bin format (e.g., from Hugging Face)
Place the .bin file in your models directory (see paths above)
Restart Handy to discover the new model
The model will appear in the "Custom Models" section of the Models settings page
Important:
Community models are user-provided and may not receive troubleshooting assistance
The model must be a valid Whisper GGML format (.bin file)
Model name is derived from the filename (e.g., my-custom-model.bin → "My Custom Model")
Linux Startup Crashes or Instability
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:
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.
