Feedback
See it listening. Hear it start and stop.
Themed visualizer
Section titled “Themed visualizer”The recording-status indicator — the mic OSD — gives visual feedback while recording and auto-matches Noctalia & Omarchy themes.
{ "mic_osd_enabled": true}Display mode depends on your compositor
Section titled “Display mode depends on your compositor”mic_osd_enabled turns the mic OSD on; how it’s shown is chosen automatically at startup:
- Overlay mode — compositors with layer-shell support (Hyprland, Sway, niri, KDE Plasma Wayland) get the animated always-on-top overlay. Requires GTK4, PyCairo, and
gtk4-layer-shell. - Notification mode — GNOME/Mutter and X11 sessions use desktop notifications (recording / transcribing / inserted), which never steal the focus the paste needs. The layer-shell overlay is Wayland-only. Requires a desktop notification service and either
notify-send(libnotify) orgdbus. Processing is replaced by the result; banner timing depends on the desktop.
Set mic_osd_enabled: false to turn off both. The service log records which mode was selected:
journalctl --user -u hyprwhspr.service | grep -E 'Mic-OSD daemon started|status via notifications'Overlay styles
Section titled “Overlay styles”In overlay mode, mic_osd_style picks one of three visualizations (notification mode ignores it):
waveform— the full themed waveform with transcript preview (default)vu_meter— a VU meterpill— a compact monochrome status pill: idle dots, live bars while recording, a travelling wave while processing, a pulse on error, and a checkmark on success. Can optionally show an animated live transcript on realtime backends that stream partial results (OpenAI, ElevenLabs).

{ "mic_osd_style": "pill"}Restart the service after changing the style:
systemctl --user restart hyprwhsprPill live transcript
Section titled “Pill live transcript”Shows the last few words while recording. Opt-in; needs mic_osd_style: pill plus a realtime-ws backend that streams partial transcripts (OpenAI, ElevenLabs, Deepgram, self-hosted — not Gemini yet). Final transcription and paste are unaffected.
{ "transcription_backend": "realtime-ws", "websocket_provider": "elevenlabs", "websocket_model": "scribe_v2_realtime", "realtime_mode": "transcribe", "mic_osd_style": "pill", "mic_osd_pill_transcript_enabled": true}| Setting | Default | Description |
|---|---|---|
mic_osd_pill_transcript_enabled |
false |
Enable the pill transcript. |
mic_osd_pill_transcript_word_limit |
4 |
Recent words shown (1–12). |
mic_osd_pill_transcript_idle_timeout_ms |
1400 |
Hide after this much idle time; 0 disables. |
Notifications
Section titled “Notifications”Choose how much the service tells you. These are the defaults; add only the settings you want to change to your config, then restart hyprwhspr.
{ "notification_level": "all", "notification_timeout_ms": 5000}| Level | Shows |
|---|---|
all (default) |
Problems, command results, model loading/unloading, and recovery that needs retries. |
action_required |
Problems and command results; quiet automatic lifecycle changes. |
off |
No service or Waybar click alerts. Logs remain available. |
Recording status is separate. mic_osd_enabled controls the overlay or recording-status bubble at every level, including off. To disable all desktop notifications, set both notification_level: "off" and mic_osd_enabled: false. Audio feedback has its own toggle.
The first automatic recovery attempt, including after suspend, is silent. If retries are needed, one message explains what is recovering; its outcome replaces it. A blocked recording attempt gets immediate feedback. Microphone and connection recovery keep separate alerts.
| When | What you see |
|---|---|
| The idle timer unloads the model | “Model unloaded after inactivity — reloads on next recording” |
| You record while it loads | “Model loading — keep speaking”, then “Model loading — audio captured” if you stop before it is ready |
| Microphone recovery needs retries | “Recovering microphone…”, then “Microphone recovered” on success |
| Text reaches only the clipboard | “Text copied — paste to insert” |
| No speech is recognized | “No speech recognized — try recording again” |
| A failed model load leaves saved audio | “Transcription failed — audio kept”, with the command to transcribe that file |
A hook that consumes the text shows “Handled by hook”; a capture client shows “✓ Done”. Neither claims the text was inserted. See memory management for model wake behavior and long-form recording for retrying a saved session.
Temporary alerts use notification_timeout_ms (5000 ms by default). The service explicitly closes them after at least four seconds; 0 does not make them permanent. The desktop may use its own banner duration. Recording status has its own lifecycle; clipboard and no-speech results get extra reading time.
Final recovery failures and saved-audio instructions stay until dismissed or resolved. Each saved file keeps its own alert, even after a later successful dictation. Individual microphone-start failures and disconnection notices are temporary, so deliberately muting or unplugging a mic does not leave a permanent warning.
Tray icon
Section titled “Tray icon”A system tray icon shows that hyprwhspr is running and what it’s doing. It works in any standard tray (StatusNotifierItem): KDE Plasma, XFCE, Waybar’s tray module, and Quickshell shells such as DankMaterialShell. GNOME needs the AppIndicator extension.
| Icon | State |
|---|---|
| Microphone | Ready to record |
| Record dot | Recording |
| Pause | Long-form session paused |
| Muted microphone | Model loading or unloaded, or transcribing |
| Warning | Microphone, model or long-form submit problem (the tooltip says which) |
Click it for a menu to start or stop recording, unload or load the model, and restart or stop the service. In long-form, it pauses, submits, retries or cancels. Restart and Stop only appear when the service runs as hyprwhspr.service.
The icon disappears when the service stops, so no icon means hyprwhspr isn’t running. It needs PyGObject, which the visualizer also uses.
It’s off by default; setup offers it when you skip the bar integrations. Using the Waybar module or Noctalia’s widget? You don’t need it. To turn it on:
{ "tray_icon_enabled": true}Restart the service after changing it.
Audio feedback
Section titled “Audio feedback”Optional sound notifications:
{ "audio_feedback": true, // Enable audio feedback (default: true) "audio_volume": 0.5, // General audio volume fallback (0.1 to 1.0, default: 0.5) "start_sound_volume": 1.0, // Start recording sound volume (0.1 to 1.0, default: 1.0) "stop_sound_volume": 1.0, // Stop recording sound volume (0.1 to 1.0, default: 1.0) "error_sound_volume": 0.5, // Error sound volume (0.1 to 1.0, default: 0.5) "start_sound_path": "custom-start.ogg", // Custom start sound (relative to assets) "stop_sound_path": "custom-stop.ogg", // Custom stop sound (relative to assets) "error_sound_path": "custom-error.ogg" // Custom error sound (relative to assets)}Default sounds included:
- Start recording:
ping-up.ogg(ascending tone) - Stop recording:
ping-down.ogg(descending tone) - Error/blank audio:
ping-error.ogg(double-beep)
Custom sounds:
- Supported formats:
.ogg,.wav,.mp3 - Fallback: Uses defaults if custom files don’t exist
Audio ducking
Section titled “Audio ducking”Quiet other audio on record:
{ "audio_ducking": true, "audio_ducking_mode": "duck", "audio_ducking_percent": 50}audio_ducking: true— set true to quiet other audio while recordingaudio_ducking_mode: "duck"—"duck"lowers volume;"pause"pauses media players insteadaudio_ducking_percent: 50— how much to reduce volume BY (default 50 = reduce to 50% of original; 70 = reduce to 30%); in pause mode, applies to apps without player controls
Ducking lowers each application stream’s volume, not the device master — your speaker setting is untouched and shell volume OSDs don’t fire on every recording. Streams that start mid-recording aren’t ducked.
Halving a podcast’s volume doesn’t help; you still miss what was said. Pause mode pauses your players instead and resumes them afterwards, at the same position, with no volume change at all. It uses MPRIS (Firefox, Chromium, Spotify, mpv, VLC, most players); anything without it — game audio, calls, system sounds — is ducked as usual.
Pause mode needs dbus-python, an optional dependency installed by scripts/install-deps.sh; without it, it falls back to ducking. Only players hyprwhspr paused are resumed, and only if they’re still paused when you stop.