Whispy docs

Install

One command installs Whispy on macOS and Linux. Tick the steps as you go; your progress is remembered in this browser.

One-line installer

curl -fsSL https://raw.githubusercontent.com/albrones/whispy/main/scripts/bootstrap.sh | bash

On macOS it builds and installs the signed Whispy.app into /Applications. Source lives in ~/.local/share/whispy.

On Linux it sets up a virtualenv and a systemd --user service. Source lives in ~/.local/share/whispy.

Checklist

  1. Install the Xcode Command Line Tools, needed to build the app. 
    xcode-select --install
  2. Run the one-line installer above. If the Command Line Tools are missing it prints the manual steps instead. To do it by hand: 
    git clone https://github.com/albrones/whispy.git
cd whispy && ./install.sh   # creates the .venv
make app                    # builds and signs dist/Whispy.app
cp -R dist/Whispy.app /Applications/
open /Applications/Whispy.app
  3. Microphone. On first launch macOS shows a Whispy prompt: click Allow.
  4. Accessibility. System Settings → Privacy & Security → Accessibility → enable Whispy. Without it the text is transcribed but never typed.
  5. Input Monitoring. System Settings → Privacy & Security → Input Monitoring → enable Whispy. It is needed to detect the Fn key.
  6. Restart Whispy from its menu bar icon (Restart) so the new permissions apply.
  7. Optional: switch on Start at login in the menu bar menu. No LaunchAgent is used.
  8. Remove any old LaunchAgents (the older com.whisper-dictation and the com.whispy ones) so the daemon does not run twice: 
    ./install.sh --uninstall

Whispy is signed with a free, local self-signed certificate, so macOS remembers the permissions across relaunches. After a fresh make app build macOS may ask you to approve them again.

  1. Use an X11 session, not Wayland. Under Wayland, log out and pick an Xorg / X11 session at the login screen.
  2. Install xdotool (text injection), xclip or xsel (clipboard delivery, on by default), and the PortAudio runtime: 
    sudo apt install xdotool xclip libportaudio2   # Debian/Ubuntu
sudo dnf install xdotool xclip portaudio       # Fedora
sudo pacman -S xdotool xclip portaudio         # Arch
  3. Run the one-line installer above. It creates a virtualenv and a systemd --user service that starts at login.
  4. Check that it is running: 
    systemctl --user status whispy.service

Dictating mostly into a terminal? Terminals read Ctrl+V as a literal character, so set copy_to_clipboard to false.

First run: the model

Whispy uses one model, nvidia/parakeet-tdt-0.6b-v3, run on your CPU. The first time you dictate it downloads about 639 MB, once, and caches it. It uses about 1.4 GB of memory while loaded.

It transcribes 25 languages and detects the language automatically: Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Russian and Ukrainian. Other languages will not transcribe.

Not working? Run make doctor from the source folder, or see Troubleshooting.

Uninstall

curl -fsSL https://raw.githubusercontent.com/albrones/whispy/main/scripts/bootstrap.sh | bash -s -- --uninstall

See Usage for the manual steps.