hyprwhspr

Thank you to all the contributors who keep the flow of excellent new features alive. :pray:

System tray controls

An optional tray icon shows recording, transcription, model and error states. Click it to start or stop recording, load or unload the model, or restart and stop the service.

Long-form sessions get Pause, Resume, Submit, Retry and Cancel actions. Stop stays available when a new recording starts while the previous one transcribes.

• Off by default. Setup offers it when you skip the bar integrations.
• Works with KDE Plasma, XFCE, Waybar's tray and Quickshell shells. GNOME needs the AppIndicator extension.
• Restart and Stop service actions appear only when running under hyprwhspr.service.

To enable it, add this to your config and restart the service:

{
  "tray_icon_enabled": true
}

No need to change anything if you use Noctalia or Waybar plugins already.

Thanks to @ChickenSplash for #292.

Deepgram Nova-3 realtime dictation

Deepgram is now available under Realtime WS in hyprwhspr setup, with live transcript previews.

{
  "transcription_backend": "realtime-ws",
  "websocket_provider": "deepgram",
  "websocket_model": "nova-3"
}

• Supports toggle, push-to-talk and auto recording modes.
• Leave language unset for multilingual detection, or set an explicit language.
• Each recording gets a fresh stream. Stopping flushes the remaining transcript before closing.
• Optional Deepgram settings, including repeated keyterm parameters, can be supplied through websocket_url.

Setup and diagnostics now flag incompatible continuous or long-form modes for Deepgram and Phonon.

Thanks to @TagCopperLight for #294.

ElevenLabs Scribe v2 over REST

Scribe v2 is now available under REST API in setup. It shares the stored ElevenLabs key with Scribe v2 Realtime, and language selection works through the usual primary and secondary shortcuts.

It is very fast and accurate!

REST body fields now accept flat arrays, sent as repeated form fields. For example, add vocabulary hints to Scribe v2:

{
  "rest_body": {
    "model_id": "scribe_v2",
    "keyterms": ["hyprwhspr", "Hyprland", "Claude Code"]
  }
}

Provider-specific authentication headers are handled automatically. Explicit authentication headers in rest_headers take precedence over the stored key.

Thanks to @avienor for #297.

Maintenance

• The bundled GNOME waveform extension now reads recording and audio-level files only from the runtime directory, completing the compatibility cleanup from v1.51.0.
• Corrected REST documentation and schema descriptions: uploads are always 16-bit WAV. rest_audio_format is unused.

• Upgrading: No configuration changes are required from v1.51.0. The tray icon remains off until enabled.

PRs

• feat(tray): add system tray icon by @ChickenSplash in https://github.com/goodroot/hyprwhspr/pull/292
• feat(realtime): add deepgram streaming provider by @TagCopperLight in https://github.com/goodroot/hyprwhspr/pull/294
• feat(rest): array body fields and provider key headers by @avienor in https://github.com/goodroot/hyprwhspr/pull/297

New Contributors

• @ChickenSplash made their first contribution in https://github.com/goodroot/hyprwhspr/pull/292
• @TagCopperLight made their first contribution in https://github.com/goodroot/hyprwhspr/pull/294
• @avienor made their first contribution in https://github.com/goodroot/hyprwhspr/pull/297

Full Changelog: https://github.com/goodroot/hyprwhspr/compare/v1.51.0...v1.52.0

Language hints for multilingual realtime dictation

If you dictate in more than one language with OpenAI's GPT Transcribe or GPT Live Transcribe, you can now tell the model which languages to expect:

{
  "transcription_backend": "realtime-ws",
  "websocket_provider": "openai",
  "websocket_model": "gpt-live-transcribe",
  "language": null,
  "realtime_transcription_languages": ["pl", "en"]
}

• These are hints, not a lock. Leave the setting unset or null to keep automatic detection.
• An explicit language takes precedence, including one set on a secondary shortcut. The hints come back after that shortcut is used.
• A list without en never gets the English default prompt.
• Older OpenAI models ignore this setting.

Thanks to @PanBartosz for #291.

Fixes

• Single-letter filler words now match only whole words. A filler like "м" no longer removes letters from inside "мама". Single-character word overrides ("ß" → "ss") still apply inside words.

Removed compatibility shims

• Old signal-file paths. recording_control, recording_status and audio_level moved to $XDG_RUNTIME_DIR/hyprwhspr/ in July. The service no longer creates links to them in ~/.config/hyprwhspr/, and it removes the old ones when it starts. If a compositor binding or script still writes to ~/.config/hyprwhspr/recording_control, switch it to hyprwhspr record toggle (or the runtime path).
• use_hypr_bindings. It is still read and migrated to external_bindings, but it is no longer written back on save. hyprwhspr now removes it from your config the next time it starts. Downgrading below v1.49.0 afterwards won't keep compositor bindings enabled.

Upgrading: No action is needed unless something still uses the old ~/.config/hyprwhspr/ signal paths.

PRs

• feat(realtime): configure transcription language hints by @PanBartosz in https://github.com/goodroot/hyprwhspr/pull/291

Full Changelog: https://github.com/goodroot/hyprwhspr/compare/v1.50.0...v1.51.0

v1.50.0

Fresh stuff!

Configurable post-transcription hook timeout

Post-transcription hooks can now run longer than five seconds—useful for local LLM cleanup and other slower text transforms.

Set post_transcription_hook_timeout in your configuration:

{
  "post_transcription_hook": "~/.local/bin/transcription-cleanup",
  "post_transcription_hook_timeout": 15.0
}

• Accepts positive numbers of seconds, including fractional values.
• Defaults to 5 seconds, preserving existing behavior.
• Invalid runtime values fall back to the default; 0 does not disable the timeout.
• The original transcription is still preserved if the hook fails or times out.

Pasting waits for the hook to finish. For hooks that make HTTP requests, keep the request timeout shorter than the hook timeout.

Thanks to @PanBartosz for #289.

Maintenance and release improvements

• Updated website dependencies to address security advisories.
• Clarified hook documentation and examples.
• Removed redundant exception declarations and an unused backend lookup without changing app behavior.

No configuration changes are required when upgrading.

New Contributors

• @PanBartosz made their first contribution in https://github.com/goodroot/hyprwhspr/pull/289

Full Changelog: https://github.com/goodroot/hyprwhspr/compare/v1.49.2...v1.50.0

Fixes

• Keep captured audio when the microphone stalls mid-recording (#282). On machines where the mic and speakers share one sound card, an idle output could stop capture after ~5 seconds. hyprwhspr now ends the recording, transcribes what it heard, and shows one notice instead of silently cutting off.
• Fix a rare hang where logging from cleanup code could freeze the service.
• Push-to-talk now latches only on key-up release. An explicit stop always stops.
• Release the previous model before reloading a backend, so reinitializing no longer holds two models in VRAM (#272).
• Waybar: stop rewriting commented config.jsonc, remove every module placement on uninstall, keep the style copy until removal completes, and accept a string include (#287).
• Setup prints a Lua binding for Hyprland Lua configs instead of writing a bindings.conf that never loads (#286).
• Clipboard restore no longer picks X11 atoms such as TARGETS as the saved type.

Documentation

• Troubleshooting: "Recording cuts off after a few seconds", with a WirePlumber rule that keeps a shared sound card awake.

New Contributors

• @kruxarth made their first contribution in https://github.com/goodroot/hyprwhspr/pull/286

Full Changelog: https://github.com/goodroot/hyprwhspr/compare/v1.49.1...v1.49.2