---
type: Quickstart
title: whisper-local — Schnellstart
description: Lokales Push-to-Talk Speech-to-Text-Tool mit faster-whisper. Hotkey halten, sprechen, loslassen — Text wird ins aktive Textfeld eingefügt. Kein Cloud-Service, kein Netzwerk.
tags: [speech-to-text, whisper, push-to-talk, desktop, python]
---

# whisper-local — Schnellstart

**whisper-local** ist ein lokales Speech-to-Text-Tool für **Linux (KDE Plasma / Wayland)** und **Windows 10/11**. Ein systemweiter Hotkey (Standard: `F12`) wird gehalten, um Audio aufzunehmen; beim Loslassen transkribiert [faster-whisper](https://github.com/SYSTRAN/faster-whisper) lokal und der Text wird ins aktive Textfeld eingefügt. Die App läuft als Hintergrunddienst mit Tray-Icon.

## Installation

Voraussetzung: [uv](https://github.com/astral-sh/uv) (Python-Paketmanager), Python ≥ 3.13.

```bash
git clone <repo-url> whisper-local
cd whisper-local
uv sync
```

### Linux-Systemabhängigkeiten

```bash
sudo pacman -S ydotool wl-clipboard libayatana-appindicator gobject-introspection
sudo systemctl enable --now ydotool
sudo usermod -aG input $USER   # Neu-Login nötig
```

`ydotool` simuliert Tastatureingaben unter Wayland, `wl-clipboard` ermöglicht Clipboard-Zugriff, `libayatana-appindicator` + `gobject-introspection` stellen das Tray-Icon bereit.

Windows benötigt keine zusätzlichen System-Dependencies.

## Starten

```bash
uv run whisper-local
```

Beim ersten Start lädt faster-whisper das Whisper-Modell (Standard: `small`) herunter — ein Fortschrittsdialog erscheint. Danach ist der Hotkey aktiv und das Tray-Icon zeigt den Zustand an (grau = warten, rot = aufnehmen, gelb = transkribieren).

## Konfiguration

Die Konfigurationsdatei wird beim ersten Start automatisch angelegt:

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

Vorlage: [`config.example.toml`](../../config.example.toml). Hotkey und Mikrofon lassen sich auch über den Einstellungs-Dialog im Tray-Icon ändern (Rechtsklick → „Einstellungen"). Änderungen greifen sofort ohne Neustart. Siehe [Operations-Runbook](operations/runbook.md) für Details.

## Entwicklung

```bash
uv run pytest                    # Tests
uv run python -m whisper_local   # Direkt starten
```

## Wiki-Übersicht

| Bereich | Seite | Inhalt |
|---|---|---|
| Architektur | [Architektur-Übersicht](architecture/overview.md) | Factory-Pattern, Protocol-Interfaces, Plattform-Dispatch, Modul-Graph |
| Architektur | [Source-Map](architecture/source-map.md) | Verzeichnisstruktur, Datei-Referenzen |
| Workflows | [Aufnahme-Zyklus](workflows/recording-cycle.md) | Push-to-Talk-Flow, Media-Pause, Mikrofon-Überwachung |
| Domain | [Plattform-Abstraktionen](domain/platform-abstractions.md) | Hotkey, Inserter, Media, Microphone — Backends je Plattform |
| Operations | [Runbook](operations/runbook.md) | Konfiguration, Autostart, Build/Packaging, CI, Versionsverwaltung |
| Testing | [Test-Leitfaden](testing/guide.md) | pytest-Setup, plattformspezifische Tests, Mocking-Muster |

## Backlog

- **Linux-Inserter unter X11**: Aktuell nur Wayland (`wl-copy` + `ydotool`). X11 wird nicht unterstützt. — *Grund: Projekt zielt auf KDE/Wayland ab.*
- **Silero VAD-Integration**: faster-whisper enthält Silero VAD, wird aber nicht explizit konfiguriert. — *Grund: Keine Quell-Referenz gefunden; nur in PyInstaller-Spec als Bundle-Dependency sichtbar.*