whisper-key-local 0.3.0__tar.gz

whisper_key_local-0.3.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: whisper-key-local
+Version: 0.3.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: 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
+- **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:
+```powershell
+pipx install whisper-key
+```
+
+Add VAD support (prevents silence hallucinations):
+```powershell
+pipx inject whisper-key git+https://github.com/TEN-framework/ten-vad.git@v1.0-ONNX
+```
+
+Run from anywhere:
+```powershell
+whisper-key
+```
+
+### Option 3: Development Installation
+**Prerequisites:**
+- Python 3.8+ installed on Windows
+
+Clone the repository:
+```powershell
+git clone https://github.com/PinW/whisper-key-local.git
+cd whisper-key-local
+```
+
+Install the dependencies:
+```powershell
+pip install -e .
+```
+
+Add VAD support (prevents silence hallucinations):
+```powershell
+pip install git+https://github.com/TEN-framework/ten-vad.git@v1.0-ONNX
+```
+
+Run the application:
+```powershell
+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, and 
+- 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)
+- And much more
+
+## 🔧 Troubleshooting
+
+- Check the log file `app.log` for detailed error messages
+- Delete the user settings file in `%APPDATA%\Roaming\whisperkey\user_settings.yaml` and restart to reset to defaults

whisper_key_local-0.3.0/README.md

@@ -0,0 +1,105 @@
+# 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
+- **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:
+```powershell
+pipx install whisper-key
+```
+
+Add VAD support (prevents silence hallucinations):
+```powershell
+pipx inject whisper-key git+https://github.com/TEN-framework/ten-vad.git@v1.0-ONNX
+```
+
+Run from anywhere:
+```powershell
+whisper-key
+```
+
+### Option 3: Development Installation
+**Prerequisites:**
+- Python 3.8+ installed on Windows
+
+Clone the repository:
+```powershell
+git clone https://github.com/PinW/whisper-key-local.git
+cd whisper-key-local
+```
+
+Install the dependencies:
+```powershell
+pip install -e .
+```
+
+Add VAD support (prevents silence hallucinations):
+```powershell
+pip install git+https://github.com/TEN-framework/ten-vad.git@v1.0-ONNX
+```
+
+Run the application:
+```powershell
+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, and 
+- 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)
+- And much more
+
+## 🔧 Troubleshooting
+
+- Check the log file `app.log` for detailed error messages
+- Delete the user settings file in `%APPDATA%\Roaming\whisperkey\user_settings.yaml` and restart to reset to defaults

whisper_key_local-0.3.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "whisper-key-local"
+version = "0.3.0"
+description = "Local faster-whisper speech-to-text app with global hotkeys for Windows"
+readme = "README.md"
+authors = [
+    {name = "Pin Wang", email = "pinwang@gmail.com"}
+]
+requires-python = ">=3.11"
+dependencies = [
+    "faster-whisper>=1.1.1",
+    "numpy>=1.24.0",
+    "sounddevice>=0.4.6",
+    "global-hotkeys>=0.1.7; platform_system=='Windows'",
+    "pyperclip>=1.8.2",
+    "ruamel.yaml>=0.18.14",
+    "pywin32>=306; platform_system=='Windows'",
+    "pyautogui>=0.9.54; platform_system=='Windows'",
+    "pystray>=0.19.5",
+    "Pillow>=10.0.0",
+    "hf-xet>=1.1.5",
+    # Note: ten-vad git dependency handled separately
+]
+
+[project.scripts]
+whisper-key = "whisper_key.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"whisper_key" = ["assets/**/*", "config.defaults.yaml"]

whisper_key_local-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

whisper_key_local-0.3.0/src/whisper_key/audio_feedback.py

@@ -0,0 +1,56 @@
+import logging
+import os
+import threading
+import winsound
+
+from .utils import resolve_asset_path
+
+class AudioFeedback:    
+    def __init__(self, enabled=True, start_sound='', stop_sound='', cancel_sound=''):
+        self.enabled = enabled
+        self.logger = logging.getLogger(__name__)
+        
+        self.start_sound_path = resolve_asset_path(start_sound)
+        self.stop_sound_path = resolve_asset_path(stop_sound)
+        self.cancel_sound_path = resolve_asset_path(cancel_sound)
+        
+        if not self.enabled:
+            self.logger.info("Audio feedback disabled by configuration")
+            print("   ✗ Audio feedback disabled")
+        else:
+            self._validate_sound_files()
+            print("   ✓ Audio feedback enabled...")
+    
+    def _validate_sound_files(self):
+        if self.start_sound_path and not os.path.isfile(self.start_sound_path):
+            self.logger.warning(f"Start sound file not found: {self.start_sound_path}")
+        
+        if self.stop_sound_path and not os.path.isfile(self.stop_sound_path):
+            self.logger.warning(f"Stop sound file not found: {self.stop_sound_path}")
+        
+        if self.cancel_sound_path and not os.path.isfile(self.cancel_sound_path):
+            self.logger.warning(f"Cancel sound file not found: {self.cancel_sound_path}")
+    
+    def _play_sound_file_async(self, file_path: str):
+        def play_sound():
+            try:
+                # SND_FILENAME = play from file, SND_ASYNC = don't block
+                winsound.PlaySound(file_path, winsound.SND_FILENAME | winsound.SND_ASYNC)
+                
+            except Exception as e:
+                self.logger.warning(f"Failed to play sound file {file_path}: {e}")
+        
+        sound_thread = threading.Thread(target=play_sound, daemon=True)
+        sound_thread.start()
+    
+    def play_start_sound(self):
+        if self.enabled:
+            self._play_sound_file_async(self.start_sound_path)
+    
+    def play_stop_sound(self):
+        if self.enabled:        
+            self._play_sound_file_async(self.stop_sound_path)
+    
+    def play_cancel_sound(self):
+        if self.enabled:
+            self._play_sound_file_async(self.cancel_sound_path)

whisper_key_local-0.3.0/src/whisper_key/audio_recorder.py

@@ -0,0 +1,145 @@
+import logging
+import threading
+import time
+from typing import Optional
+
+import numpy as np
+import sounddevice as sd
+
+class AudioRecorder:
+    WHISPER_SAMPLE_RATE = 16000
+    THREAD_JOIN_TIMEOUT = 2.0
+    RECORDING_SLEEP_INTERVAL = 100
+    STREAM_DTYPE = np.float32
+       
+    def __init__(self, 
+                 channels: int = 1,
+                 dtype: str = "float32", 
+                 max_duration: int = 30,
+                 on_max_duration_reached: callable = None):
+        
+        self.sample_rate = self.WHISPER_SAMPLE_RATE
+        self.channels = channels
+        self.dtype = dtype
+        self.max_duration = max_duration
+        self.on_max_duration_reached = on_max_duration_reached
+        self.is_recording = False
+        self.audio_data = []
+        self.recording_thread = None
+        self.recording_start_time = None
+        self.logger = logging.getLogger(__name__)
+        
+        self._test_microphone()
+    
+    def _wait_for_thread_finish(self):
+        if self.recording_thread:
+            self.recording_thread.join(timeout=self.THREAD_JOIN_TIMEOUT)
+    
+    def _test_microphone(self):
+        try:
+            default_input = sd.query_devices(kind='input')
+            self.logger.info(f"Default microphone: {default_input['name']}")
+
+        except Exception as e:
+            self.logger.error(f"Microphone test failed: {e}")
+            raise
+    
+    def start_recording(self):
+        if self.is_recording:
+            return False
+        
+        try:
+            self.logger.info("Starting audio recording...")
+            self.is_recording = True
+            self.audio_data = []
+            self.recording_start_time = time.time()
+            
+            self.recording_thread = threading.Thread(target=self._record_audio)
+            self.recording_thread.daemon = True  # Thread will close when main program closes
+            self.recording_thread.start()
+            
+            print("🎤 Recording started! Speak now...")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to start audio recording: {e}")
+            print("❌ Failed to start recording!")
+            self.is_recording = False
+            return False
+    
+    def stop_recording(self) -> Optional[np.ndarray]:
+        if not self.is_recording:
+            return None
+        
+        self.is_recording = False
+        self._wait_for_thread_finish()
+        
+        return self._process_audio_data()
+    
+    def _process_audio_data(self) -> Optional[np.ndarray]:
+        if len(self.audio_data) == 0:
+            print("   ✗ No audio data recorded!")
+            return None
+        
+        # Convert list of audio chunks into a single numpy array
+        audio_array = np.concatenate(self.audio_data, axis=0)
+        duration = self.get_audio_duration(audio_array)
+        self.logger.info(f"Recorded {duration:.2f} seconds of audio")
+        return audio_array
+    
+    def cancel_recording(self):
+        if not self.is_recording:
+            return
+        
+        self.is_recording = False
+        self._wait_for_thread_finish()
+        
+        self.audio_data = []
+        self.recording_start_time = None
+    
+    def _record_audio(self):
+        try:
+            def audio_callback(audio_data, frames, time, status):                
+                if self.is_recording:
+                    self.audio_data.append(audio_data.copy())
+
+                if status:
+                    self.logger.debug(f"Audio callback status: {status}")
+            
+            with sd.InputStream(samplerate=self.sample_rate,
+                                channels=self.channels,
+                                callback=audio_callback,
+                                dtype=self.STREAM_DTYPE):
+                
+                while self.is_recording:
+                    if self._check_max_duration_exceeded():
+                        break
+                    
+                    sd.sleep(self.RECORDING_SLEEP_INTERVAL)
+                
+        except Exception as e:
+            self.logger.error(f"Error during audio recording: {e}")
+            self.is_recording = False
+    
+    def _check_max_duration_exceeded(self) -> bool:
+        if self.max_duration > 0 and self.recording_start_time:
+            elapsed_time = time.time() - self.recording_start_time
+            if elapsed_time >= self.max_duration:
+                self.logger.info(f"Maximum recording duration of {self.max_duration}s reached")
+                print(f"⏰ Maximum recording duration of {self.max_duration}s reached - stopping recording")
+                
+                self.is_recording = False
+                audio_data = self._process_audio_data()
+                
+                if self.on_max_duration_reached:
+                    self.on_max_duration_reached(audio_data)
+                return True
+        return False
+    
+    def get_recording_status(self) -> bool:
+        return self.is_recording
+    
+    def get_audio_duration(self, audio_data: np.ndarray) -> float:
+        if audio_data is None or len(audio_data) == 0:
+            return 0.0
+        return len(audio_data) / self.sample_rate

whisper_key_local-0.3.0/src/whisper_key/clipboard_manager.py

@@ -0,0 +1,164 @@
+import logging
+import time
+from typing import Optional
+
+import pyperclip
+import win32gui
+import pyautogui
+
+pyautogui.FAILSAFE = True  # Enable "move mouse to corner to abort automation"
+
+class ClipboardManager:    
+    def __init__(self, key_simulation_delay, auto_paste, preserve_clipboard):
+        self.logger = logging.getLogger(__name__)
+        self.key_simulation_delay = key_simulation_delay
+        self.auto_paste = auto_paste
+        self.preserve_clipboard = preserve_clipboard
+        self._configure_pyautogui_timing()
+        self._test_clipboard_access()
+        self._print_status()
+    
+    def _configure_pyautogui_timing(self):
+        pyautogui.PAUSE = self.key_simulation_delay
+    
+    def _test_clipboard_access(self):
+        try:
+            pyperclip.paste()
+            self.logger.info("Clipboard access test successful")
+            
+        except Exception as e:
+            self.logger.error(f"Clipboard access test failed: {e}")
+            raise
+    
+    def _print_status(self):
+        if self.auto_paste:
+            method_name = "key simulation (CTRL+V)"
+            print(f"   ✓ Auto-paste is ENABLED using {method_name}")
+        else:
+            print("   ✗ Auto-paste is DISABLED - paste manually with Ctrl+V")
+    
+    def copy_text(self, text: str) -> bool:
+        if not text:
+            return False
+        
+        try:
+            self.logger.info(f"Copying text to clipboard ({len(text)} chars)")
+            pyperclip.copy(text)
+            return True
+                
+        except Exception as e:
+            self.logger.error(f"Failed to copy text to clipboard: {e}")
+            return False
+    
+    def get_clipboard_content(self) -> Optional[str]:
+        try:
+            clipboard_content = pyperclip.paste()
+            
+            if clipboard_content:
+                return clipboard_content
+            else:
+                return None
+                
+        except Exception as e:
+            self.logger.error(f"Failed to paste text from clipboard: {e}")
+            return None
+    
+    def copy_with_notification(self, text: str) -> bool:
+        if not text:
+            return False
+        
+        success = self.copy_text(text)
+        
+        if success:
+            print("   ✓ Copied to clipboard")
+            print("   ✓ You can now paste with Ctrl+V in any application!")
+        
+        return success
+    
+    def clear_clipboard(self) -> bool:
+        try:
+            pyperclip.copy("")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to clear clipboard: {e}")
+            return False
+    
+    def get_active_window_handle(self) -> Optional[int]:
+        try:
+            hwnd = win32gui.GetForegroundWindow()
+            if hwnd:
+                window_title = win32gui.GetWindowText(hwnd)
+                self.logger.info(f"Active window: '{window_title}' (handle: {hwnd})")
+                return hwnd
+            else:
+                return None
+        except Exception as e:
+            self.logger.error(f"Failed to get active window handle: {e}")
+            return None       
+    
+    def execute_auto_paste(self, text: str, preserve_clipboard: bool) -> bool:              
+        try:
+            original_content = None
+            if preserve_clipboard:
+                original_content = pyperclip.paste()
+
+            if not self.copy_text(text):
+                return False
+                      
+            pyautogui.hotkey('ctrl', 'v')
+
+            print(f"   ✓ Auto-pasted via key simulation")
+
+            if original_content is not None:
+                pyperclip.copy(original_content)
+                time.sleep(self.key_simulation_delay)
+
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to simulate paste keypress: {e}")
+            return False
+        
+    def send_enter_key(self) -> bool:
+        try:
+            self.logger.info("Sending ENTER key to active application")
+            pyautogui.press('enter')
+            print("   ✓ Text submitted with ENTER!")
+
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to send ENTER key: {e}")
+            return False
+
+    def deliver_transcription(self,
+                              transcribed_text: str,
+                              use_auto_enter: bool = False) -> bool:
+        
+        try:
+            if use_auto_enter:
+                print("🚀 Auto-pasting text and SENDING with ENTER...")
+               
+                # Force auto-paste when using auto-enter hotkey
+                success = self.execute_auto_paste(transcribed_text, self.preserve_clipboard)
+                if success:
+                    success = self.send_enter_key()
+
+            elif self.auto_paste:
+                print("🚀 Auto-pasting text...")
+                success = self.execute_auto_paste(transcribed_text, self.preserve_clipboard)             
+                    
+            else:
+                print("📋 Copying to clipboard...")
+                success = self.copy_with_notification(transcribed_text)        
+
+            return success
+
+        except Exception as e:
+            self.logger.error(f"Delivery workflow failed: {e}")
+            return False
+        
+    def update_auto_paste(self, enabled: bool):
+        self.auto_paste = enabled
+        self._print_status()