Whisper Key - Local Speech-to-Text

Global hotkeys to record speech and transcribe directly to your cursor.

Questions or ideas? Discord

✨ Features

• Global Hotkey: Start recording speech from any app
• Auto-Paste: Transcribe directly to cursor
• Auto-Send: Optionally auto-send with ENTER keypress
• Local/Offline: Voice data never leaves your computer
• CPU Ready: Small, efficient models available
• GPU Ready: Support for both NVIDIA & AMD cards
• Cross-platform: Works on Windows and macOS
• Voice Commands: Trigger shortcuts, text snippets, and shell commands by voice — docs
• Configurable: Customize hotkeys, models, and much more

🚀 Quick Start

From PyPI (Recommended)

Requires Python 3.11-3.13

# With pipx (isolated environment)
pipx install whisper-key-local

# Or with pip
pip install whisper-key-local

Then run: whisper-key (or wk for short)

Windows App

1. Download whisper-key.exe from the latest release
2. Run whisper-key.exe

From Source

git clone https://github.com/PinW/whisper-key-local.git
cd whisper-key-local
pip install -e .
python whisper-key.py

🎤 Basic Usage

Open the system tray / menu bar icon to:

• Toggle auto-paste vs clipboard-only
• Change transcription model
• Select audio device

🗣️ Voice Commands

Speak trigger phrases to run shell commands and more. Define in:

• Windows: %APPDATA%\whisperkey\commands.yaml
• macOS: ~/.whisperkey/commands.yaml

commands:
  # Send a keyboard shortcut
  - trigger: "undo"
    hotkey: "ctrl+z"
  # Deliver pre-written text
  - trigger: "my email"
    type: "user@example.com"
  # Run a shell command
  - trigger: "open notepad"
    run: 'notepad.exe'

See the Voice Commands Guide for full details.

⚡ GPU Acceleration

Whisper Key detects your GPU on first launch and offers one-press install of the required runtime libraries. Supports NVIDIA (CUDA) and AMD (ROCm).

For manual setup or troubleshooting, see the GPU Setup Guide.

⚙️ Configuration

Local settings at:

• Windows: %APPDATA%\whisperkey\user_settings.yaml
• macOS: ~/.whisperkey/user_settings.yaml

Delete this file and restart app to reset to defaults.

📁 Model Cache

Default path for transcription models (via HuggingFace):

• Windows: %USERPROFILE%\.cache\huggingface\hub\
• macOS: ~/.cache/huggingface/hub/

Contributing

Check the roadmap for planned features and see CONTRIBUTING.md for guidelines. Please open an issue before starting work on new features.

📦 Dependencies

Cross-platform: faster-whisper · numpy · sounddevice · soxr · pyperclip · ruamel.yaml · pystray · Pillow · playsound3 · ten-vad · hf-xet

Windows: global-hotkeys · pywin32

macOS: pyobjc-framework-Quartz · pyobjc-framework-ApplicationServices