Software Requirements Specification
Introduction
Purpose
This SRS defines MVP requirements for Cleanroom Whisper, an offline audio transcription app.
Scope
Product: Cleanroom Whisper — a minimal desktop app for voice-to-text using whisper.cpp.
In Scope:
Record audio from microphone
Transcribe using whisper.cpp
Store history in SQLite
Global hotkeys for hands-free operation
System tray for background operation
Out of Scope:
Cloud sync, telemetry, auto-updates
FLAC compression, MP3/M4A import
Audio playback, streaming transcription
Word timestamps, speaker diarization
Definitions
Term |
Definition |
|---|---|
whisper.cpp |
C++ implementation of OpenAI’s Whisper model |
System tray |
OS notification area (menu bar on macOS, taskbar on Windows/Linux) |
Overall Description
Product Perspective
Standalone desktop app that shells out to user-installed whisper.cpp. All processing occurs locally with no network connectivity.
See SDD for architecture diagrams and component details.
Constraints
Constraint |
Description |
|---|---|
Offline-only |
Zero network calls at runtime |
air-gap ready |
Deployable without internet access |
Platforms |
macOS, Windows, Linux (GNOME requires AppIndicator extension) |
UI model |
System tray app with native dialogs (no main window) |
Dependencies |
User installs whisper.cpp and models |
Functional Requirements
Priority: Must / Should / Could
Recording
ID |
Priority |
Title |
|---|---|---|
must |
Global Hotkey Toggle |
|
must |
Tray Icon Recording State |
|
must |
Default Microphone Input |
|
must |
WAV Audio Format |
|
should |
Recording Duration Display |
|
should |
Recording Duration Limit |
|
should |
Audio Input Device Selection |
Traceable Requirements (sphinx-needs directives):
Global hotkey toggles recording (start/stop) |
Tray icon changes color/state when recording |
Audio captured from system default microphone |
Audio saved as WAV (16kHz mono) |
Tray menu shows recording duration while active |
Configurable recording duration limit (default: 120 min) |
Audio input device selection in settings |
Transcription
ID |
Priority |
Title |
|---|---|---|
must |
Invoke Whisper.cpp |
|
must |
Parse Transcription Output |
|
must |
Transcription Notification |
|
must |
Transcription Progress Indicator |
|
must |
Transcription Error Handling |
On stop, invoke whisper.cpp with configured model |
Parse whisper.cpp stdout for transcription text. The parser SHALL extract plain text lines from stdout, ignoring timestamp prefixes and blank lines. Lines matching the pattern |
Show notification with transcription preview on completion |
Tray icon indicates transcription in progress |
Handle transcription errors with system notification |
History
ID |
Priority |
Title |
|---|---|---|
must |
Save Transcriptions to Database |
|
must |
Show Recent Transcriptions |
|
must |
Transcription Menu Preview |
|
must |
Copy Transcription on Click |
|
should |
View History Dialog |
|
should |
Delete Transcription |
Save all transcriptions to SQLite |
Tray menu shows recent transcriptions (newest first) |
Menu items show: timestamp and text preview |
Click menu item copies full transcription to clipboard |
“View History” opens native dialog with full list |
Delete transcription from history dialog |
Output
ID |
Priority |
Title |
|---|---|---|
must |
Copy Last Transcription Hotkey |
|
should |
Export Transcription to File |
Global hotkey copies most recent transcription |
Export transcription as .txt file from history dialog |
Settings
ID |
Priority |
Title |
|---|---|---|
must |
Settings Dialog |
|
must |
Configure Whisper Binary Path |
|
must |
Configure Model Path |
|
must |
Path Validation |
|
must |
Hotkey Configuration |
|
should |
First-Run Prompt |
“Settings” menu item opens native settings dialog |
Configure whisper.cpp binary path with file picker |
Configure model file path with file picker |
Validate paths exist and are accessible before save. The system SHALL verify the file exists, is readable, and (for whisper binary) is executable. Validation SHALL run on every save attempt. |
Configure global hotkeys with conflict detection |
First-run prompt when paths not configured |
System Tray
ID |
Priority |
Title |
|---|---|---|
must |
Tray Icon Status Display |
|
must |
Tray Icon Click Toggle |
|
must |
Tray Menu |
|
must |
Minimized Tray Start |
Tray icon shows app status (idle/recording/transcribing) |
Left-click tray icon toggles recording |
Right-click shows menu: Recent items, Settings, Quit |
App starts minimized to tray (no main window) |
Security
ID |
Priority |
Title |
|---|---|---|
must |
Path Sanitization |
|
must |
Parameterized Queries |
|
must |
No Network Calls |
Sanitize file paths: reject paths containing |
Use parameterized database queries |
No network calls under any circumstance |
Deployment
ID |
Priority |
Title |
|---|---|---|
must |
Offline Build Dependencies |
|
must |
Internet-Free Build |
|
should |
Single-Directory Deployment |
All dependencies available for offline build |
Build process works without internet after initial setup |
Single-directory deployment (app + whisper.cpp + model) |
Non-Functional Requirements
ID |
Priority |
Title |
|---|---|---|
must |
App Launch Time |
|
must |
Memory Footprint |
|
must |
Privacy Guarantee |
|
must |
Offline Functionality |
|
must |
Air-Gap Deployment |
|
should |
System Theme Support |
|
should |
Transcription Performance |
|
must |
Audio File Integrity |
|
must |
Database Transaction Safety |
|
must |
Graceful Whisper.cpp Failure |
|
should |
Hotkey Registration Recovery |
|
must |
Notification Clarity |
|
must |
Tray Icon State Visibility |
|
should |
Settings Discoverability |
|
should |
First-Time Setup |
|
must |
Test Coverage |
|
must |
API Documentation |
|
must |
Clippy Compliance |
|
must |
Code Formatting |
|
must |
Platform-Specific Tray Support |
|
must |
Audio Device Compatibility |
|
should |
Database Growth Handling |
|
should |
Long Audio Support |
|
should |
Large Transcription Handling |
|
could |
Local Data Encryption |
Performance
App launch time < 2 seconds |
Memory footprint < 100 MB (excluding whisper.cpp) |
Transcription completion time SHALL be within 2x the recording duration |
Reliability
The system SHALL verify WAV file integrity before transcription |
Database operations SHALL use transactions to prevent data loss |
The system SHALL handle whisper.cpp crashes gracefully without losing audio |
The system SHALL detect and recover from hotkey registration failures |
Usability
Follow system theme (dark/light) |
System notifications SHALL include clear status and transcription preview |
Tray icon SHALL clearly indicate app state (idle/recording/transcribing) |
Settings dialog SHALL provide clear labels and validation feedback |
First-time users SHALL be guided to configure whisper.cpp path via clear prompts |
Maintainability
The codebase SHALL achieve at least 80% test coverage |
All public APIs SHALL have rustdoc documentation |
The code SHALL pass cargo clippy with zero warnings |
The code SHALL be formatted with rustfmt |
Portability
The system SHALL support native tray icons on macOS, Windows, Linux (GNOME with AppIndicator) |
The system SHALL work with standard audio input devices across all platforms |
Scalability
The system SHALL handle databases with 10,000+ transcriptions without performance degradation |
The system SHALL support audio recordings up to 120 minutes. Note The SDD allows configuration up to 480 minutes; this NFR establishes the minimum supported duration. |
The system SHALL handle transcriptions with 50,000+ characters |
Security & Privacy
All data stays on user’s machine; no network calls, no telemetry |
The system COULD support optional SQLite encryption for sensitive transcriptions |
Deployment
100% functional offline |
Build and run on systems with no internet access |
Error Handling
Scenario |
Behavior |
|---|---|
Whisper binary not found |
Open settings dialog with path field focused |
Model file not found |
Open settings dialog with path field focused |
Whisper process crashes |
System notification with error, menu option to retry |
Microphone permission denied |
System notification explaining how to grant permission |
Disk full during recording |
Stop recording, save partial, system notification |
Hotkey registration failed |
System notification, app continues without that hotkey |
Hotkey conflict with system |
Warning in settings, allow override with confirmation |
Appendix: Default Hotkeys
Action |
macOS |
Windows/Linux |
|---|---|---|
Toggle recording |
|
|
Copy last |
|
|