Blitztext Linux

Dein lokaler KI-Sprachassistent für KDE Plasma & Wayland

Sprache per Hotkey aufnehmen, lokal oder online transkribieren, optional per LLM umschreiben und direkt in die aktive Anwendung einfügen.

Important

Eigenständiger Linux-Port: Dieses Repository enthält ausschließlich den Linux-Port von Blitztext – eine eigenständige Python 3/PyQt6-Implementierung optimiert für Kubuntu/Ubuntu unter KDE Plasma mit Wayland. Für die originale macOS-Version besuche bitte das offizielle Haupt-Repository.

---

Features

• NEU: Eigennamen / Begriffe: Erweitere das Vokabular der KI um eigene Begriffe, Namen oder Fachwörter für perfekte Transkriptionen.

• Globale Hotkeys: Jederzeit von überall im System aufnehmen.

• Auto-Paste: Erkennt Sprache und fügt sie direkt dort ein, wo der Cursor ist.

• LLM-gestützte Workflows: Lass die KI deine Sätze professionell umformulieren, emotional filtern oder mit passenden Emojis anreichern.

• Lokale Verarbeitung: Optional 100% offline für volle Privatsphäre.

---

Installation

Schnellinstallation (empfohlen)

Der einfachste Weg, um Blitztext auf deinem System bereitzustellen:

git clone https://github.com/TimInTech/blitztext-linux.git
cd blitztext-linux
bash scripts/install.sh

Was macht das Skript? Es ist idempotent (mehrfach ausführbar) und erledigt alles vollautomatisch:

1. Prüft dein System (Ubuntu/Debian) & Python-Version.
2. Installiert fehlende Systempakete (inkl. pipx).
3. Richtet eine .venv Umgebung ein und installiert openai-whisper/faster-whisper.
4. Bereitet ydotool.service und den systemd-User-Service vor.

Nach der Installation

1. Neustart erforderlich (oder ab-/anmelden), damit die Gruppe input aktiv wird. Danach checken:

   bash scripts/verify.sh

2. Manuell testen:

   ./run.sh

   (Erscheint das Tray-Symbol und reagieren die Hotkeys? Dann lief alles glatt!)
3. Autostart aktivieren:

   systemctl --user start blitztext-linux

Autostart wieder deaktivieren

systemctl --user stop blitztext-linux
systemctl --user disable blitztext-linux

Manuelle Installation (Diagnose / Experten)

Falls du gezielt debuggen möchtest, anstatt scripts/install.sh zu nutzen:

1. Systempakete (apt)

sudo apt install pulseaudio-utils wl-clipboard xclip ydotool ffmpeg python3-venv python3-evdev build-essential python3-dev socat pipx

Paket	Zweck
pulseaudio-utils	parec für die Audioaufnahme via PulseAudio/PipeWire
wl-clipboard / xclip	Zwischenablage unter Wayland (wl-copy) bzw. X11-Fallback
ydotool (≥ 1.0)	Simuliert Ctrl+V für automatisches Einfügen (Auto-Paste). Ab Version 1.0 werden rohe Keycodes verwendet. Ubuntu 25.10/26.04 liefern ydotool ≥ 1.0 (1.0.4) direkt via apt. Ubuntu 24.04 und 22.04 liefern per apt nur 0.1.x (z. B. 0.1.8), das keine Keycodes unterstützt und damit kein Auto-Paste – dort ydotool ≥ 1.0 aus dem Quellcode bauen (siehe unten). Auto-Paste auf 24.04, 25.10 und 26.04 verifiziert.
ffmpeg	Audio-Konvertierungen
python3-evdev	Eingabegeräte-Zugriff für den systemweiten Hotkey-Daemon
socat	Optionale Socket-Kommunikation
pipx	Isolierte Installation von Whisper-Engines

2. evdev-Rechte vergeben

sudo usermod -aG input $USER

3. Virtuelle Umgebung & Python-Pakete

python3 -m venv .venv
source .venv/bin/activate
pip install PyQt6 evdev openai pytest openai-whisper faster-whisper

4. Whisper-Engine als Alternative via pipx Falls Sie openai-whisper losgelöst von der venv installieren möchten (umgeht Versionskonflikte auf neueren Ubuntu-Setups durch Python 3.11):

pipx install --python "$(command -v python3.11)" openai-whisper
pipx inject openai-whisper faster-whisper   # optional, für beschleunigte Ausführung

5. ydotool prüfen

systemctl --user start ydotool.service

Liefert apt nur ydotool 0.1.x (Ubuntu 24.04/22.04), ydotool ≥ 1.0 aus dem Quellcode bauen:

sudo apt install cmake build-essential scdoc git
git clone --depth 1 --branch v1.0.4 https://github.com/ReimuNotMoe/ydotool.git
cd ydotool && cmake -B build -DCMAKE_BUILD_TYPE=Release && make -C build && sudo make -C build install
systemctl --user enable --now ydotool.service   # nutzt /usr/local/bin/ydotoold

6. Anwendung starten

./run.sh

---

Die 5 Workflows und Hotkeys

Blitztext registriert globale Hotkeys via evdev. Mit diesen Kombinationen hast du die volle Kontrolle:

Workflow	Hotkey	LLM?	Beschreibung
Blitztext	Meta + H	❌	Standard: Nimmt auf, transkribiert und fügt den Text ein.
Blitztext Lokal	Meta + Shift + H	❌	Erzwingt eine reine Offline-Transkription.
Blitztext+	Meta + Shift + T	✅	Formuliert deine Aufnahme professionell via LLM um.
Blitztext $%&!	Meta + Shift + D	✅	Emotionale Entladung: Wandelt Frust in eine sachliche Nachricht um.
Blitztext :)	Meta + Shift + E	✅	Ergänzt deine Nachricht passend mit Emojis.

Note

LLM-Workflows (Blitztext+, Blitztext $%&!, Blitztext :)) setzen einen gültigen OpenAI API-Key voraus. Lege ihn am einfachsten in ~/.config/blitztext-linux/secrets.env ab, indem du dort die Variable OPENAI_API_KEY mit deinem Key als Wert setzt (Zeilenformat NAME=WERT). ./run.sh und der systemd-Service laden diese Datei automatisch. Ohne diesen Key sind diese Funktionen im Menü und über die Hotkeys deaktiviert bzw. führen zu einer Fehlermeldung.

KI-Workflows

Die KI-Workflows helfen bei Formulierung, Ton und Emojis. Die passenden Einstellungen findest du direkt in der App:

Schreibstil-Vorlagen

Für den Workflow Blitztext+ (Text-Verbesserer) gibt es vorgefertigte Schreibstil-Vorlagen, die du unter Einstellungen → KI-Workflows → „Schreibstil-Vorlage" auswählst:

Vorlage	Wirkung
Standard (Text verbessern)	Bisheriges Verhalten – sauber formatierter Text, der gewählte Tonfall greift.
E-Mail – formell	Höfliche E-Mail in der Sie-Form mit klarer Struktur.
E-Mail – locker	Freundliche E-Mail in der Du-Form.
Stichpunkte	Gliedert den Inhalt in prägnante Stichpunkte.
Zusammenfassung	Knappe, sachliche Zusammenfassung der Kernaussagen.
Persönlich (Du-Form)	Klarer Text in der persönlichen Du-Form.
Höflich (Sie-Form)	Klarer Text in der höflichen Sie-Form.
Kurz & präzise	Maximal knapp, ohne Füllwörter und Wiederholungen.

Bei Standard wird zusätzlich der eingestellte Tonfall angewendet. Jede andere Vorlage bringt ihren eigenen Schreibstil mit und ersetzt den Tonfall. Eigennamen/Begriffe bleiben in allen Vorlagen erhalten.

---

Tray-Symbol: Statusfarben

Das Mikrofon im System-Tray ist dein Indikator für den aktuellen Zustand:

Grün (IDLE) Bereit — wartet auf deinen Einsatz.

Rot (RECORDING) Aufnahme läuft aktiv.

Orange (TRANSCRIBING) Magie läuft (Transkription / KI-Umformulierung).

Grau (ERROR) Ups, etwas ist schiefgelaufen.

Note

Steht im Desktop-Environment kein Tray-Bereich zur Verfügung, fällt das Icon auf das System-Theme audio-input-microphone zurück; die Farbkodierung greift dann ggf. nicht.

---

Hauptfenster (grafischer Fallback)

Falls du keine Tastatur parat hast oder Hotkeys blockiert sind:

• Maus-Steuerung: Start/Stopp-Button für die Aufnahme.
• Workflow-Menü: Dropdown für alle 5 Modi.
• Abbruch: Verwirft eine Aufnahme sofort ohne Transkription.
• Schnellzugriffe: Diktat, Verlauf, Vorlesen und Einstellungen.

Das Fenster öffnet sich beim Start sowie über den Tray-Eintrag Fenster anzeigen oder einen Klick auf das Tray-Icon. Schließen versteckt das Fenster nur — die App läuft im Tray weiter.

---

Diktat, Verlauf und Vorlesen

Zusätzlich zu den Workflows bietet das Tool drei Komfort-Funktionen:

Menüpunkt	Beschreibung
Diktat-Modus	Umschalter. Ist er aktiv, werden alle Transkripte als Diktat-Einträge gesammelt und einzeln als Markdown-Datei gespeichert. Im Verlauf erscheint dann eine Schaltfläche Zusammenführen, die alle Einträge kombiniert und in die Zwischenablage kopiert.
Verlauf…	Öffnet ein Fenster mit den letzten Transkripten. Pro Eintrag: In Zwischenablage kopieren oder löschen.
Vorlesen…	Lässt dir beliebigen Text vorlesen — lokal per Piper TTS (Standard) oder optional über OpenAI Cloud-TTS (inklusive Anbieter-, Stimmen- und Modellauswahl)!

Note

Diktat-Notizen werden ausschließlich in einen Ordner innerhalb des Home-Verzeichnisses geschrieben (Schutz gegen Pfad-Ausbruch), mit Berechtigungen 0o600.

Important

Piper TTS muss für die Vorlesefunktion (sowie Stimmen) installiert sein:

.venv/bin/pip install piper-tts
# Stimmen (.onnx + .onnx.json) nach ~/.local/share/piper-voices/ legen

Fehlt Piper oder eine Stimme, zeigt das Vorlese-Fenster einen Installationshinweis; alle übrigen Funktionen bleiben nutzbar. Optionale Desktop-Benachrichtigungen nutzen notify-send (Paket libnotify-bin).

Note

OpenAI Cloud-TTS ist eine optionale Alternative zu Piper. Voraussetzung: das openai-Paket (.venv/bin/pip install openai) und ein gültiger Key in der Umgebungsvariable OPENAI_API_KEY (siehe secrets.env unten). Beim ersten Umschalten auf den Anbieter „OpenAI Cloud" fragt das Vorlese-Fenster einmalig nach Bestätigung, da der eingegebene Text zur Synthese an die OpenAI-Server gesendet wird. Piper bleibt Standard und arbeitet vollständig lokal.

---

Konfiguration

Alles wird lokal und sicher unter ~/.config/blitztext-linux/config.json gespeichert. Der OpenAI-Schlüssel wird nicht mehr in dieser Datei abgelegt, sondern aus einer Umgebungsvariable gelesen. Die Konfigurationsdatei lässt sich für erweiterte Prompt- und Workflow-Anpassungen direkt aus den Einstellungen öffnen: Einstellungen → Allgemein → „Konfigurationsdatei öffnen".

Important

Die Konfigurationsdatei wird automatisch mit restriktiven Dateiberechtigungen (0o600 / chmod 600) gespeichert. Der echte OpenAI-Key liegt stattdessen in ~/.config/blitztext-linux/secrets.env oder wird als Umgebungsvariable bereitgestellt.

Beispiel-Konfiguration & Felderklärung

{
  "model": "base",
  "language": "de",
  "backend": "openai-whisper",
  "hotkey_mode": "toggle",
  "openai_api_key_env": "OPENAI_API_KEY",
  "autopaste": true,
  "audio_device": "@DEFAULT_SOURCE@",
  "workflows": {
    "text_improver_tone": "neutral",
    "emoji_density": "mittel",
    "dampf_system_prompt": ""
  }
}

• model: Whisper-Modellgröße (tiny, base, small, medium, large, large-v2, large-v3, large-v3-turbo). Standard: base.
• language: Sprache (de, en) oder auto.
• backend: openai-whisper oder faster-whisper.
• hotkey_mode:
  • toggle: Einmal drücken startet, erneutes Drücken beendet.
  • hold: Aufnahme läuft solange der Hotkey gedrückt wird.
• openai_api_key_env: Name der Umgebungsvariable für den OpenAI API-Key. Standard: OPENAI_API_KEY.
• Der eigentliche Key liegt nicht in config.json, sondern in ~/.config/blitztext-linux/secrets.env oder einer bereits gesetzten Umgebungsvariable.
• autopaste: Fügt per ydotool ein.
• audio_device: Name der Audioquelle.
• tts_provider: TTS-Anbieter für „Vorlesen" — piper (lokal, Standard) oder openai (Cloud).
• tts_openai_model / tts_openai_voice: Modell und Stimme für OpenAI Cloud-TTS (Standard: gpt-4o-mini-tts, marin).
• tts_openai_consent: true, sobald die einmalige Datenschutz-Bestätigung für Cloud-TTS erteilt wurde. Standard: false.
• workflows: Feintuning von Tonalität (text_improver_tone), Schreibstil-Vorlage (writing_preset), Emojis (emoji_density) und dem Dampf-Prompt (dampf_system_prompt).

---

Entwicklung und Tests

Wir lieben Stabilität! Führe die Tests lokal aus:

pytest

Die Suite umfasst aktuell 130 Tests (9 werden ohne optionale Abhängigkeiten wie Piper TTS übersprungen). Mit WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest laufen zusätzlich die GUI-Tests des Hauptfensters.

Verzeichnisüberblick

.
├── app/
│   ├── __init__.py
│   ├── audio_recorder.py   # PulseAudio/PipeWire-Aufnahme via parec
│   ├── blitztext_linux.py  # PyQt6-Hauptanwendung (System-Tray)
│   ├── config.py           # Konfigurations-Manager
│   ├── hotkey_service.py   # evdev-basierter Hotkey-Daemon
│   ├── llm_service.py      # OpenAI API Schnittstelle
│   ├── paste_service.py    # Wayland-Clipboard-Integration
│   ├── transcribe.py       # Whisper-Transkription
│   └── workflows.py        # Workflows Definition
├── tests/                  # Test-Suite
└── README.md               # Dieses Dokument

---

Wichtige Hinweise

• Linux Exclusive: Nur für Linux-Systeme.
• Wayland Fokus: Entwickelt für Wayland (wl-clipboard, ydotool).
• Datenschutz: Lokale Workflows bleiben zu 100% auf deinem Rechner. OpenAI wird nur bei Bedarf für LLM-Aufgaben kontaktiert.
• Sicherheit (evdev & input Gruppe): Das Tool liest Input global über /dev/input/event*. Auf System-Ebene bedeutet dies, dass alle Prozesse des Benutzers Eingaben mitlesen könnten (Trade-off unter Wayland ohne XDG GlobalShortcuts). Nutzen Sie Blitztext nur in Umgebungen, denen Sie vertrauen!
• Entwickler-Hinweis: Dieses Projekt wurde mit Unterstützung künstlicher Intelligenz (AI-assisted) entworfen. Architektur, Code und Tests wurden manuell gesichtet und auf Funktion/Sicherheit lokal verifiziert.

---

Legal / Impressum & Datenschutz (Original-Projekt)

Dieses Projekt ist ein Linux-Port der macOS-Anwendung "Blitztext". Der Fairness halber und zur korrekten Attribution verweisen wir auf die rechtlichen Angaben des Original-Projekts:

Das Original-Projekt ist ein experimentelles, nicht-kommerzielles Open-Source-Projekt unter der MIT-Lizenz. Die zugehörige Website (blitztext.de) wird betrieben von der Blackboat Internet GmbH:

• Impressum: https://www.blackboat.com/impressum
• Datenschutz / Privacy: https://www.blackboat.com/datenschutz

---

_{Erstellt mit ❤️ (und ein bisschen KI-Hilfe).}