How jeffrey94/windows-whisper works
Project Type and Purpose
• This is a Windows desktop application that provides a lightweight voice-to-text functionality using OpenAI’s Whisper API.
• It is triggered by a global hotkey (Ctrl + Space), captures audio from the microphone, displays a minimal overlay UI during recording, sends the audio to the Whisper API for transcription, and then automatically copies the resulting text to the clipboard.
• Key functionalities include global shortcut triggering, audio recording, transcription via an external API, a modern overlay UI (likely built with a framework like PyQt5), and clipboard integration.
Key Components
a. Entry Point:
• main.py: This is the starting point of the application that initializes and coordinates the overall workflow.
b. Configuration:
• config.py and .env file: Used for setting environment parameters like OPENAI_API_KEY, hotkey definitions, recording duration, etc.
c. Global Hotkey Module:
• src/hotkey.py: Listens for the Ctrl + Space shortcut and triggers the recording process.
d. Audio Recording Module:
• src/audio.py: Captures audio input when the hotkey event is triggered.
e. Transcription Module:
• src/whisper_api.py: Interfaces with OpenAI’s Whisper API, sending recorded audio and receiving the transcription.
f. Clipboard Handling Module:
• src/clipboard.py: Automatically copies the transcription to the system clipboard.
g. UI/Overlay Module:
• src/ui/overlay.py: Provides the floating overlay UI that shows the recording status and update indicators.
h. Utility Functions:
• src/utils.py: Contains helper methods that may be used across multiple modules.
i. External Dependencies:
• OpenAI’s Whisper API: An external, cloud-based transcription service.
• PyQt5 (or similar, as inferred from the README and the "Modern UI" reference): For building the overlay interface.
• Windows specific APIs for global hotkey detection and clipboard interaction.
Relationships and Interactions
• The main entry point (main.py) interacts with config.py to load environment variables and determine runtime settings.
• On detecting a global hotkey event via src/hotkey.py, the application instructs src/audio.py to begin recording.
• Once the audio is captured, src/whisper_api.py is called to perform transcription by communicating with the external Whisper API.
• After transcription, src/clipboard.py ensures the text is copied to the clipboard automatically.
• Throughout the process, src/ui/overlay.py manages the display of a minimal and informative overlay that reflects recording status, progress, and transient notifications.
• All modules may leverage utility functions from src/utils.py.
Architectural Patterns and Design Principles
• Modular design: Each functionality is encapsulated in dedicated modules which simplifies maintenance and testing.
• Separation of concerns: There is a clean differentiation between core business logic (audio processing, transcription, clipboard handling) and UI/OS interactions.
• Event-driven architecture: Hotkey detection serves as the event that triggers the audio recording and subsequent actions.
• External service integration: The transcription functionality is offloaded to OpenAI’s Whisper API.
Overall Detailing
• Data flows (audio data, transcribed text) and configuration-driven decision points.