whisper.cpp/examples/whisper.linux

whisper.linux

Voice typing for Linux desktop using whisper.cpp.

Transcribes speech from microphone and injects text at the cursor position. Supports X11 and Wayland, hotkey and continuous listening modes, voice commands.

Requirements

• Python 3.10+
• PyQt5: pip install PyQt5
• Built whisper-cli from whisper.cpp (see root README)
• A GGML model file (e.g. ggml-base.bin)
• xdotool (X11/XWayland) or wtype (Wayland) for text injection
• xclip (X11) or wl-copy (Wayland) for clipboard fallback

Quick Start

cd examples/whisper.linux

# Start
./whisper-linux

# Start with debug logging
./whisper-linux --debug

# Toggle recording on a running instance
./whisper-linux --toggle

# Stop
pkill -f whisper-linux

CLI Options

--toggle           Send toggle signal to running instance
--language LANG    Override language (ru, en, auto)
--model PATH       Override model path
--input-mode MODE  hotkey or listen
--output-mode MODE batch or stream
--stream           Shortcut for --output-mode stream
--wake-word WORD   Override wake word (for listen mode)
--wake-model PATH  Lighter model for wake word detection
--debug            Enable debug logging

Input / Output Modes

Two independent axes control behavior:

	batch	stream
hotkey	Record all, transcribe, inject at once	Each speech segment transcribed and injected live
listen	Wake word activates, text accumulated, injected on stop	Wake word activates, each segment injected live

Default: hotkey + batch (press hotkey to record, press again to transcribe).

Voice Commands

When voice_commands = True (default), spoken command words trigger key presses instead of being typed literally. Editable via tray menu: Settings > Edit voice commands.

Word (EN)	Word (RU)	Action
enter	энтер, ввод	Press Enter
backspace	бэкспейс, назад	Delete previous word
tab	таб, табуляция	Press Tab
escape, stop	эскейп, стоп	Press Escape

Commands use fuzzy matching (threshold 0.75), so slight mispronunciations are tolerated.

Backspace has special behavior: if there are buffered words not yet injected, it removes the last word from the buffer. If the buffer is empty, it sends Ctrl+BackSpace to delete the previous word in the editor.

Keyboard Shortcut

In hotkey mode, you toggle recording via --toggle. Set up a global keyboard shortcut to trigger it from anywhere:

GNOME (Settings → Keyboard → Custom Shortcuts → Add):

Field	Value
Name	whisper-linux
Command	/path/to/whisper.linux/whisper-linux --toggle
Shortcut	Super+V or any key you prefer

Or via command line (GNOME):

# Replace /path/to/whisper.linux with the actual path
TOGGLE_CMD="/path/to/whisper.linux/whisper-linux --toggle"

gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings \
  "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/whisper-linux/']"

dconf write /org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/whisper-linux/name "'whisper-linux'"
dconf write /org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/whisper-linux/command "'$TOGGLE_CMD'"
dconf write /org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/whisper-linux/binding "'F8'"

KDE: System Settings → Shortcuts → Custom Shortcuts → Add.

Configuration

Config file: ~/.config/whisper-linux/config.ini

All settings are configurable via the system tray menu (right-click the tray icon).

Autostart

Copy the desktop file to autostart:

cp whisper-linux.desktop ~/.config/autostart/

Project Structure

whisper.linux/
  whisper-linux               # Launcher script (unique process name)
  app/                        # Python package
    __init__.py               # Re-exports public API
    __main__.py               # Entry point
    config.py                 # Config, AppState, constants, helpers
    audio.py                  # AudioRecorder, AudioStream, SimpleVAD
    transcriber.py            # Transcriber, WakeWordDetector
    injector.py               # TextInjector (xdotool/wtype/clipboard)
    commands.py               # VoiceCommands (Enter, Backspace, etc.)
    tray.py                   # TrayIcon, system tray menu, settings
    app.py                    # WhisperLinuxApp, state machine, CLI
  tests/
    conftest.py               # Fixtures
    test_whisper_linux.py     # Tests (all mocked, no hardware needed)
  run_tests.sh                # Run all tests with one command
  whisper-linux.desktop       # Desktop entry for autostart

Running Tests

# All tests
./run_tests.sh

# With options
./run_tests.sh --debug -x -k "test_toggle"

# Or directly
python3 -m pytest tests/ -v