---
type: SourceMap
title: Source-Map
description: Verzeichnisstruktur und Datei-Referenzen für whisper-local. Jede Datei mit ihrer Verantwortung.
tags: [source-map, file-inventory]
---

# Source-Map

## Projekt-Root

| Datei | Beschreibung |
|---|---|
| `pyproject.toml` | Projekt-Metadaten, plattformabhängige Dependencies, Entry-Point `whisper-local` |
| `config.example.toml` | Konfigurations-Vorlage mit allen Sektionen und Defaults |
| `uv.lock` | Lock-File für reproduzierbare Installationen |
| `build.ps1` | Windows-Build-Skript: PyInstaller + versioniertes ZIP |
| `whisper_local.spec` | PyInstaller-Build-Konfiguration (DLLs, Datas, Hidden-Imports) |
| `README.md` | Nutzer-Dokumentation: Installation, System-Dependencies, Konfiguration |
| `CLAUDE.md` | Agent-Instruktionen: Entwicklungsumgebung, Architektur, Test-Konventionen |
| `AGENTS.md` | OpenWiki-Referenz für automatisierte Doku-Updates |

## `whisper_local/` — Hauptpaket

| Datei | Verantwortung |
|---|---|
| `__init__.py` | Paket-Marker |
| `__main__.py` | `App`-Klasse, `main()`-Entry-Point, Orchestrator für alle Module |
| `config.py` | `Config`-Dataclass, `load_config()`, `save_config()` — TOML-basiert |
| `recorder.py` | `Recorder`-Klasse — Audio-Aufnahme via `sounddevice.InputStream` |
| `transcriber.py` | `Transcriber`-Klasse — `faster_whisper.WhisperModel`, Modell-Cache-Logik |

### `whisper_local/hotkey/` — Hotkey-Listener

| Datei | Beschreibung |
|---|---|
| `__init__.py` | `HotkeyListener`-Protocol, `create_listener()`-Factory |
| `_evdev.py` | Linux: `EvdevHotkeyListener` — lauscht auf `/dev/input/event*` |
| `_pynput.py` | Windows: `PynputHotkeyListener` — pynput mit Key-Repeat-Unterdrückung |

### `whisper_local/inserter/` — Text-Einfügung

| Datei | Beschreibung |
|---|---|
| `__init__.py` | `Inserter`-Protocol, `create_inserter()`-Factory |
| `_wayland.py` | Linux: `WaylandInserter` — `wl-copy` + `ydotool key Ctrl+V`, Clipboard-Restaurierung |
| `_win32.py` | Windows: `Win32Inserter` — `win32clipboard` + pynput `Ctrl+V`, Clipboard-Restaurierung |

### `whisper_local/media/` — Medien-Steuerung

| Datei | Beschreibung |
|---|---|
| `__init__.py` | `MediaController`-Protocol, `create_media_controller()`-Factory |
| `_mpris.py` | Linux: `MprisController` — D-Bus MPRIS2, pausiert alle Playing-Sessions |
| `_smtc.py` | Windows: `SmtcController` — Windows SMTC via `winrt` |
| `_noop.py` | `NoopController` — No-Op-Fallback |

### `whisper_local/microphone/` — Mikrofon-Überwachung

| Datei | Beschreibung |
|---|---|
| `__init__.py` | `MicrophoneMonitor`-Protocol, `create_monitor()`-Factory |
| `_poll.py` | `PollMonitor` — Cross-Platform Polling via `sounddevice.query_devices()` |
| `_win32.py` | `Win32Monitor` — COM `IMMNotificationClient` mit Polling-Fallback |

### `whisper_local/tray/` — Tray-Icon und UI

| Datei | Beschreibung |
|---|---|
| `__init__.py` | `create_tray()`-Factory, `AppState`-Re-Export |
| `_tray.py` | `PystrayApp` (Tray-Icon, Menu, Zustand), `NoOpTray`, `AppState`-Enum |
| `_icon.py` | `create_icon()` — Pillow-basierte Mikrofon-Icon-Generierung je Zustand |
| `_settings.py` | `SettingsDialog` — Tkinter-Dialog für Hotkey, Mikrofon, Medien-Pause |
| `_download_progress.py` | `load_model_with_progress()` — Tkinter-Fortschrittsdialog für Modell-Download |
| `_notification.py` | `notify()` — notify-py Wrapper für Desktop-Benachrichtigungen |
| `_theme.py` | `apply_system_theme()` — sv-ttk + darkdetect |
| `_hotkey_record_pynput.py` | Windows: Hotkey-Aufzeichnung + `check_hotkey_conflict()` via Win32 `RegisterHotKey` |
| `_hotkey_record_evdev.py` | Linux: Hotkey-Aufzeichnung via evdev-Selector |

## `tests/` — Test-Suite

| Datei | Test-Bereich |
|---|---|
| `test_config.py` | Config laden/speichern, Defaults, TOML-Escaping |
| `test_recorder.py` | Recorder start/stop, min_duration-Filter |
| `test_transcriber.py` | Transcriber mit gemocktem WhisperModel |
| `test_hotkey.py` | EvdevHotkeyListener + PynputHotkeyListener, Key-Repeat-Unterdrückung |
| `test_inserter.py` | WaylandInserter + Win32Inserter, Clipboard-Restaurierung |
| `test_media_factory.py` | Factory-Dispatch für MediaController |
| `test_media_mpris.py` | MprisController pause/resume, Circuit-Breaker |
| `test_media_smtc.py` | SmtcController pause/resume, Circuit-Breaker |
| `test_microphone_monitor.py` | PollMonitor Geräte-Erkennung, Start-Check |
| `test_tray.py` | Tray-App, AppState, Icon-Generierung, Settings-Dialog |
| `test_download_progress.py` | Download-Fortschrittsdialog |
| `test_main.py` | App-Integration: Aufnahme-Zyklus, Config-Reload, Mikrofon-Callbacks |

## `docs/superpowers/` — Specs und Pläne

Design-Specs (`specs/`) und Implementierungspläne (`plans/`) für jede Feature-Entwicklung. Die Doku-Sprache ist Deutsch. Die Specs dokumentieren Architektur-Entscheidungen vor der Implementierung und sind wertvoll für das Verständnis historischer Design-Rationale.

## Weitere Verzeichnisse

| Pfad | Beschreibung |
|---|---|
| `systemd/` | `whisper-local.service` — systemd-User-Unit für Linux-Autostart |
| `.github/workflows/` | `openwiki-update.yml` — tägliche OpenWiki-Doku-Aktualisierung |
| `.claude/skills/bump-version/` | Claude-Code-Skill für SemVer-Versionsverwaltung via `uv version --bump` |
| `build/`, `dist/` | PyInstaller-Build-Artifacts (gitignored) |