111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
|
---
|
||
|
|
type: Runbook
|
||
|
|
title: Operations-Runbook
|
||
|
|
description: Konfiguration, Autostart, Build/Packaging, CI/CD und Versionsverwaltung für whisper-local. Praktische Anleitungen für Betrieb und Release.
|
||
|
|
tags: [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`](../../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`](../../whisper_local/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`](../../whisper_local/tray/_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](../workflows/recording-cycle.md#config-reload-zur-laufzeit).
|
||
|
|
|
||
|
|
## Autostart
|
||
|
|
|
||
|
|
### Linux (systemd user unit)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
.\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`](../../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](../../.claude/skills/bump-version/SKILL.md) automatisiert SemVer-Bumps:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|