hyprwhspr Documentation

The extension acts as a pure status consumer. It does not capture audio itself; instead, it reads state files written by hyprwhspr to drive its animations. It automatically falls back to ~/.config/hyprwhspr/ if the files are not found in $XDG_RUNTIME_DIR/hyprwhspr/.

Data Sources

Visual Features

• A pulsing record dot.
• 27 cyan-to-violet equalizer bars reacting to live microphone levels.
• Live transcript text (when available).

Both config.json and credentials.json support ${VAR} tokens. These tokens are stored as literal strings on disk and are expanded to their actual values at runtime when the configuration is read. This is useful for keeping sensitive API keys out of your configuration files.

{
  "rest_api_key": "${OPENAI_API_KEY}"
}

The recording_mode setting determines how the application captures audio. Available modes include:

• toggle (default): Press the primary shortcut to start recording, and press it again to stop.
• push_to_talk: Hold the primary shortcut to record, and release it to stop.
• auto: A hybrid mode. A short tap (< 400ms) acts as a toggle; a long hold (>= 400ms) acts as push-to-talk.
• continuous: Press to start. The system automatically transcribes and pastes text whenever a pause in speech is detected. Pressing the shortcut again stops the session and pastes any remaining audio.
• long_form: Designed for extended dictation with pause/resume support. The primary shortcut toggles recording/pause/resume, and a separate long_form_submit_shortcut must be configured to process and paste the accumulated segments.

You can modify the visual properties of the extension by editing its source files and reloading the extension.

Visual Parameters

• Colors, size, and bar count: Edit the constants at the top of extension.js. Available constants include:
  • N_BARS (number of bars)
  • BAR_MIN / BAR_MAX (size constraints)
  • C1 / C2 (colors)
• Pill style: Edit stylesheet.css.

Applying Changes

Once you have edited the files, reload the extension using the following commands (no logout required after the initial registration):

gnome-extensions disable hyprwhspr-waveform@ninyawee.github.io
gnome-extensions enable hyprwhspr-waveform@ninyawee.github.io

gnome-extensions disable hyprwhspr-waveform@ninyawee.github.io && gnome-extensions enable hyprwhspr-waveform@ninyawee.github.io

On Arch Linux, you can install hyprwhspr via the AUR. You can choose between the stable version or the bleeding edge (git) version.

After installation, you must run the interactive setup to configure backends, download models, and set up systemd services.

# Install for stable
yay -S hyprwhspr

# Or install for bleeding edge
yay -S hyprwhspr-git

# Run interactive setup
hyprwhspr setup

If you are using a local-model backend (e.g., pywhispercpp, faster-whisper, onnx-asr, or Cohere Transcribe), you can unload the model from GPU memory to free up VRAM for other tasks (like gaming) without stopping the Hyprwhspr service. Keyboard shortcuts remain active, but recording will be blocked until the model is reloaded.

Note: This does not apply to rest-api or realtime-ws backends as they do not hold local GPU memory.

Commands:

• hyprwhspr model unload: Unloads the model from GPU memory.
• hyprwhspr model reload: Reloads the model into memory.

# Example: Hyprland bindings for GPU management
bindd = SUPER ALT, U, Unload Whisper model, exec, hyprwhspr model unload
bindd = SUPER ALT, L, Reload Whisper model, exec, hyprwhspr model reload

Once installed and configured, follow these steps for your first use:

1. Log out and back in to apply necessary group permissions.
2. Start dictation: Press Super+Alt+D (default). You will hear a beep.
3. Speak naturally.
4. Stop dictation: Press Super+Alt+D again. You will hear a boop.
5. Result: The transcribed text will be automatically pasted into your active buffer.

For other supported distributions, use the official installation script. This script installs dependencies, clones the repository to ~/.local/share/hyprwhspr/src, and initiates the interactive setup process.

curl -fsSL https://hyprwhspr.com/install.sh | bash

To update the application:

• Arch Linux: Use your AUR helper (e.g., yay -Syu hyprwhspr).
• Other distros: Re-run the installation script: curl -fsSL https://hyprwhspr.com/install.sh | bash.

Note: Running hyprwhspr setup is idempotent, meaning you can safely run it after an update to ensure configuration is correct.

# Arch
yay -Syu hyprwhspr

# Other distros
curl -fsSL https://hyprwhspr.com/install.sh | bash

# Re-run setup if needed
hyprwhspr setup

GNOME/Mutter requires specific considerations due to the lack of layer-shell:

• Window Detection: Uses the AT-SPI accessibility bridge. If it's not enabled, hyprwhspr cannot distinguish between terminals and other apps, causing it to fall back to Ctrl+V. You can enable it via: gsettings set org.gnome.desktop.interface toolkit-accessibility true.
• Direct Typing: Mutter blocks wtype. On Wayland, hyprwhspr uses ydotool type for ASCII text on US layouts. For other layouts, it falls back to clipboard paste. To force clipboard paste, set "prefer_clipboard_paste": true.
• Non-Latin Layouts: For layouts like Thai, Russian, or Arabic, hyprwhspr briefly switches to a Latin input source to perform the paste chord and then restores your original layout. Ensure you have a Latin source configured in your system settings.