docs: add GUI app design spec
This commit is contained in:
beo3000
parent
2464081f4c
commit
ebfd751e8d
|
|
@ -0,0 +1,184 @@
|
||||||
|
# Whisper Dictation — GUI App Design
|
||||||
|
|
||||||
|
**Date:** 2026-03-20
|
||||||
|
**Status:** Approved
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Convert the existing `dictate.py` script into a proper packaged desktop application that:
|
||||||
|
- Runs without a terminal window on Windows and Linux
|
||||||
|
- Shows a compact log/status panel accessible from the tray icon
|
||||||
|
- Can be integrated into the system (autostart, start menu, desktop shortcut)
|
||||||
|
- Is distributed as a standalone binary via PyInstaller
|
||||||
|
|
||||||
|
## Module Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
whisper-dictation/
|
||||||
|
├── main.py # Entry point
|
||||||
|
├── build.py # PyInstaller build script (platform-specific)
|
||||||
|
├── whisper-dictation.spec # PyInstaller spec (manual, for ctranslate2)
|
||||||
|
├── whisper_app/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── app.py # AppState, central coordination, log queue
|
||||||
|
│ ├── audio.py # sounddevice stream, audio_callback
|
||||||
|
│ ├── transcriber.py # WhisperModel, stop_and_transcribe()
|
||||||
|
│ ├── hotkey.py # HotkeyListener (unchanged)
|
||||||
|
│ ├── config.py # load/save config + vocab, path resolution
|
||||||
|
│ ├── typer.py # type_text(), cross-platform
|
||||||
|
│ ├── tray.py # pystray icon + menu
|
||||||
|
│ ├── log_window.py # Compact log panel
|
||||||
|
│ ├── settings_window.py # Settings dialog
|
||||||
|
│ ├── vocab_window.py # Vocabulary dialog
|
||||||
|
│ ├── overlay.py # "Recording..." overlay
|
||||||
|
│ └── installer.py # System integration (autostart, start menu, shortcut)
|
||||||
|
├── config.json # Shared config (git-tracked)
|
||||||
|
├── vocabulary.json # Shared vocabulary (git-tracked)
|
||||||
|
├── start.sh # Dev start (Linux)
|
||||||
|
└── start.bat # Dev start (Windows)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Path Handling
|
||||||
|
|
||||||
|
All path resolution lives in `config.py`. Must work in two modes:
|
||||||
|
|
||||||
|
```python
|
||||||
|
import sys, os
|
||||||
|
|
||||||
|
def _app_dir() -> str:
|
||||||
|
"""Root dir for config.json and vocabulary.json."""
|
||||||
|
if getattr(sys, "frozen", False):
|
||||||
|
# PyInstaller binary: use directory containing the executable
|
||||||
|
return os.path.dirname(sys.executable)
|
||||||
|
else:
|
||||||
|
# Dev mode: use script directory (git repo root)
|
||||||
|
return os.path.dirname(os.path.abspath(__file__ + "/../../"))
|
||||||
|
```
|
||||||
|
|
||||||
|
Machine-local config (`config_local.json`) continues to use `%LOCALAPPDATA%\WhisperDictation` (Windows) or `~/.local/share/WhisperDictation` (Linux) — unchanged.
|
||||||
|
|
||||||
|
## Logging Architecture
|
||||||
|
|
||||||
|
`app.py` owns a `queue.Queue[str]` and a pre-queue buffer list.
|
||||||
|
|
||||||
|
```python
|
||||||
|
_log_buffer: list[str] = [] # before queue is ready
|
||||||
|
_log_queue: queue.Queue | None = None
|
||||||
|
|
||||||
|
def log(msg: str) -> None:
|
||||||
|
if _log_queue is not None:
|
||||||
|
_log_queue.put(msg)
|
||||||
|
else:
|
||||||
|
_log_buffer.append(msg)
|
||||||
|
|
||||||
|
def set_log_queue(q: queue.Queue) -> None:
|
||||||
|
global _log_queue
|
||||||
|
_log_queue = q
|
||||||
|
for msg in _log_buffer:
|
||||||
|
q.put(msg)
|
||||||
|
_log_buffer.clear()
|
||||||
|
```
|
||||||
|
|
||||||
|
All `print()` calls in all modules are replaced with `app.log()`.
|
||||||
|
|
||||||
|
## Log Panel (Compact)
|
||||||
|
|
||||||
|
Opened via tray icon left-click or "Anzeigen" menu item. Implemented in `log_window.py`.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────┐
|
||||||
|
│ ● WHISPER DICTATION medium·de ✕ │
|
||||||
|
├─────────────────────────────────────┤
|
||||||
|
│ Model ready. │
|
||||||
|
│ Hotkey: ctrl+shift+space │
|
||||||
|
│ ● Recording... │
|
||||||
|
│ Audio: 2.1s RMS: 0.048 │
|
||||||
|
│ ✓ "Das ist ein Test" │
|
||||||
|
├─────────────────────────────────────┤
|
||||||
|
│ ⚙ Einstellungen 📚 Vokabular 🗑 │
|
||||||
|
└─────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
- Size: ~380×220px, **not resizable**
|
||||||
|
- `tk.Text` widget in read-only mode, max 200 lines (older lines discarded)
|
||||||
|
- Auto-scroll to bottom on new messages
|
||||||
|
- Color tags: green = ready/result, red = recording, yellow = transcribing, grey = info
|
||||||
|
- Close button → `withdraw()` (does not quit the app)
|
||||||
|
- 🗑 button → clears the text widget
|
||||||
|
- Queue polled via `root.after(100, _poll_log_queue)`
|
||||||
|
|
||||||
|
## Settings Window — Installation Section
|
||||||
|
|
||||||
|
New section "INSTALLATION" added to the existing settings window. Implemented in `installer.py`.
|
||||||
|
|
||||||
|
Each integration shows status ("eingerichtet" / "nicht eingerichtet") and two buttons: "Einrichten" / "Entfernen".
|
||||||
|
|
||||||
|
| Feature | Windows | Linux |
|
||||||
|
|---|---|---|
|
||||||
|
| Autostart beim Login | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` | `~/.config/autostart/whisper-dictation.desktop` |
|
||||||
|
| Startmenü-Eintrag | `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Whisper Dictation.lnk` | `~/.local/share/applications/whisper-dictation.desktop` |
|
||||||
|
| Desktop-Verknüpfung | `%USERPROFILE%\Desktop\Whisper Dictation.lnk` | `~/Desktop/whisper-dictation.desktop` |
|
||||||
|
|
||||||
|
Windows `.lnk` files are created via `pywin32` (`win32com.client.Dispatch("WScript.Shell")`).
|
||||||
|
|
||||||
|
**Only available when running as a frozen binary.** In dev mode, the buttons are disabled with a tooltip "Nur im gebauten Binary verfügbar".
|
||||||
|
|
||||||
|
## Icon
|
||||||
|
|
||||||
|
The existing tray icon (64×64 PIL `Image`) is extended:
|
||||||
|
- At build time, `build.py` generates `icon.ico` (sizes: 16, 32, 48, 256) via Pillow
|
||||||
|
- Used as the PyInstaller `--icon` and for `.lnk` shortcuts
|
||||||
|
|
||||||
|
## PyInstaller Build
|
||||||
|
|
||||||
|
### Manual `.spec` file (required for ctranslate2/faster-whisper)
|
||||||
|
|
||||||
|
```python
|
||||||
|
# whisper-dictation.spec (key sections)
|
||||||
|
a = Analysis(
|
||||||
|
['main.py'],
|
||||||
|
hiddenimports=[
|
||||||
|
'ctranslate2',
|
||||||
|
'faster_whisper',
|
||||||
|
'sounddevice',
|
||||||
|
'pynput.keyboard._win32', # Windows
|
||||||
|
'pynput.keyboard._xorg', # Linux
|
||||||
|
],
|
||||||
|
datas=[
|
||||||
|
('config.json', '.'),
|
||||||
|
('vocabulary.json', '.'),
|
||||||
|
],
|
||||||
|
)
|
||||||
|
exe = EXE(a.pure, ..., console=False, icon='icon.ico')
|
||||||
|
```
|
||||||
|
|
||||||
|
### `build.py`
|
||||||
|
|
||||||
|
1. Generates `icon.ico` from PIL
|
||||||
|
2. Runs PyInstaller with the `.spec` file
|
||||||
|
3. Copies `config.json` and `vocabulary.json` into `dist/whisper-dictation/`
|
||||||
|
|
||||||
|
### Platform requirement
|
||||||
|
|
||||||
|
PyInstaller cannot cross-compile. **Build must be run separately on each platform:**
|
||||||
|
- Windows: `python build.py` → `dist/whisper-dictation/whisper-dictation.exe`
|
||||||
|
- Linux: `python build.py` → `dist/whisper-dictation/whisper-dictation`
|
||||||
|
|
||||||
|
## New Dependencies
|
||||||
|
|
||||||
|
| Package | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `pywin32` | `.lnk` shortcut creation (Windows only) |
|
||||||
|
|
||||||
|
Added to `requirements-windows.txt`. Not required on Linux.
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- Code signing / notarization
|
||||||
|
- Auto-updater
|
||||||
|
- Versioning
|
||||||
|
- Cross-compilation
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
_(none — all resolved during design session)_
|
||||||
Loading…
Reference in New Issue