155 lines
4.8 KiB
Markdown
155 lines
4.8 KiB
Markdown
# whisper.linux
|
|
|
|
Voice typing for Linux desktop using [whisper.cpp](https://github.com/ggerganov/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
|
|
|
|
```bash
|
|
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):**
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# All tests
|
|
./run_tests.sh
|
|
|
|
# With options
|
|
./run_tests.sh --debug -x -k "test_toggle"
|
|
|
|
# Or directly
|
|
python3 -m pytest tests/ -v
|
|
```
|