Metadata-Version: 2.4
Name: whisper-key-local
Version: 0.4.0
Summary: Local faster-whisper speech-to-text app with global hotkeys for Windows
Author-email: Pin Wang <pinwang@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: faster-whisper>=1.1.1
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: sounddevice>=0.4.6
Requires-Dist: global-hotkeys>=0.1.7; platform_system == "Windows"
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: ruamel.yaml>=0.18.14
Requires-Dist: pywin32>=306; platform_system == "Windows"
Requires-Dist: pyautogui>=0.9.54; platform_system == "Windows"
Requires-Dist: pystray>=0.19.5
Requires-Dist: Pillow>=10.0.0
Requires-Dist: hf-xet>=1.1.5

# Whisper Key - Local Speech-to-Text for Windows

Global hotkey to start/stop recording and auto-paste transcription wherever your cursor is.

## 🎯 Features

- **Global Hotkey**: Press `Ctrl+Win` to start recording, `Ctrl` to stop
- **Auto-Paste**: Transcription inserted at your cursor via auto-paste
- **Auto-Send**: Press `Alt` to stop, auto-paste, and auto-send with ENTER keypress
- **Offline Capable**: No internet required after models downloaded
- **Local Processing**: Voice data never leaves your computer
- **Voice activity detection**: Prevent hallucinations, auto-stop accidental hotkey presses
- **Configurable**: Customize hotkeys, model, transcription actions, and audio settings

## 🚀 Quick Start

### Prerequisites
- Windows 10/11
- Microphone

### Option 1: Download Portable App
1. [Download the latest release zip](https://github.com/PinW/whisper-key-local/releases/latest)
2. Extract the zip file
3. Run `whisper-key.exe`

### Option 2: Install via pipx
**Prerequisites:**
- Python 3.8+ installed on Windows
- pipx installed (`pip install pipx`)

Install the application globally:
```bash
pipx install whisper-key-local
```

Add VAD support (prevents silence hallucinations):
```bash
pipx inject whisper-key-local git+https://github.com/TEN-framework/ten-vad.git@v1.0-ONNX
```

Run from anywhere:
```bash
whisper-key
```

### Option 3: Development Installation
**Prerequisites:**
- Python 3.8+ installed on Windows

Clone the repository:
```bash
git clone https://github.com/PinW/whisper-key-local.git
cd whisper-key-local
```

Install the dependencies:
```bash
pip install -e .
```

Add VAD support (prevents silence hallucinations):
```bash
pip install git+https://github.com/TEN-framework/ten-vad.git@v1.0-ONNX
```

Run the application:
```bash
python whisper-key.py
```

## 📦 Package Dependencies

- `faster-whisper` - Fast AI speech recognition
- `numpy` - Numerical computing support
- `sounddevice` - Audio recording
- `global-hotkeys` - System-wide hotkey detection  
- `pyperclip` - Clipboard operations
- `ruamel.yaml` - Configuration file parsing (YAML)
- `pyautogui` - Key simulation for Ctrl+V auto-paste and auto-ENTER
- `pywin32` - Windows API access for window management
- `pystray` - System tray integration
- `Pillow` - Image processing for system tray icons
- `hf-xet` - Cache management for Hugging Face models
- `ten-vad` - Voice Activity Detection to prevent silent hallucinations

## 🎮 Basic Usage

- Boot the app, the "tiny" model will download and start
- Press `Ctrl+Win` to start recording
- Speak into your microphone  
- Press `Ctrl` to stop recording and transcribe
- The transcribed text is auto-pasted on your text cursor
- Alternatively press `Alt` to stop recording, auto-paste, and also send an ENTER keypress
- Right click the system tray icon to change models

### Configuration
The app automatically creates a user settings file in `%APPDATA%\Roaming\whisperkey\user_settings.yaml`, where you can:
- Change whisper model size (tiny/base/small/medium/large)
- Hotkeys
- Configure automation (auto-paste, auto-ENTER)
- Voice activity detection
- And much more

## 🔧 Troubleshooting

- Check the log file `app.log` for detailed error messages
- Delete the user settings file in `%APPDATA%/whisperkey/user_settings.yaml` and restart to reset to defaults
