whisper-local/docs/superpowers/specs/2026-04-12-model-download-progress-dialog-design.md

Design: Modell-Lade-Wartebalken

Datum: 2026-04-12 Zuletzt geändert: 2026-04-16 Status: Umgesetzt

Problemstellung

Beim ersten Start lädt faster_whisper das Whisper-Modell von HuggingFace herunter (z.B. small ≈ 460 MB). Dieser Vorgang blockiert App.__init__() ohne jede Rückmeldung. Der Nutzer sieht einen eingefrorenen Start ohne Statusanzeige.

Ziel

Ein kleiner tkinter-Dialog erscheint automatisch, wenn das Laden des Modells länger als 500 ms dauert, und zeigt einen animierten Wartebalken. Ist das Modell bereits vollständig gecacht und wird in unter 500 ms bereit, erscheint kein Dialog.

Verworfener Ansatz: tqdm-Monkey-Patch

Die ursprüngliche Idee war, tqdm.tqdm während des Downloads mit einer eigenen Klasse (TkProgressTqdm) zu ersetzen und echten Byte-Fortschritt anzuzeigen. Dieser Ansatz funktioniert nicht mehr, weil huggingface_hub für große Dateien (model.bin) die Xet-Engine (Rust) nutzt, die Python-tqdm komplett bypasst. Der Dialog blieb dadurch leer, bis der Download fertig war.

Die Klasse TkProgressTqdm existiert noch im Code (mit Unit-Tests), wird aber von der Lade-Funktion nicht mehr aktiviert — sie bleibt als möglicher Fallback erhalten, falls zukünftige faster_whisper-Versionen wieder durch Python-tqdm laufen.

Aktueller Ansatz: Timeout-basierter Wartebalken

1. Worker-Thread startet WhisperModel(...).
2. Hauptthread wartet via threading.Event.wait(timeout=0.5).
3. Ist der Thread innerhalb von 500 ms fertig (vollständiger Cache) → kein Dialog, direkter Rückweg.
4. Sonst → tkinter-Dialog mit indeterminatem ttk.Progressbar öffnen, bis der Worker signalisiert.

Architektur & Ablauf

main()
  └─ App.__init__()
       ├─ load_model_with_progress(model_name, compute_type, download_root)
       │    ├─ [Daemon-Thread] WhisperModel(...)
       │    └─ [Hauptthread] done_event.wait(0.5)
       │         ├─ sofort fertig → Modell zurückgeben (kein Dialog)
       │         └─ Timeout → tkinter-Fenster + Indeterminate-Progressbar
       │              └─ root.after(100, poll) bis done_event.is_set()
       └─ Transcriber(model=fertig_geladenes_modell)

Dialog läuft plattformübergreifend (Linux + Windows) — tkinter gehört zur Standardbibliothek.

Komponenten

Datei: whisper_local/tray/_download_progress.py

TkProgressTqdm — ungenutzter tqdm.tqdm-Ersatz (historischer Fallback):

• Erbt von tqdm.tqdm
• Akkumuliert Fortschritt und schreibt Messages in TkProgressTqdm._queue, falls gesetzt
• Wird derzeit nicht aktiviert (Xet bypasst tqdm)

load_model_with_progress(model_name, compute_type, download_root) -> WhisperModel — öffentliche Funktion:

1. Startet Daemon-Thread mit WhisperModel(...)
2. Wartet 500 ms via done_event.wait(timeout=0.5)
3. Kehrt bei schnellem Abschluss direkt zurück
4. Öffnet sonst tkinter-Fenster mit indeterminatem ttk.Progressbar
5. Pollt done_event alle 100 ms via root.after und beendet mainloop() bei Signal
6. Bei Exception im Worker: messagebox.showerror + sys.exit(1)

Datei: whisper_local/__main__.py

App.__init__() ruft load_model_with_progress() auf (plattformunabhängig) und übergibt das fertige WhisperModel-Objekt an Transcriber.

Datei: whisper_local/transcriber.py

Transcriber.__init__() akzeptiert optional ein bereits geladenes WhisperModel-Objekt via Parameter model: WhisperModel | None = None.

Dialog-Darstellung

• Titel: "whisper-local – Modell wird geladen"
• Label oben: "Lade Whisper-Modell '<model_name>'..."
• Label darunter: "Bitte warten…" (grau)
• ttk.Progressbar im indeterminate-Modus (Länge 320 px, via pb.start(10) animiert)
• Kein Abbrechen-Button
• apply_system_theme(root) für konsistentes Aussehen
• root.resizable(False, False)

Threading-Modell

Thread	Aufgabe
Hauptthread	done_event.wait(0.5), tkinter mainloop(), Polling via root.after
Daemon-Thread	WhisperModel(...)

Kommunikation über threading.Event (kein Monkey-Patch, keine Queue in der Lade-Funktion).

Fehlerbehandlung

• Kein Internet / Download-Fehler: Exception im Thread → nach done_event.set() im Hauptthread geprüft → messagebox.showerror("Fehler beim Modell-Laden", str(exc)) → sys.exit(1)
• Modell bereits gecacht und schnell bereit: done_event.wait(0.5) returnt True → kein Dialog erscheint

Plattform

Kein Plattform-Guard — load_model_with_progress() läuft auf Linux und Windows identisch. tkinter ist Teil der Python-Standardbibliothek und auf beiden Systemen verfügbar.

Dateien

Datei	Status
whisper_local/tray/_download_progress.py	Umgesetzt (Timeout-basierter Wartebalken)
whisper_local/__main__.py	Umgesetzt (Preload plattformübergreifend)
whisper_local/transcriber.py	Umgesetzt (optionaler model-Parameter)
tests/test_download_progress.py	Vorhanden (deckt ungenutzte TkProgressTqdm ab)
tests/test_transcriber.py	Vorhanden (deckt model-Parameter ab)