---
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.