A free, open source, and extensible speech-to-text application that works completely offline.
slim readme
CJ Pais53c55d706514
diff --git a/README.md b/README.mdindex 14ea9190..ebeb91da 100644--- a/README.md+++ b/README.md@@ -15,8 +15,6 @@ Handy was created to fill the gap for a truly open source, extensible speech-to-- **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 Works1. **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)@@ -62,20 +60,6 @@ Control Handy from [Raycast](https://www.raycast.com) — start/stop recording,[Source](https://github.com/mattiacolombomc/raycast-handy) · by [@mattiacolombomc](https://github.com/mattiacolombomc)-## 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**:- - `transcribe-cpp`: Local speech recognition with Whisper-family models (GGML/GGUF)- - `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 ModeHandy includes an advanced debug mode for development and troubleshooting. Access it by pressing:@@ -85,7 +69,7 @@ Handy includes an advanced debug mode for development and troubleshooting. Acces### CLI Parameters-Handy supports command-line flags for controlling a running instance and customizing startup behavior. These work on all platforms (macOS, Windows, Linux).+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):@@ -132,19 +116,6 @@ This is a hardware limitation rather than a Handy bug. `fn` is not part of the sIf 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.-### 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`](https://github.com/atx/wtype) or [`dotool`](https://sr.ht/~geb/dotool/) for text input to work correctly (see [Linux Notes](#linux-notes) below for installation)-### Linux Notes**Text Input Tools:**@@ -164,6 +135,11 @@ For reliable text input on Linux, install the appropriate tool for your displayWithout 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`](https://github.com/atx/wtype) or [`dotool`](https://sr.ht/~geb/dotool/) for text input to work correctly (see [Linux Notes](#linux-notes) below for installation)+**Other Notes:**- **Runtime library dependency (`libgtk-layer-shell.so.0`)**:@@ -237,60 +213,6 @@ Without these tools, Handy falls back to enigo which may have limited compatibil- 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 SignaturesHandy release artifacts are signed with Tauri's updater signature format. The public key is stored in [`src-tauri/tauri.conf.json`](src-tauri/tauri.conf.json) under `plugins.updater.pubkey`.@@ -383,11 +305,6 @@ Download the models you want from below- Q8_0 (731 MB): `https://huggingface.co/handy-computer/parakeet-unified-en-0.6b-gguf/resolve/main/parakeet-unified-en-0.6b-Q8_0.gguf`-**Parakeet Models (compressed archives):**--- V2 (473 MB): `https://blob.handy.computer/parakeet-v2-int8.tar.gz`-- V3 (478 MB): `https://blob.handy.computer/parakeet-v3-int8.tar.gz`-#### Step 4: Install Models**For Whisper Models (.bin files):**@@ -406,29 +323,8 @@ Simply place the `.bin` file directly into the `models` directory:Place the `.gguf` file directly into the `models` directory, exactly like the Whisper `.bin` files above. Handy also picks up models already present in the shared Hugging Face cache (`~/.cache/huggingface/hub`), so a copy downloaded by another tool works without being moved.-**For Parakeet Models (.tar.gz archives):**--1. Extract the `.tar.gz` file-2. Place the **extracted directory** into the `models` folder-3. 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` or `.gguf` files—use the exact filenames from the download URLs- After placing the files, restart Handy to detect the new models@@ -511,12 +407,6 @@ $env:HANDY_KEEP_VULKAN_IMPLICIT_LAYERS = "1"Adjust the executable path if needed. This override only applies to apps launched from that PowerShell session, not the Start menu. Handy also preserves any existing `VK_LOADER_LAYERS_DISABLE` value.-### Handy Starts or Stops Recording on Its Own (Linux)--Handy 0.9.4 and earlier listened for `SIGUSR1` as a remote-control trigger. WebKitGTK — the webview engine embedded in Handy on Linux — uses that same signal internally to coordinate JavaScript garbage collection, so GC cycles were misread as hotkey presses: recordings started on their own, or real dictations were cut off mid-sentence (typically ~2 minutes in). See [#1660](https://github.com/cjpais/Handy/issues/1660).--Update to a newer release, and replace any `pkill -USR1 -n handy` keybindings with `handy --toggle-post-process`.-### How to Contribute1. **Check existing issues** at [github.com/cjpais/Handy/issues](https://github.com/cjpais/Handy/issues)@@ -559,7 +449,7 @@ Handy is open-source software, but the Handy name, logo, icon, and brand assets## Acknowledgments- **Whisper** by OpenAI for the speech recognition model-- **ggml and transcribe.cpp** for amazing cross-platform speech-to-text inference/acceleration+- **ggml** for an amazing cross-platform tensor library- **Silero** for great lightweight VAD- **Tauri** team for the excellent Rust-based app framework- **Community contributors** helping make Handy better