Software requirements
Classification: Internal ·
Version: 1.0 ·
Audience: Engineering leadership ·
Primary focus: Platform, dependencies, security
Formal platform, security, and delivery requirements for the Voice Hotkey application.
Product context is in the
Executive overview;
UX detail is in the
Design guide.
1. Platform requirements
| Requirement | Specification |
|---|
| Operating system | Linux (kernel 5.x+) |
| Display server | X11 or Wayland with XWayland |
| Python | 3.9 or later |
| Audio subsystem | PulseAudio or PipeWire (via PortAudio) |
| Clipboard | xclip, xsel, or wl-copy |
| FFmpeg | Required by Whisper for audio decoding |
2. Python dependencies
| Package | Purpose | License |
|---|
pynput | Global keyboard listener | LGPL-3.0 |
sounddevice | Audio capture via PortAudio | MIT |
numpy | Audio buffer management | BSD |
openai-whisper | Local speech-to-text | MIT |
pyperclip | Cross-platform clipboard | BSD |
tomli | TOML parsing (Python < 3.11) | MIT |
3. Security requirements
- No secrets in repository: API keys (if using cloud Whisper) must be in local config or environment variables.
.gitignore excludes config.toml and .env.
- Audio privacy: Audio is recorded to memory only—not written to disk by default. Temporary WAV files, if created, are deleted after transcription.
- Permissions: Requires access to input devices (
/dev/input) and audio devices. May need to be run with appropriate group membership (e.g. input group).
- Network: MVP uses local Whisper inference—no network access required. Cloud API mode (future) requires HTTPS to OpenAI API.
4. Configuration specification
Config path: ~/.config/voice-hotkey/config.toml (respects $XDG_CONFIG_HOME).
| Section | Key | Type | Default | Description |
|---|
[hotkey] | key | string | "Key.ctrl_r" | pynput key name |
| double_click_ms | int | 400 | Max interval between taps |
[recording] | sample_rate | int | 16000 | Samples per second |
| timeout_seconds | int | 30 | Auto-stop after N seconds |
[whisper] | model | string | "base" | Whisper model size |
| language | string | "en" | Language or "auto" |
[output] | target | string | "clipboard" | Output destination |
5. Delivery
- Repository:
github.com/shahzebqazi/voice-key
- Branch model:
main — single branch for MVP.
- Installation:
pip install -r requirements.txt in a virtual environment.
- Execution:
python -m app.main
- GitHub Pages: Static site at
https://sqazi.sh/voice-key/
← Back to Voice Hotkey