whisper-local/openwiki/operations/runbook.md

type, title, description, tags

type	title	description	tags
Runbook	Operations-Runbook	Konfiguration, Autostart, Build/Packaging, CI/CD und Versionsverwaltung für whisper-local. Praktische Anleitungen für Betrieb und Release.	operations runbook config autostart build packaging ci versioning

Operations-Runbook

Konfiguration

Die Konfiguration liegt als TOML-Datei:

• Linux: ~/.config/whisper-local/config.toml
• Windows: %APPDATA%\whisper-local\config.toml

Die Datei wird beim ersten Start automatisch mit Defaults angelegt. Vorlage: config.example.toml.

Sektionen

Sektion	Schlüssel	Default	Beschreibung
[hotkey]	key	KEY_F12	Hotkey im evdev-Format — auch unter Windows
[whisper]	model	small	faster-whisper Modellname
[whisper]	language	de	Sprache für Transkription
[whisper]	compute_type	int8	Compute-Typ (CPU-optimiert)
[audio]	sample_rate	16000	Abtastrate in Hz
[audio]	channels	1	Anzahl Kanäle (Mono)
[audio]	min_duration	0.5	Mindestdauer in Sekunden — kürzere Aufnahmen werden verworfen
[audio]	device	""	Mikrofon-Gerätename (leer = Standardgerät)
[media]	pause_during_recording	true	Medien während Aufnahme pausieren

Config-Quellcode

config.py enthält Config-Dataclass, load_config() und save_config(). TOML-Strings werden via _toml_str() escaped (Backslash und Quotes), um ungültiges TOML bei Sonderzeichen zu verhindern.

Einstellungs-Dialog

Rechtsklick auf das Tray-Icon → „Einstellungen". Der Dialog (_settings.py) bietet:

• Hotkey-Aufzeichnung: Taste drücken → evdev-Name wird erfasst. Unter Windows zusätzlich Konflikt-Erkennung via Win32 RegisterHotKey.
• Mikrofon-Auswahl: Dropdown aller Eingabegeräte via sounddevice.query_devices().
• Medien-Pause: Checkbox für pause_during_recording.

Änderungen greifen sofort via _on_config_reload() — kein Neustart erforderlich. Siehe Aufnahme-Zyklus → Config-Reload.

Autostart

Linux (systemd user unit)

mkdir -p ~/.config/systemd/user
cp systemd/whisper-local.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now whisper-local.service

Das whisper-local-Executable muss in ~/.local/bin verfügbar sein (uv tool install . oder Pfad in der Unit anpassen). Die Unit startet nach graphical-session.target und restartet bei Fehlern.

Windows

Kein integrierter Autostart-Mechanismus. Möglichkeit: Verknüpfung zur whisper-local.exe im Autostart-Ordner (%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup).

Build und Packaging (Windows)

PyInstaller-Build

.\build.ps1              # Build + ZIP
.\build.ps1 -Clean       # dist/ und build/ löschen, dann Build
.\build.ps1 -SkipBuild   # Nur ZIP aus bestehendem dist/ erstellen

build.ps1 liest die Version aus pyproject.toml, führt uv sync --group build aus, startet PyInstaller mit whisper_local.spec und erstellt ein versioniertes ZIP (whisper-local-v{version}-win64.zip).

Die PyInstaller-Spec (whisper_local.spec) bündelt:

• ctranslate2-DLLs (Haupt-DLL, cuDNN, Intel OpenMP)
• pywin32-System-DLLs (pythoncom313.dll, pywintypes313.dll)
• PortAudio-Binaries für sounddevice
• onnxruntime (für Silero VAD in faster-whisper)
• av/FFmpeg-DLLs (per Glob gesammelt)
• sv_ttk Theme-Daten, Silero VAD ONNX-Modell

Im gebündelten Modus (sys.frozen) cacht Transcriber._model_cache_dir() das Whisper-Modell neben der EXE im models/-Verzeichnis (portabel).

CI/CD

OpenWiki-Aktualisierung

.github/workflows/openwiki-update.yml führt täglich um 08:00 Uhr (cron: "0 8 * * *") oder manuell (workflow_dispatch) ein OpenWiki-Doku-Update durch. Der Workflow:

1. Installiert OpenWiki via npm install --global openwiki.
2. Führt openwiki code --update --print aus (mit OpenRouter als Provider).
3. Erstellt einen Pull-Request via peter-evans/create-pull-request@v7 auf Branch openwiki/update.

Erforderliche Secrets: OPENROUTER_API_KEY, LANGSMITH_API_KEY.

Versionsverwaltung

Version steht in pyproject.toml (version = "1.3.0"). Der bump-version-Skill automatisiert SemVer-Bumps:

uv version --bump patch    # 1.3.0 → 1.3.1
uv version --bump minor    # 1.3.0 → 1.4.0
uv version --bump major    # 1.3.0 → 2.0.0
uv version 2.0.0           # explizite Version

Nach dem Bump wird ein Git-Commit und Tag erstellt. Der Skill ist für Claude-Code-Sessions konzipiert und fragt bei Commit-Anfragen, ob die Version mit aktualisiert werden soll.