Handy: Gratis, open source en uitbreidbare spraak-naar-tekst applicatie die volledig offline werkt

Waarom Handy?

Handy is gemaakt om het gat te vullen voor een echt open source en uitbreidbare spraak-naar-tekst tool. Zoals vermeld op handy.computer:

• Gratis: Toegankelijkheidstools horen in ieders handen te zijn, niet achter een betaalmuur.
• Open Source: Samen kunnen we verder bouwen. Breid Handy voor jezelf uit en draag bij aan iets groters.
• Privé: Je stem blijft op je computer. Krijg transcripties zonder audio naar de cloud te sturen.
• Eenvoudig: Eén tool, één taak. Transcribeer wat je zegt en plaats het in een tekstvak.

Handy probeert niet de beste spraak-naar-tekst app te zijn — het probeert de meest "forkbare" te zijn.

Hoe het werkt

1. Druk op een configureerbare sneltoets: houd deze ingedrukt om op te nemen en laat los om te stoppen, of tik erop om de opname aan en uit te schakelen (alleen-inhouden en alleen-omschakelen modi zijn ook beschikbaar).
2. Spreek je woorden uit terwijl de sneltoets actief is.
3. Laat los en Handy verwerkt je spraak met behulp van Whisper.
4. Ontvang je getranscribeerde tekst, die direct wordt geplakt in de applicatie die je gebruikt.

Het proces is volledig lokaal:

• Stilte wordt gefilterd met VAD (Voice Activity Detection) via Silero.
• Transcriptie maakt gebruik van jouw keuze uit modellen:
• Whisper-modellen (Small/Medium/Turbo/Large) met GPU-versnelling indien beschikbaar.
• Parakeet V3 - een CPU-geoptimaliseerd model met uitstekende prestaties en automatische taaldetectie.
• Compatibiliteit: Werkt op Windows, macOS en Linux.

Snelstart

Installatie

Download de nieuwste release vanaf de releases-pagina of de website.

• macOS: Ook beschikbaar via Homebrew cask: brew install --cask handy
• Windows: Ook beschikbaar via winget: winget install cjpais.Handy
• Let op: De Homebrew cask en winget package worden niet onderhouden door de Handy-ontwikkelaars.
• Debian/Ubuntu: Installeer het gedownloade .deb-bestand met APT, zodat vereiste afhankelijkheden automatisch worden geïnstalleerd:

sudo apt install ./Handy_*.deb

• Gebruik geen dpkg -i tenzij de afhankelijkheden al zijn geïnstalleerd. Als je dit al hebt gedaan, voer dan sudo apt --fix-broken install uit.

Gebruik in werking stellen

1. Installeer de applicatie.
2. Start Handy en verleen de nodige systeemmachtigingen (microfoon, toegankelijkheid).
3. Configureer je voorkeurs-sneltoetsen in de Instellingen.
4. Begin met transcriberen!

Ontwikkelingsopstelling

Voor gedetailleerde build-instructies, inclusief platformspecifieke vereisten, zie BUILD.md.

Integraties

Je kunt Handy aansturen vanuit Raycast — start/stop de opname, bekijk de transcriptiegeschiedenis, beheer het woordenboek en wissel van modellen en talen. (Bron: door @mattiacolombomc)

Architectuur

Handy is gebouwd als een Tauri-applicatie die het volgende combineert:

• Frontend: React + TypeScript met Tailwind CSS voor de instellingen-UI.
• Backend: Rust voor systeemintegratie, audioverwerking en ML-inferentie.
• Kernbibliotheken:
• transcribe-cpp: Lokale spraakherkenning met Whisper-familie modellen (GGML/GGUF).
• transcribe-rs: CPU-geoptimaliseerde spraakherkenning met Parakeet-modellen.
• cpal: Cross-platform audio I/O.
• vad-rs: Voice Activity Detection.
• rdev: Globale sneltoetsen en systeemevenementen.
• rubato: Audio-resampling.

Debug-modus

Handy bevat een geavanceerde debug-modus voor ontwikkeling en probleemoplossing. Deze is toegankelijk via:

• macOS: Cmd+Shift+D
• Windows/Linux: Ctrl+Shift+D

CLI-parameters

Handy ondersteunt command-line flags voor het aansturen van een actieve instantie en het aanpassen van het opstartgedrag. Deze werken op alle platforms (macOS, Windows, Linux).

Remote control flags (verzonden naar een reeds actieve instantie):

• handy --toggle-transcription : Schakelt opname aan/uit.
• handy --toggle-post-process : Schakelt opname met post-processing aan/uit.
• handy --cancel : Annuleert de huidige operatie.

Startup flags:

• handy --start-hidden : Start zonder het hoofdvenster te tonen.
• handy --no-tray : Start zonder het systeemicoontje (tray icon).
• handy --debug : Schakelt debug-modus in met uitgebreide logging.
• handy --help : Toont alle beschikbare flags.

Flags kunnen worden gecombineerd voor automatische startscenario's: handy --start-hidden --no-tray

Tip voor macOS: Wanneer Handy is geïnstalleerd als een app-bundel, roep dan het binary direct aan: /Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription

Bekende problemen en huidige beperkingen

Dit project is actief in ontwikkeling en heeft enkele bekende problemen.

Bluetooth Headset Microfoons (macOS)

Het gebruik van een Bluetooth-headset microfoon op macOS kan de afspeelkwaliteit of het volume tijdelijk verminderen tijdens het opnemen, omdat Bluetooth overschakelt naar bidirectionele audio. Houd je hoofdtelefoon als uitvoerapparaat en selecteer de ingebouwde microfoon van je Mac of een externe microfoon in Handy om dit te voorkomen.

fn en Globe-toets Sneltoetsen (macOS)

Sneltoetsen die de fn (Globe) toets bevatten, werken alleen op Apple-toetsenborden. Ze zullen nooit triggeren op toetsenborden van derden, zelfs niet als deze zijn aangesloten op dezelfde Mac. Dit is een hardwarebeperking; de fn-toets maakt geen deel uit van de standaard USB HID-toetsenbordspecificatie. Gebruik in plaats daarvan standaard modifiers (ctrl, option, shift, command) of een reguliere toets.

Grote problemen (Hulp gevraagd)

• Whisper Model Crashes: Whisper-modellen crashen op bepaalde systeemconfiguraties (Windows en Linux). Dit is configuratie-afhankelijk. Ontwikkelaars die dit kunnen helpen oplossen en debug-logs kunnen leveren zijn welkom.
• Wayland Support (Linux): Beperkte ondersteuning voor de Wayland display server. Vereist wtype of dotool om tekstinvoer correct te laten werken (zie Linux-sectie).

Linux-opmerkingen

Tekstinvoertools

Voor betrouwbare tekstinvoer op Linux moet de juiste tool voor je display server worden geïnstalleerd:

Display Server	Aanbevolen Tool	Installatiecommando
X11	xdotool	sudo apt install xdotool
Wayland	wtype	sudo apt install wtype
Beiden	dotool	sudo apt install dotool (vereist input groep)

• X11: Installeer xdotool voor zowel direct typen als clipboard paste-sneltoetsen.
• Ubuntu 26.04: Gebruikt standaard Wayland. wtype werkt hier niet; installeer ydotool en configureer systemd.
• Wayland: Installeer wtype (voorkeur) of dotool.
• dotool setup: Vereist dat je gebruiker aan de input groep wordt toegevoegd: sudo usermod -aG input $USER (log daarna uit en opnieuw in).

Zonder deze tools valt Handy terug op enigo, wat beperkte compatibiliteit kan hebben, vooral op Wayland.

Overige opmerkingen

• Runtime library dependency (libgtk-layer-shell.so.0): Handy koppelt naar gtk-layer-shell op Linux. Als de opstart faalt met een fout over deze bibliotheek, installeer dan het runtime-pakket:
• Ubuntu/Debian: sudo apt install libgtk-layer-shell0
• Fedora/RHEL: sudo dnf install gtk-layer-shell
• Arch Linux: sudo pacman -S gtk-layer-shell
• Opname-overlay: Deze is standaard uitgeschakeld op Linux (Overlay Position: None) omdat sommige compositors dit als het actieve venster behandelen, wat kan voorkomen dat Handy tekst terugplakt in de oorspronkelijke applicatie.
• Instabiliteit: Als de app niet start, kan het helpen om de omgevingsvariabele WEBKITDISABLEDMABUF_RENDERER=1 te gebruiken.

Globale sneltoetsen (Wayland)

Op Wayland moeten systeem-sneltoetsen via je desktopomgeving of window manager worden geconfigureerd. Gebruik de CLI-flags als commando voor je aangepaste sneltoets.

• GNOME: Instellingen > Toetsenbord > Toetsenbordsneltoetsen > Aangepaste sneltoetsen. Commando: handy --toggle-transcription
• KDE Plasma: Systeeminstellingen > Sneltoetsen > Aangepaste sneltoetsen. Actie: handy --toggle-transcription
• Sway / i3: Voeg toe aan config: bindsym $mod+o exec handy --toggle-transcription
• Hyprland: Voeg toe aan config: bind = $mainMod, O, exec, handy --toggle-transcription

Je kunt Handy ook extern triggeren via Unix-signalen of CLI-flags:

• Toggle transcription: pkill -USR2 -n handy of handy --toggle-transcription
• Toggle transcription met post-processing: handy --toggle-post-process

Let op: Oudere releases accepteerden SIGUSR1 voor post-processing, maar dit veroorzaakte problemen met WebKitGTK garbage collection. Gebruik nu uitsluitend handy --toggle-post-process.

Overlay & Plakproblemen (Linux)

Het opname-overlayvenster kan interfereren met het plakken van tekst op Linux (X11). Oplossing: Ga naar Instellingen > Geavanceerd en zet "Overlay Position" op "None". Schakel "Audio Feedback" in voor hoorbare bevestiging.

Platformondersteuning

• macOS (zowel Intel als Apple Silicon)
• x64 Windows
• x64 Linux

Systeemvereisten en aanbevelingen

Voor een optimale ervaring worden de volgende specificaties aanbevolen:

Voor Whisper-modellen:

• macOS: M-serie Mac of Intel Mac.
• Windows: Intel, AMD, of NVIDIA GPU.
• Linux: Intel, AMD, of NVIDIA GPU (Ubuntu 22.04, 24.04).

Voor Parakeet V3 Model:

• Werkt uitsluitend op de CPU - draait op een breed scala aan hardware.
• Minimum: Intel Skylake (6e generatie) of gelijkwaardige AMD-processoren.
• Prestaties: Ongeveer 5x real-time snelheid op mid-range hardware (getest op i5).
• Taal: Automatische taaldetectie.

Roadmap en actieve ontwikkeling

• Debug Logging: Toevoegen van debug-logs naar een bestand.
• macOS Toetsenbord: Ondersteuning voor de Globe-toets als trigger en een herschrijving van de globale sneltoets-afhandeling.
• Opt-in Analytics: Anonieme gebruiksgegevens verzamelen via een privacy-first opt-in benadering.
• Instellingen Refactoring: Opschonen van het instellingen-systeem.
• Tauri Commands Cleanup: Organiseren van Tauri command-patronen en onderzoek naar tauri-specta.

Release-handtekeningen verifiëren

Handy release-artefacten zijn ondertekend met het Tauri updater-signatuurformaat. De publieke sleutel staat in src-tauri/tauri.conf.json onder plugins.updater.pubkey.

Om een release handmatig te verifiëren met minisign:

1. Sla de publieke sleutel op als handy.pub.b64.
2. Decodeer de publieke sleutel en het bijbehorende .sig bestand van base64.
3. Verifieer het artifact:

minisign -Vm "$ARTIFACT" -p handy.pub -x "$ARTIFACT.minisig"

Gebruik geen gpg voor deze .sig bestanden.

Probleemoplossing

Vorige klembordinhoud wordt geplakt in plaats van de transcriptie

Als de transcriptie correct is in de geschiedenis, maar Handy tekst plakt die je eerder had gekopieerd (issue #502):

1. Open de instellingen en open het Debug-menu (Cmd+Shift+D / Ctrl+Shift+D).
2. Probeer op macOS en Windows Reliable Paste (Beta).
3. Als dit niet werkt of niet beschikbaar is, verhoog dan de Paste Delay (After) in het Debug-menu. Dit bepaalt de wachttijd voordat het vorige klembord wordt hersteld.

Handmatige installatie van modellen

Als Handy modellen niet automatisch kan downloaden (bijv. door een proxy of firewall):

1. Zoek je App Data Directory: Kijk bij Instellingen → About.

• macOS: ~/Library/Application Support/com.pais.handy/
• Windows: C:\Users\{username}\AppData\Roaming\com.pais.handy\
• Linux: ~/.config/com.pais.handy/

1. Maak een models map aan in deze directory.
2. Download modelbestanden:

• Whisper (.bin): Small, Medium, Turbo, of Large van blob.handy.computer.
• Parakeet GGUF (.gguf): Unified EN 0.6B van Hugging Face.
• Parakeet Archives (.tar.gz): V2 of V3 van blob.handy.computer.

1. Installatie:

• Plaats .bin en .gguf bestanden direct in de models map.
• Pak .tar.gz bestanden uit en plaats de map in models. De mappen moeten exact parakeet-tdt-0.6b-v2-int8 of parakeet-tdt-0.6b-v3-int8 heten.

1. Verifiëren: Start Handy opnieuw op en controleer onder Instellingen → Models of ze als "Downloaded" verschijnen.

Aangepaste Whisper-modellen

Handy kan aangepaste Whisper GGML-modellen (.bin) ontdekken als deze in de models directory worden geplaatst. Na een herstart verschijnen deze onder "Custom Models" in de instellingen.

Linux Opstartcrashes of Instabiliteit

Probeer deze stappen in volgorde:

1. Installeer gtk-layer-shell: Zorg dat het runtime-pakket (libgtk-layer-shell0 op Ubuntu) is geïnstalleerd.
2. Schakel GTK layer shell overlay uit: Gebruik HANDYNOGTKLAYERSHELL=1 handy.
3. Schakel WebKit DMA-BUF renderer uit: Gebruik WEBKITDISABLEDMABUF_RENDERER=1 handy.

Om een workaround permanent te maken, voeg deze toe aan je shell-profiel of .desktop bestand (bijv. Exec=env HANDYNOGTKLAYERSHELL=1 handy).

Vulkan Overlays en Capture Tools op Windows

Om crashes door overlay-hooks te voorkomen, slaat Handy impliciete Vulkan-lagen over. Om dit uit te schakelen (voor debugging tools):

1. Sluit Handy volledig af.
2. Voer in PowerShell uit:

$env:HANDYKEEPVULKANIMPLICITLAYERS = "1" & "$env:ProgramFiles\Handy\handy.exe"

Handy start of stopt opnames spontaan (Linux)

Dit werd veroorzaakt door SIGUSR1 signalen van WebKitGTK. Update naar een nieuwere versie en vervang pkill -USR1 bindingen door handy --toggle-post-process.

Bijdragen

• Bekijk bestaande issues op GitHub.
• Fork de repository en maak een feature branch.
• Test grondig op je platform.
• Dien een pull request in met een duidelijke beschrijving.
• Neem contact op via contact@handy.computer.

Gerelateerde Projecten

• Handy CLI: De originele Python command-line versie.
• handy.computer: Projectwebsite met demo's en documentatie.

Licentie

Dit project valt onder de MIT Licentie. Let op: De naam, het logo, het icoon en de merkactiva van Handy zijn niet open source. Onofficiële forks moeten eigen branding gebruiken.

Dankwoord

• OpenAI voor het Whisper-model.
• ggml en transcribe.cpp voor de cross-platform inferentie en versnelling.
• Silero voor de lichtgewicht VAD.
• Tauri team voor het Rust-gebaseerde app-framework.
• Alle community-bijdragers.