Usage

Hold the trigger, speak, release. The text is typed into the focused field.

Dictating

1. Put the cursor in any text field.
2. Hold the trigger key: Fn on macOS, Right Ctrl on Linux. A sound confirms recording.
3. Speak.
4. Release the key. The text is transcribed and inserted.

On macOS you can change the key from the menu bar (Settings → Trigger). On Linux the trigger is Right Ctrl unless you set trigger.

Hold or toggle

The default hold mode is push-to-talk. With trigger_mode set to "toggle", press the trigger once to start and again to stop. In toggle mode, type_while_speaking types each chunk about a second after each pause instead of all at once; switching windows mid-dictation scatters the text across them.

Menu bar and tray

Whispy lives in the menu bar. From there you can switch the trigger, toggle Type while speaking and Start at login, restart, and quit. If it cannot type, a Can't type — fix permissions… row appears.

Whispy shows its state in the system tray (there is no floating overlay on Linux). Set options such as type_while_speaking: false in the config and restart the service.

Custom vocabulary

Add names, brands and jargon to custom_vocabulary. After transcription, an output word is corrected when its spelling or pronunciation is close to one of your terms (wispy becomes Whispy). It fixes close misses only and never adds words you did not say.

Logs

• Standard log: ~/.whispy.log
• Error log: ~/.whispy-error.log

tail -f ~/.whispy.log ~/.whispy-error.log

Restart

Menu bar → Restart, or quit and reopen /Applications/Whispy.app.

systemctl --user restart whispy.service

From a source checkout, make run runs the daemon in the foreground against your working tree.

Uninstall

If you installed with the one-liner:

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

# 1. Quit Whispy (menu bar → Quit), then remove the venv and legacy LaunchAgents
./install.sh --uninstall
# 2. Delete the app bundle (this also drops the Start at login item)
rm -rf /Applications/Whispy.app
# 3. Optional: wipe settings, auth token and logs
rm -rf ~/.config/whispy ~/.whispy.log ~/.whispy-error.log

./install.sh --uninstall

Local HTTP API

The API listens on loopback only and requires a per-install token, so a web page in your browser cannot drive the daemon. Every request must send the token from ~/.config/whispy/config.token as a bearer header. The port is defined near the top of src/whispy/api/server.py.

curl -H "Authorization: Bearer $(cat ~/.config/whispy/config.token)" http://localhost:9090/status

curl -H "Authorization: Bearer $(cat ~/.config/whispy/config.token)" -X POST http://localhost:9090/start

curl -H "Authorization: Bearer $(cat ~/.config/whispy/config.token)" -X POST http://localhost:9090/stop

/status checks the daemon, /start begins recording and /stop stops and transcribes.

The model

Whispy ships one model, nvidia/parakeet-tdt-0.6b-v3, int8-quantized to ONNX and run on your CPU. There is nothing to choose, so there is no model setting. The download is about 639 MB, automatic on first use, cached at ~/.cache/huggingface/hub/models--istupakov--parakeet-tdt-0.6b-v3-onnx. It uses about 1.4 GB of memory while loaded.

No language setting

The model detects the language of each utterance and copes with switching languages mid-recording. Forcing a language was measurably wrong (English speech came back translated into French), so there is no such setting. See the supported languages.

Short sounds and silence are ignored

Given silence or room noise, the model answers with a short filler such as Yeah. or Okay., which would be typed into whatever you have focused. Two gates run first, and a clip must clear both:

• Loudness. Anything below 0.005 normalized RMS is discarded: a muted mic, a misfire, a quiet room.
• Voice detection. Anything with under 0.20 s of detected voice is discarded: steady noise, a fan, mains hum.

Both fail open: a clip that cannot be measured is transcribed rather than dropped, because losing real dictation is worse than an occasional stray word. Whispy never filters by what was said, since Okay. and No. are legitimate one-word dictations. Pausing to think while holding the trigger is fine too.

In a genuinely loud room (noise above roughly 0.04 RMS) voice detection can no longer tell noise from speech and you rely on the model alone. A stray word in a noisy environment is that gap.

Upgrading from a Whisper-era Whispy

The old model cache at ~/.cache/huggingface/hub/models--Systran--faster-whisper-* is no longer used. ./install.sh --uninstall will not delete it; remove it by hand to reclaim the space.

Upgrading the speech runtime

From the source folder:

./.venv/bin/pip install --upgrade onnx-asr

FAQ