From 506f0fbaed38f5925db297ebe134d8c52f71be21 Mon Sep 17 00:00:00 2001 From: gummiflip Date: Mon, 6 Jul 2026 23:55:55 +0200 Subject: [PATCH 1/3] docs: refresh README and Flatpak build notes --- README.de.md | 326 +++++++++++++++++++---------------- README.md | 330 ++++++++++++++++++++---------------- packaging/flatpak/README.md | 52 +++++- 3 files changed, 405 insertions(+), 303 deletions(-) diff --git a/README.de.md b/README.de.md index ede5747..8747aec 100644 --- a/README.de.md +++ b/README.de.md @@ -18,6 +18,12 @@ --- +## Zweck + +Blitztext Linux ist ein Hotkey-gesteuerter Sprachassistent, der gesprochene Sprache in Text umwandelt und direkt in die gerade aktive Anwendung einfügt. Die Transkription läuft standardmäßig lokal über Whisper; ein LLM-Schritt ist optional und wird nur genutzt, wenn du bewusst einen der KI-Workflows (Umformulierung, Ton-Filter, Emoji-Anreicherung) oder das Compose-Fenster auswählst. Alles bleibt auf deinem Rechner, solange du nicht bewusst einen Cloud-Anbieter (OpenAI, OpenRouter oder einen eigenen OpenAI-kompatiblen Endpunkt) für LLM- oder Cloud-TTS-Funktionen aktivierst. + +--- + ## Features - **Mehrsprachige Oberfläche (EN/DE):** Schalte die App-Oberfläche zwischen Deutsch und Englisch um – unter **Einstellungen → Allgemein → „Sprache der Oberfläche"** (die Änderung greift nach einem Neustart der App). @@ -30,115 +36,7 @@ - **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: - -```bash -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. Fragt den Betriebsmodus ab: globale Hotkeys mit `input`-Gruppe oder nur Fenster/Tray ohne globale Hotkeys. -4. Richtet eine `.venv` Umgebung ein und installiert `openai-whisper`/`faster-whisper`. -5. Bereitet `ydotool.service` und den systemd-User-Service vor. - -### Nach der Installation - -1. **Neustart nur erforderlich, wenn du den Hotkey-Modus gewählt hast** (oder ab-/anmelden), damit die Gruppe `input` aktiv wird. Danach checken: - ```bash - bash scripts/verify.sh - ``` -2. **Manuell testen:** - ```bash - ./run.sh - ``` - *(Erscheint das Tray-Symbol und reagieren die Hotkeys? Dann lief alles glatt!)* -3. **Autostart aktivieren:** - ```bash - systemctl --user start blitztext-linux - ``` - -
-Autostart wieder deaktivieren - -```bash -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)** -```bash -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** -```bash -sudo usermod -aG input $USER -``` - -**3. Virtuelle Umgebung & Python-Pakete** -Innerhalb der venv zuerst das CPU-only-PyTorch-Wheel installieren, damit nicht versehentlich große CUDA-Wheels heruntergeladen werden: -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install --index-url https://download.pytorch.org/whl/cpu torch -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): -```bash -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** -```bash -systemctl --user start ydotool.service -``` -Liefert `apt` nur ydotool 0.1.x (Ubuntu 24.04/22.04), ydotool ≥ 1.0 aus dem Quellcode bauen: -```bash -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** -```bash -./run.sh -``` -
- ---- - -## Die 5 Workflows und Hotkeys +### Die 5 Workflows und Hotkeys Blitztext registriert globale Hotkeys via `evdev`. Mit diesen Kombinationen hast du die volle Kontrolle: @@ -151,9 +49,9 @@ Blitztext registriert globale Hotkeys via `evdev`. Mit diesen Kombinationen hast | **Blitztext :)** | Meta + Shift + E | ✅ | Ergänzt deine Nachricht passend mit Emojis. | > [!NOTE] -> **LLM-Workflows** (`Blitztext+`, `Blitztext $%&!`, `Blitztext :)`) setzen einen gültigen **API-Key** voraus. Lege ihn am einfachsten in `~/.config/blitztext-linux/secrets.env` ab, indem du dort die Variable mit deinem Key als Wert setzt (Zeilenformat `NAME=WERT`, z. B. `OPENAI_API_KEY` mit deinem Key als 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. +> **LLM-Workflows** (`Blitztext+`, `Blitztext $%&!`, `Blitztext :)`) setzen einen gültigen **API-Key** voraus. Siehe [Secrets](#secrets) weiter unten für die Konfiguration. Ohne diesen Key sind diese Funktionen im Menü und über die Hotkeys deaktiviert bzw. führen zu einer Fehlermeldung. -## KI-Workflows +### KI-Workflows Die KI-Workflows helfen bei Formulierung, Ton und Emojis. Die passenden Einstellungen findest du unter **Einstellungen → KI-Workflows**: @@ -162,9 +60,7 @@ Die KI-Workflows helfen bei Formulierung, Ton und Emojis. Die passenden Einstell

-### LLM-Anbieter - -Blitztext unterstützt drei Anbieter-Modi, wählbar unter **Einstellungen → KI-Workflows → „LLM-Anbieter"**: +**LLM-Anbieter.** Blitztext unterstützt drei Anbieter-Modi, wählbar unter **Einstellungen → KI-Workflows → „LLM-Anbieter"**: | Anbieter | Wann verwenden | | :--- | :--- | @@ -174,9 +70,7 @@ Blitztext unterstützt drei Anbieter-Modi, wählbar unter **Einstellungen → KI Für OpenRouter `base_url` auf `https://openrouter.ai/api/v1` setzen und Modell wählen (z. B. `openai/gpt-4o`). Der Name der API-Key-Umgebungsvariable wird unter „API-Key-Umgebung" eingestellt. -### Schreibstil-Vorlagen - -Für den Workflow **Blitztext+** (Text-Verbesserer) gibt es vorgefertigte Schreibstil-Vorlagen, die du unter **Einstellungen → KI-Workflows → „Schreibstil-Vorlage"** oder direkt im **Compose-Fenster** auswählst: +**Schreibstil-Vorlagen.** Für den Workflow **Blitztext+** (Text-Verbesserer) gibt es vorgefertigte Schreibstil-Vorlagen, die du unter **Einstellungen → KI-Workflows → „Schreibstil-Vorlage"** oder direkt im **Compose-Fenster** auswählst: | Vorlage | Wirkung | | --- | --- | @@ -192,9 +86,7 @@ Für den Workflow **Blitztext+** (Text-Verbesserer) gibt es vorgefertigte Schrei > Bei **Standard** wird zusätzlich der eingestellte **Tonfall** angewendet. Jede andere Vorlage bringt ihren eigenen Schreibstil mit und überschreibt den Tonfall. Eigennamen/Begriffe bleiben in allen Vorlagen erhalten. ---- - -## Compose-Fenster +### Compose-Fenster Das **Compose-Fenster** (`✍ Compose…` im Tray-Kontextmenü) ermöglicht das Umschreiben beliebiger Texte mit der KI — ganz ohne Sprachaufnahme. Es eignet sich ideal zum Überarbeiten fertiger Entwürfe, E-Mails oder Notizen. @@ -223,9 +115,7 @@ Das **Compose-Fenster** (`✍ Compose…` im Tray-Kontextmenü) ermöglicht das > [!NOTE] > Signatur und eigener Preset-Text werden unter **Einstellungen → Allgemein** konfiguriert. Setze dort „Signatur für das Compose-Fenster" und aktiviere „Nach jeder Generierung automatisch anhängen", wenn die Signatur bei jedem Ergebnis ergänzt werden soll. ---- - -## Tray-Symbol: Statusfarben +### Tray-Symbol: Statusfarben Das Mikrofon im System-Tray ist dein Indikator für den aktuellen Zustand: @@ -267,9 +157,7 @@ Das Tray-Kontextmenü gibt dir schnellen Zugriff auf alle Workflows, das Compose > [!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 +### Hauptfenster Das Hauptfenster ist dein grafisches Kontrollzentrum — nützlich, wenn Hotkeys blockiert sind oder du lieber mit der Maus arbeitest: @@ -288,9 +176,7 @@ Das Hauptfenster ist dein grafisches Kontrollzentrum — nützlich, wenn Hotkeys *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 +### Diktat, Verlauf und Vorlesen Zusätzlich zu den Workflows bietet das Tool drei Komfort-Funktionen: @@ -319,13 +205,119 @@ Zusätzlich zu den Workflows bietet das Tool drei Komfort-Funktionen: > 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. +> **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](#secrets) 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. + +--- + +## Installation & Start + +### Schnellinstallation (empfohlen) + +Der einfachste Weg, um Blitztext auf deinem System bereitzustellen: + +```bash +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. Fragt den Betriebsmodus ab: globale Hotkeys mit `input`-Gruppe oder nur Fenster/Tray ohne globale Hotkeys. +4. Richtet eine `.venv` Umgebung ein und installiert `openai-whisper`/`faster-whisper`. +5. Bereitet `ydotool.service` und den systemd-User-Service vor. + +### Nach der Installation + +1. **Neustart nur erforderlich, wenn du den Hotkey-Modus gewählt hast** (oder ab-/anmelden), damit die Gruppe `input` aktiv wird. Danach checken: + ```bash + bash scripts/verify.sh + ``` +2. **Manuell testen:** + ```bash + ./run.sh + ``` + *(Erscheint das Tray-Symbol und reagieren die Hotkeys? Dann lief alles glatt!)* +3. **Autostart aktivieren:** + ```bash + systemctl --user start blitztext-linux + ``` + +
+Autostart wieder deaktivieren + +```bash +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)** +```bash +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** +```bash +sudo usermod -aG input $USER +``` + +**3. Virtuelle Umgebung & Python-Pakete** +Innerhalb der venv zuerst das CPU-only-PyTorch-Wheel installieren, damit nicht versehentlich große CUDA-Wheels heruntergeladen werden: +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install --index-url https://download.pytorch.org/whl/cpu torch +pip install PyQt6 evdev openai pytest openai-whisper faster-whisper +``` + +**4. Whisper-Engine als Alternative via pipx** +Falls du `openai-whisper` losgelöst von der venv installieren möchtest (umgeht Versionskonflikte auf neueren Ubuntu-Setups durch Python 3.11): +```bash +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** +```bash +systemctl --user start ydotool.service +``` +Liefert `apt` nur ydotool 0.1.x (Ubuntu 24.04/22.04), ydotool ≥ 1.0 aus dem Quellcode bauen: +```bash +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** +```bash +./run.sh +``` +
--- ## 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"**. +Alles wird lokal unter `~/.config/blitztext-linux/config.json` gespeichert. Diese Datei enthält keine Secrets — der OpenAI-/OpenRouter-Key wird aus einer Umgebungsvariable gelesen (siehe [Secrets](#secrets)). Die Konfigurationsdatei lässt sich direkt aus den Einstellungen öffnen: **Einstellungen → Allgemein → „Konfigurationsdatei öffnen"**. Der Einstellungs-Dialog hat drei Tabs: @@ -339,7 +331,7 @@ Der Einstellungs-Dialog hat drei Tabs: > [!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. +> Die Konfigurationsdatei wird automatisch mit restriktiven Dateiberechtigungen (**`0o600` / `chmod 600`**) gespeichert.
Beispiel-Konfiguration & Felderklärung @@ -382,7 +374,7 @@ Der Einstellungs-Dialog hat drei Tabs: - **language**: Transkriptions-Sprache (`de`, `en`) oder `auto`. - **ui_language**: Sprache der App-Oberfläche (`de` oder `en`). Standard: `de`. Änderungen greifen nach einem Neustart. - **backend**: `openai-whisper` oder `faster-whisper`. -- **hotkey_mode**: +- **hotkey_mode**: - `toggle`: Einmal drücken startet, erneutes Drücken beendet. - `hold`: Aufnahme läuft solange der Hotkey gedrückt wird. - **transcription_hotkey**: Aufnahmetaste, die vom globalen Hotkey-Daemon überwacht wird. Standard: `KEY_LEFTALT`. @@ -408,9 +400,29 @@ Der Einstellungs-Dialog hat drei Tabs: --- -## Entwicklung und Tests +## Secrets + +API-Keys werden niemals in `config.json` gespeichert — sie werden zur Laufzeit aus Umgebungsvariablen gelesen. + +**Empfohlen: `secrets.env`.** Lege deine(n) Key(s) in `~/.config/blitztext-linux/secrets.env` ab, ein `NAME=WERT`-Paar pro Zeile, zum Beispiel: + +```bash +OPENAI_API_KEY=sk-... +# OPENROUTER_API_KEY=sk-or-... +``` + +`./run.sh` und der systemd-User-Service laden diese Datei automatisch. `config.json` speichert nur den *Namen* der zu lesenden Umgebungsvariable (`openai_api_key_env`), niemals den Key selbst. + +- Welche Variable verwendet wird, hängt von **Einstellungen → KI-Workflows → „API-Key-Umgebung"** und dem gewählten LLM-Anbieter ab (`OPENAI_API_KEY` für OpenAI, `OPENROUTER_API_KEY` für OpenRouter, oder ein eigener Name für einen eigenen Endpunkt). +- Ohne gültigen Key sind die LLM-Workflows (`Blitztext+`, `Blitztext $%&!`, `Blitztext :)`) und OpenAI Cloud-TTS deaktiviert bzw. schlagen mit einer Fehlermeldung fehl; lokale Transkription und Piper-TTS funktionieren weiterhin. +- Committe niemals `secrets.env`, API-Keys oder Tokens in git. Sollte ein Key jemals offengelegt werden (z. B. versehentlich committet oder in ein Issue eingefügt), rotiere ihn sofort beim Anbieter. +- `config.json` wird mit restriktiven Rechten (`0o600`) geschrieben; die gleiche Erwartung gilt für `secrets.env`. + +--- + +## Tests -Wir lieben Stabilität! Führe die Tests lokal aus: +Führe die Test-Suite lokal aus: ```bash pytest @@ -418,6 +430,37 @@ pytest Mit `WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest` laufen zusätzlich die GUI-Tests (Hauptfenster, Compose-Fenster). +`bash scripts/verify.sh` führt sitzungsabhängige Diagnosen für X11-, Wayland- und Clipboard-Backends aus — hilfreich nach der Installation oder bei der Fehlersuche zu Hotkeys/Paste-Verhalten. Die Ausgabe ist Diagnosehilfe, kein Supportversprechen; siehe die dort ausgegebenen Kompatibilitätshinweise für deine Desktop-Sitzung. + +--- + +## Flatpak-MVP-Status + +`packaging/flatpak/` enthält einen **experimentellen** Flatpak-Manifest-Spike — kein Release-Kanal und nicht auf Flathub veröffentlicht. + +- Eine strukturelle Validierung (`flatpak-builder --show-manifest` / `--show-deps`) sowie ein vollständiger lokaler Build (inklusive Download von `org.kde.Platform`/`org.kde.Sdk` 6.8) waren auf einer Entwicklungsmaschine beide erfolgreich. +- Die KDE-6.8-Runtime ist upstream als EOL markiert; sie baut und läuft für diesen MVP dennoch. Ein Runtime-Bump auf 6.10 ist ein möglicher Folge-Spike, hier aber nicht umgesetzt. +- Innerhalb der Flatpak-Sandbox sind mehrere Funktionen bewusst deaktiviert oder eingeschränkt: keine globalen Hotkeys (kein evdev-/Input-Geräte-Zugriff), kein `ydotool`-Auto-Paste (Zwischenablage-Kopie funktioniert weiterhin über den Qt-Fallback), keine lokale Whisper-Transkription (aus `requirements-flatpak.txt` wegen der Größe ausgeklammert — Cloud-Transkription/LLM-Workflows funktionieren weiterhin mit `--share=network`) und keine Desktop-Benachrichtigungen (`notify-send` ist nicht gebündelt). +- Es gibt kein Signing, keine AppStream-Metadaten, kein `.desktop`-File und kein paketiertes Release für diesen Spike. + +Details zu Manifest-Umfang, Build-Befehlen und bekannten Abweichungen von Flathub-Konventionen siehe [`packaging/flatpak/README.md`](packaging/flatpak/README.md). + +--- + +## Bekannte Grenzen + +- **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 oder OpenRouter wird nur bei Bedarf für LLM- oder Cloud-TTS-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). Nutze Blitztext nur in Umgebungen, denen du vertraust! +- **Flatpak-Sandbox:** Siehe [Flatpak-MVP-Status](#flatpak-mvp-status) oben — globale Hotkeys, Auto-Paste, lokales Whisper und Desktop-Benachrichtigungen sind innerhalb der Sandbox nicht verfügbar. + +--- + +## Entwicklung + +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. Siehe [CONTRIBUTING.md](CONTRIBUTING.md) für Hinweise, wie du Änderungen vorschlagen kannst. +
Verzeichnisüberblick @@ -439,6 +482,7 @@ Mit `WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest` laufen zusätzlich di │ ├── tts_window.py # Vorlese-Fenster mit Audio-Export │ ├── workflows.py # Workflow-Definitionen │ └── writing_presets.py # Schreibstil-Vorlagen-Definitionen +├── packaging/flatpak/ # Experimenteller Flatpak-MVP-Spike (siehe oben) ├── tests/ # Test-Suite └── README.md # Englische Fassung (diese Datei: README.de.md) ``` @@ -446,16 +490,6 @@ Mit `WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest` laufen zusätzlich di --- -## 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 oder OpenRouter wird nur bei Bedarf für LLM- oder Cloud-TTS-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: @@ -471,7 +505,7 @@ Das Original-Projekt ist ein experimentelles, nicht-kommerzielles Open-Source-Pr Erstellt mit ❤️ (und ein bisschen KI-Hilfe). -### v0.8.1: Absichtstreue Prompts und bessere Diagnose +### Neueste Release-Notizen (v0.8.1): Absichtstreue Prompts und bessere Diagnose Blitztext+ und die Schreibstil-Presets bewahren die Absicht der Eingabe jetzt konservativer. Sie sollen bei diktierten Arbeitsanweisungen oder Übergabe-Prompts keine Meetings, Teilnehmer, Empfänger, Rollen oder Ziele erfinden. E-Mail-Presets nutzen eine E-Mail-artige Struktur nur dann, wenn die Eingabe erkennbar als Nachricht an jemanden gemeint ist. diff --git a/README.md b/README.md index 99aa3f8..5e1b01e 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,12 @@ --- +## Purpose + +Blitztext Linux is a hotkey-driven voice assistant that turns speech into text and pastes it directly into whatever application has focus. Transcription runs locally via Whisper by default; an LLM step is optional and only used when you explicitly pick one of the AI workflows (rephrase, tone filter, emoji enrichment) or the Compose window. Everything is designed to stay on your machine unless you deliberately opt into a cloud provider (OpenAI, OpenRouter, or a custom OpenAI-compatible endpoint) for LLM or Cloud TTS features. + +--- + ## Features - **Multilingual interface (EN/DE):** Switch the app interface between German and English under **Settings → General → "Interface language"** (takes effect after restarting the app). @@ -30,115 +36,7 @@ - **LLM-powered workflows:** Let the AI rephrase your sentences professionally, filter them emotionally, or enrich them with fitting emojis. - **Local processing:** Optionally 100% offline for full privacy. ---- - -## Installation - -### Quick install (recommended) - -The easiest way to set up Blitztext on your system: - -```bash -git clone https://github.com/TimInTech/blitztext-linux.git -cd blitztext-linux -bash scripts/install.sh -``` - -**What does the script do?** -It is idempotent (safe to run repeatedly) and handles everything fully automatically: -1. Checks your system (Ubuntu/Debian) & Python version. -2. Installs missing system packages (incl. `pipx`). -3. Prompts for the operating mode: global hotkeys with `input` group, or window/tray only without global hotkeys. -4. Sets up a `.venv` environment and installs `openai-whisper`/`faster-whisper`. -5. Prepares `ydotool.service` and the systemd user service. - -### After installation - -1. **Restart required only if you chose hotkey mode** (or log out/in) so the `input` group becomes active. Then verify: - ```bash - bash scripts/verify.sh - ``` -2. **Test manually:** - ```bash - ./run.sh - ``` - *(Does the tray icon appear and do the hotkeys respond? Then everything went smoothly!)* -3. **Enable autostart:** - ```bash - systemctl --user start blitztext-linux - ``` - -
-Disable autostart again - -```bash -systemctl --user stop blitztext-linux -systemctl --user disable blitztext-linux -``` -
- -
-Manual installation (diagnostics / experts) - -In case you want to debug specifically instead of using `scripts/install.sh`: - -**1. System packages (apt)** -```bash -sudo apt install pulseaudio-utils wl-clipboard xclip ydotool ffmpeg python3-venv python3-evdev build-essential python3-dev socat pipx -``` - -| Package | Purpose | -| :--- | :--- | -| `pulseaudio-utils` | `parec` for audio recording via PulseAudio/PipeWire | -| `wl-clipboard` / `xclip` | Clipboard under Wayland (`wl-copy`) or X11 fallback | -| `ydotool` (≥ 1.0) | Simulates `Ctrl+V` for automatic pasting (auto-paste). From version 1.0 onward, raw keycodes are used. **Ubuntu 25.10/26.04** ship ydotool ≥ 1.0 (1.0.4) directly via `apt`. **Ubuntu 24.04 and 22.04** only ship 0.1.x via `apt` (e.g. 0.1.8), which does not support keycodes and therefore has no auto-paste – build ydotool ≥ 1.0 from source there (see below). Auto-paste verified on 24.04, 25.10, and 26.04. | -| `ffmpeg` | Audio conversions | -| `python3-evdev` | Input device access for the system-wide hotkey daemon | -| `socat` | Optional socket communication | -| `pipx` | Isolated installation of Whisper engines | - -**2. Grant evdev permissions** -```bash -sudo usermod -aG input $USER -``` - -**3. Virtual environment & Python packages** -Install the CPU-only PyTorch wheel first inside the venv to avoid accidentally downloading large CUDA wheels: -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install --index-url https://download.pytorch.org/whl/cpu torch -pip install PyQt6 evdev openai pytest openai-whisper faster-whisper -``` - -**4. Whisper engine as an alternative via pipx** -If you want to install `openai-whisper` decoupled from the venv (avoids version conflicts on newer Ubuntu setups due to Python 3.11): -```bash -pipx install --python "$(command -v python3.11)" openai-whisper -pipx inject openai-whisper faster-whisper # optional, for accelerated execution -``` - -**5. Check ydotool** -```bash -systemctl --user start ydotool.service -``` -If `apt` only provides ydotool 0.1.x (Ubuntu 24.04/22.04), build ydotool ≥ 1.0 from source: -```bash -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 # uses /usr/local/bin/ydotoold -``` - -**6. Start the application** -```bash -./run.sh -``` -
- ---- - -## The 5 workflows and hotkeys +### The 5 workflows and hotkeys Blitztext registers global hotkeys via `evdev`. With these combinations you have full control: @@ -151,11 +49,9 @@ Blitztext registers global hotkeys via `evdev`. With these combinations you have | **Blitztext :)** | Meta + Shift + E | ✅ | Enriches your message with fitting emojis. | > [!NOTE] -> **LLM workflows** (`Blitztext+`, `Blitztext $%&!`, `Blitztext :)`) require a valid **API key**. The easiest way is to place it in `~/.config/blitztext-linux/secrets.env` using the format `NAME=VALUE` (e.g. `OPENAI_API_KEY` set to your key). `./run.sh` and the systemd service load this file automatically. Without a key, these functions are disabled in the menu and via hotkeys, or result in an error message. - ---- +> **LLM workflows** (`Blitztext+`, `Blitztext $%&!`, `Blitztext :)`) require a valid **API key**. See [Secrets](#secrets) below for how to configure it. Without a key, these functions are disabled in the menu and via hotkeys, or result in an error message. -## AI workflows +### AI workflows The AI workflows help with phrasing, tone, and emojis. You'll find the relevant settings under **Settings → AI Workflows**: @@ -164,9 +60,7 @@ The AI workflows help with phrasing, tone, and emojis. You'll find the relevant

-### LLM providers - -Blitztext supports three provider modes, selectable under **Settings → AI Workflows → "LLM provider"**: +**LLM providers.** Blitztext supports three provider modes, selectable under **Settings → AI Workflows → "LLM provider"**: | Provider | When to use | | :--- | :--- | @@ -176,9 +70,7 @@ Blitztext supports three provider modes, selectable under **Settings → AI Work For OpenRouter, set `base_url` to `https://openrouter.ai/api/v1` and choose your model (e.g. `openai/gpt-4o`). The API key environment variable name is configured under "API key environment". -### Writing-style presets - -For the **Blitztext+** workflow (text improver) there are ready-made writing-style presets that you select under **Settings → AI Workflows → "Writing-style preset"** or directly in the **Compose window**: +**Writing-style presets.** For the **Blitztext+** workflow (text improver) there are ready-made writing-style presets that you select under **Settings → AI Workflows → "Writing-style preset"** or directly in the **Compose window**: | Preset | Effect | | --- | --- | @@ -194,9 +86,7 @@ For the **Blitztext+** workflow (text improver) there are ready-made writing-sty > With **Standard**, the configured **tone** (casual / neutral / professional) is additionally applied. Every other preset brings its own writing style and overrides the tone setting. Custom names/terms are preserved in all presets. ---- - -## Compose window +### Compose window The **Compose window** (`✍ Compose…` in the tray menu) lets you rewrite any text using the AI — without recording your voice. It is ideal for editing existing drafts, emails, or notes. @@ -225,9 +115,7 @@ The **Compose window** (`✍ Compose…` in the tray menu) lets you rewrite any > [!NOTE] > The signature and custom preset text are configured under **Settings → General**. Set "Signature for Compose window" and toggle "Automatically append after generation" if you want the signature added to every result. ---- - -## Tray icon and context menu +### Tray icon and context menu The microphone in the system tray is your indicator of the current state: @@ -269,9 +157,7 @@ The tray context menu gives you quick access to all workflows, the compose windo > [!NOTE] > If no tray area is available in the desktop environment, the icon falls back to the system theme `audio-input-microphone`; the color coding may then not apply. ---- - -## Main window +### Main window The main window is your graphical control center — useful when hotkeys are blocked or you prefer mouse control: @@ -290,9 +176,7 @@ The main window is your graphical control center — useful when hotkeys are blo *The window opens at startup and via the tray entry **Show window** or a click on the tray icon. Closing only hides the window — the app keeps running in the tray.* ---- - -## Dictation, history, and read-aloud +### Dictation, history, and read-aloud In addition to the workflows, the tool offers three convenience functions: @@ -303,7 +187,6 @@ In addition to the workflows, the tool offers three convenience functions:

- | Menu item | Description | | :--- | :--- | | **Dictation mode** | Toggle. When active, all transcripts are collected as dictation entries and each saved as a Markdown file. The history then shows a **Merge** button that combines all entries and copies them to the clipboard. | @@ -322,13 +205,119 @@ In addition to the workflows, the tool offers three convenience functions: > If Piper or a voice is missing, the read-aloud window shows an installation hint; all other functions remain usable. Optional desktop notifications use `notify-send` (package `libnotify-bin`). > [!NOTE] -> **OpenAI Cloud TTS** is an optional alternative to Piper. Requirements: the `openai` package (`.venv/bin/pip install openai`) and a valid key in the environment variable `OPENAI_API_KEY` (see `secrets.env` below). When first switching to the "OpenAI Cloud" provider, the read-aloud window asks for confirmation once, because the entered text is sent to OpenAI's servers for synthesis. Piper remains the default and works entirely locally. +> **OpenAI Cloud TTS** is an optional alternative to Piper. Requirements: the `openai` package (`.venv/bin/pip install openai`) and a valid key in the environment variable `OPENAI_API_KEY` (see [Secrets](#secrets) below). When first switching to the "OpenAI Cloud" provider, the read-aloud window asks for confirmation once, because the entered text is sent to OpenAI's servers for synthesis. Piper remains the default and works entirely locally. + +--- + +## Installation & Start + +### Quick install (recommended) + +The easiest way to set up Blitztext on your system: + +```bash +git clone https://github.com/TimInTech/blitztext-linux.git +cd blitztext-linux +bash scripts/install.sh +``` + +**What does the script do?** +It is idempotent (safe to run repeatedly) and handles everything fully automatically: +1. Checks your system (Ubuntu/Debian) & Python version. +2. Installs missing system packages (incl. `pipx`). +3. Prompts for the operating mode: global hotkeys with `input` group, or window/tray only without global hotkeys. +4. Sets up a `.venv` environment and installs `openai-whisper`/`faster-whisper`. +5. Prepares `ydotool.service` and the systemd user service. + +### After installation + +1. **Restart required only if you chose hotkey mode** (or log out/in) so the `input` group becomes active. Then verify: + ```bash + bash scripts/verify.sh + ``` +2. **Test manually:** + ```bash + ./run.sh + ``` + *(Does the tray icon appear and do the hotkeys respond? Then everything went smoothly!)* +3. **Enable autostart:** + ```bash + systemctl --user start blitztext-linux + ``` + +
+Disable autostart again + +```bash +systemctl --user stop blitztext-linux +systemctl --user disable blitztext-linux +``` +
+ +
+Manual installation (diagnostics / experts) + +In case you want to debug specifically instead of using `scripts/install.sh`: + +**1. System packages (apt)** +```bash +sudo apt install pulseaudio-utils wl-clipboard xclip ydotool ffmpeg python3-venv python3-evdev build-essential python3-dev socat pipx +``` + +| Package | Purpose | +| :--- | :--- | +| `pulseaudio-utils` | `parec` for audio recording via PulseAudio/PipeWire | +| `wl-clipboard` / `xclip` | Clipboard under Wayland (`wl-copy`) or X11 fallback | +| `ydotool` (≥ 1.0) | Simulates `Ctrl+V` for automatic pasting (auto-paste). From version 1.0 onward, raw keycodes are used. **Ubuntu 25.10/26.04** ship ydotool ≥ 1.0 (1.0.4) directly via `apt`. **Ubuntu 24.04 and 22.04** only ship 0.1.x via `apt` (e.g. 0.1.8), which does not support keycodes and therefore has no auto-paste – build ydotool ≥ 1.0 from source there (see below). Auto-paste verified on 24.04, 25.10, and 26.04. | +| `ffmpeg` | Audio conversions | +| `python3-evdev` | Input device access for the system-wide hotkey daemon | +| `socat` | Optional socket communication | +| `pipx` | Isolated installation of Whisper engines | + +**2. Grant evdev permissions** +```bash +sudo usermod -aG input $USER +``` + +**3. Virtual environment & Python packages** +Install the CPU-only PyTorch wheel first inside the venv to avoid accidentally downloading large CUDA wheels: +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install --index-url https://download.pytorch.org/whl/cpu torch +pip install PyQt6 evdev openai pytest openai-whisper faster-whisper +``` + +**4. Whisper engine as an alternative via pipx** +If you want to install `openai-whisper` decoupled from the venv (avoids version conflicts on newer Ubuntu setups due to Python 3.11): +```bash +pipx install --python "$(command -v python3.11)" openai-whisper +pipx inject openai-whisper faster-whisper # optional, for accelerated execution +``` + +**5. Check ydotool** +```bash +systemctl --user start ydotool.service +``` +If `apt` only provides ydotool 0.1.x (Ubuntu 24.04/22.04), build ydotool ≥ 1.0 from source: +```bash +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 # uses /usr/local/bin/ydotoold +``` + +**6. Start the application** +```bash +./run.sh +``` +
--- ## Configuration -Everything is stored locally and securely under `~/.config/blitztext-linux/config.json`. The OpenAI key is not stored in this file but read from an environment variable. The configuration file can be opened directly from the settings: **Settings → General → "Open configuration file"**. +Everything is stored locally under `~/.config/blitztext-linux/config.json`. This file holds no secrets — the OpenAI/OpenRouter key is read from an environment variable (see [Secrets](#secrets)). The configuration file can be opened directly from the settings: **Settings → General → "Open configuration file"**. The settings dialog has three tabs: @@ -341,9 +330,8 @@ The settings dialog has three tabs:
General — Auto-Paste, dictation folder, history size, interface language, and signature.

- > [!IMPORTANT] -> The configuration file is automatically saved with restrictive file permissions (**`0o600` / `chmod 600`**). The real OpenAI key instead lives in `~/.config/blitztext-linux/secrets.env` or is provided as an environment variable. +> The configuration file is automatically saved with restrictive file permissions (**`0o600` / `chmod 600`**).
Example configuration & field explanation @@ -386,7 +374,7 @@ The settings dialog has three tabs: - **language**: Transcription language (`de`, `en`) or `auto`. - **ui_language**: Language of the app interface (`de` or `en`). Default: `de`. Changes take effect after a restart. - **backend**: `openai-whisper` or `faster-whisper`. -- **hotkey_mode**: +- **hotkey_mode**: - `toggle`: press once to start, press again to stop. - `hold`: recording runs as long as the hotkey is held. - **transcription_hotkey**: Recording key captured by the global hotkey daemon. Default: `KEY_LEFTALT`. @@ -412,9 +400,29 @@ The settings dialog has three tabs: --- -## Development and tests +## Secrets + +API keys are never stored in `config.json` — they are read from environment variables at runtime. + +**Recommended: `secrets.env`.** Place your key(s) in `~/.config/blitztext-linux/secrets.env`, one `NAME=VALUE` pair per line, for example: + +```bash +OPENAI_API_KEY=sk-... +# OPENROUTER_API_KEY=sk-or-... +``` + +`./run.sh` and the systemd user service load this file automatically. `config.json` only stores the *name* of the environment variable to read (`openai_api_key_env`), never the key itself. + +- Which variable is used depends on **Settings → AI Workflows → "API key environment"** and the selected LLM provider (`OPENAI_API_KEY` for OpenAI, `OPENROUTER_API_KEY` for OpenRouter, or a custom name for a custom endpoint). +- Without a valid key, the LLM workflows (`Blitztext+`, `Blitztext $%&!`, `Blitztext :)`) and OpenAI Cloud TTS are disabled or fail with an error message; local transcription and Piper TTS keep working. +- Never commit `secrets.env`, API keys, or tokens to git. If a key is ever exposed (e.g. committed by accident or pasted into an issue), rotate it immediately with the provider. +- `config.json` is written with restrictive permissions (`0o600`); keep the same expectation for `secrets.env`. + +--- + +## Tests -We love stability! Run the tests locally: +Run the test suite locally: ```bash pytest @@ -422,6 +430,37 @@ pytest With `WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest`, the GUI tests (main window, compose window) run additionally. +`bash scripts/verify.sh` runs session-aware diagnostics for X11, Wayland, and clipboard backends — useful after installation or when troubleshooting hotkeys/paste behavior. Its output is diagnostic guidance, not a support promise; see the compatibility notes it prints for your desktop session. + +--- + +## Flatpak MVP status + +`packaging/flatpak/` contains an **experimental** Flatpak manifest spike — it is not a release channel and not published on Flathub. + +- A structural validation (`flatpak-builder --show-manifest` / `--show-deps`) and a full local build (including the `org.kde.Platform`/`org.kde.Sdk` 6.8 download) have both succeeded on a development machine. +- The KDE 6.8 runtime is marked EOL upstream; it still builds and runs for this MVP. A runtime bump to 6.10 is a possible follow-up spike, not something implemented here. +- Inside the Flatpak sandbox, several features are intentionally disabled or degraded: no global hotkeys (no evdev/input-device access), no `ydotool` auto-paste (clipboard copy still works via the Qt fallback), no local Whisper transcription (excluded from `requirements-flatpak.txt` due to its size — cloud transcription/LLM workflows still work with `--share=network`), and no desktop notifications (`notify-send` is not bundled). +- No signing, no AppStream metadata, no `.desktop` file, and no packaged release exist for this spike. + +See [`packaging/flatpak/README.md`](packaging/flatpak/README.md) for the exact manifest scope, build commands, and known deviations from Flathub conventions. + +--- + +## Known limitations + +- **Linux exclusive:** For Linux systems only. +- **Wayland focus:** Developed for Wayland (`wl-clipboard`, `ydotool`). +- **Privacy:** Local workflows stay 100% on your machine. OpenAI or OpenRouter is only contacted when needed for LLM or Cloud TTS tasks. +- **Security (`evdev` & `input` group):** The tool reads input globally via `/dev/input/event*`. At the system level, this means all of the user's processes could read along with input (a trade-off under Wayland without XDG GlobalShortcuts). Only use Blitztext in environments you trust! +- **Flatpak sandbox:** See [Flatpak MVP status](#flatpak-mvp-status) above — global hotkeys, auto-paste, local Whisper, and desktop notifications are unavailable inside the sandbox. + +--- + +## Development + +This project was designed with the support of artificial intelligence (AI-assisted). Architecture, code, and tests were reviewed manually and verified locally for function/security. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose changes. +
Directory overview @@ -443,6 +482,7 @@ With `WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest`, the GUI tests (main │ ├── tts_window.py # Read Aloud window with audio export │ ├── workflows.py # Workflow definitions │ └── writing_presets.py # Writing-style preset definitions +├── packaging/flatpak/ # Experimental Flatpak MVP spike (see above) ├── tests/ # Test suite └── README.md # This document (German version: README.de.md) ``` @@ -450,16 +490,6 @@ With `WHISPER_GUI_TESTS=1 QT_QPA_PLATFORM=offscreen pytest`, the GUI tests (main --- -## Important notes - -- **Linux exclusive:** For Linux systems only. -- **Wayland focus:** Developed for Wayland (`wl-clipboard`, `ydotool`). -- **Privacy:** Local workflows stay 100% on your machine. OpenAI or OpenRouter is only contacted when needed for LLM or Cloud TTS tasks. -- **Security (`evdev` & `input` group):** The tool reads input globally via `/dev/input/event*`. At the system level, this means all of the user's processes could read along with input (a trade-off under Wayland without XDG GlobalShortcuts). Only use Blitztext in environments you trust! -- **Developer note:** This project was designed with the support of artificial intelligence (AI-assisted). Architecture, code, and tests were reviewed manually and verified locally for function/security. - ---- - ## Legal / Imprint & privacy (original project) This project is a Linux port of the macOS application "Blitztext". For fairness and correct attribution, we refer to the legal information of the original project: @@ -475,7 +505,7 @@ The original project is an experimental, non-commercial open-source project unde Made with ❤️ (and a little AI help). -### v0.8.1: Intent-preserving prompts and diagnostics +### Latest release notes (v0.8.1): Intent-preserving prompts and diagnostics Blitztext+ and the writing presets now preserve the user's intent more conservatively. They avoid inventing meetings, participants, recipients, roles, or goals when rewriting spoken work instructions or handover prompts. Email presets only use email-like structure when the input is clearly meant as a message to someone. diff --git a/packaging/flatpak/README.md b/packaging/flatpak/README.md index f176fe4..901c691 100644 --- a/packaging/flatpak/README.md +++ b/packaging/flatpak/README.md @@ -55,23 +55,61 @@ Absichtlich **nicht** enthalten / sichtbar deaktiviert: ## Verifikation (in diesem Spike durchgefuehrt) -`flatpak-builder` 1.4.8 ist auf diesem Host vorhanden. Ein vollstaendiger -Build (Download von `org.kde.Platform`/`org.kde.Sdk` 6.8, ca. 1,5 GB) wurde -in diesem Diagnose-Pass **nicht** ausgefuehrt -- das waere ein groesserer, -bestaetigungspflichtiger Download/Installationsschritt ausserhalb des -Spike-Rahmens. Stattdessen nur strukturelle Validierung ohne Runtime-Install: +`flatpak-builder` 1.4.8 ist auf diesem Host vorhanden. Zunaechst wurde nur +strukturell validiert, ohne Runtime-Install: ```bash flatpak-builder --show-manifest packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml flatpak-builder --show-deps packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml ``` +Nach PR #48 wurde zusaetzlich ein echter Build (inkl. Download von +`org.kde.Platform`/`org.kde.Sdk` 6.8, ca. 1,5 GB) erfolgreich getestet. + +### Hinweis: Build-State-Dir unter `/tmp` + +Wenn das Build-Verzeichnis unter `/tmp` liegt, kann `flatpak-builder` +je nach Setup versuchen, seinen State-Ordner (`.flatpak-builder/`) relativ +zum Home-Filesystem anzulegen. Da `/tmp` haeufig ein separates `tmpfs` ist, +schlagen manche Operationen (z. B. `rofiles-fuse`/Hardlinks) ueber die +Filesystem-Grenze fehl. Abhilfe: State-Dir explizit auf denselben +Filesystem-Mountpoint wie das Build-Ziel legen, z. B.: + +```bash +--state-dir=/tmp/blitztext-flatpak-builder-state +``` + +### Beispiel-Build-Befehl (ohne `--install`) + +```bash +flatpak install --user -y flathub org.kde.Platform//6.8 org.kde.Sdk//6.8 +flatpak-builder --force-clean \ + --state-dir=/tmp/blitztext-flatpak-builder-state \ + /tmp/blitztext-flatpak-build \ + packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml +``` + +Bewusst ohne `--install` -- der Build wird nur erzeugt, nicht in die lokale +Flatpak-Umgebung installiert. Fuer einen manuellen Testlauf danach: + +```bash +flatpak-builder --run /tmp/blitztext-flatpak-build \ + packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml \ + blitztext-linux.sh +``` + +### KDE Platform/Sdk 6.8 -- EOL-Hinweis + +Laut Flathub ist `org.kde.Platform`/`org.kde.Sdk` 6.8 als EOL markiert. +Fuer diesen MVP ist die Runtime weiterhin funktionsfaehig und wurde +erfolgreich gebaut. Naechster Upgrade-Kandidat: **6.10**. Ein Runtime-Bump +ist nicht Teil dieses Spikes. + ## Naechster Schritt (nicht Teil dieses Spikes) -Falls ein echter Build gewuenscht ist: +Falls ein vollstaendig installierter Testlauf gewuenscht ist: ```bash -flatpak install flathub org.kde.Platform//6.8 org.kde.Sdk//6.8 flatpak-builder --user --install --force-clean build-dir \ packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml flatpak run io.github.TimInTech.BlitztextLinux From 52e45c7c047155b94b55d3ec41e591aacd587bc2 Mon Sep 17 00:00:00 2001 From: gummiflip Date: Sun, 12 Jul 2026 20:13:50 +0200 Subject: [PATCH 2/3] fix(flatpak): grant D-Bus talk-name for tray icon registration Real flatpak-builder --install test run showed the app starting and staying alive but never becoming reachable: no tray icon, no window. Blitztext starts exclusively as a tray icon (blitztext_linux.py setup_tray), and without --talk-name=org.kde.StatusNotifierWatcher the sandboxed Qt/KDE tray backend can't register the StatusNotifierItem (D-Bus ServiceUnknown), leaving no way to open the GUI at all. Verified via busctl that the tray item registers correctly after the fix. Documented root cause and verification in the Flatpak README. --- packaging/flatpak/README.md | 24 +++++++++++++++++++ .../io.github.TimInTech.BlitztextLinux.yaml | 1 + 2 files changed, 25 insertions(+) diff --git a/packaging/flatpak/README.md b/packaging/flatpak/README.md index 901c691..e5a3b75 100644 --- a/packaging/flatpak/README.md +++ b/packaging/flatpak/README.md @@ -12,6 +12,11 @@ Absichtlich enthalten: - Audioaufnahme ueber PulseAudio-Socket - Cloud-Aufrufe (OpenAI: LLM-Workflows, ggf. Transkription/TTS) ueber `--share=network` +- D-Bus-Zugriff auf `org.kde.StatusNotifierWatcher` + (`--talk-name=org.kde.StatusNotifierWatcher`) fuer das Tray-Icon -- + siehe "Tray-Icon erfordert D-Bus-Talk-Name" unten, App startet + ausschliesslich als Tray-Icon (`app/blitztext_linux.py::setup_tray`), + ohne diese Berechtigung ist die GUI im Sandbox unerreichbar. Absichtlich **nicht** enthalten / sichtbar deaktiviert: - Globale Hotkeys (evdev) -- `app/hotkey_service.py` importiert `evdev` lazy @@ -98,6 +103,25 @@ flatpak-builder --run /tmp/blitztext-flatpak-build \ blitztext-linux.sh ``` +### Tray-Icon erfordert D-Bus-Talk-Name + +Beim ersten echten `flatpak run`-Testlauf (nach PR #48) blieb die App +unerreichbar: kein Absturz, Prozess lief stabil (`flatpak ps` zeigte ihn), +aber es erschien weder Tray-Icon noch Fenster. Ursache: Blitztext startet +ausschliesslich als Tray-Icon (`app/blitztext_linux.py::setup_tray`, Zeile +~645/673-781), das Hauptfenster oeffnet sich erst per Klick darauf. Ohne +`--talk-name=org.kde.StatusNotifierWatcher` im Manifest kann Qt +(`QDBusTrayIcon`, KDE-Style) das StatusNotifierItem nicht beim Watcher +registrieren (`QDBusError("org.freedesktop.DBus.Error.ServiceUnknown")` +im Log) -- damit gab es keinen Weg, die GUI ueberhaupt zu oeffnen. + +Fix: `--talk-name=org.kde.StatusNotifierWatcher` zu `finish-args` +hinzugefuegt (kein breiterer `--socket=session-bus`, um beim +Minimal-Rechte-Ansatz des MVP zu bleiben). Nach Rebuild + Neuinstallation +registrierte sich das Tray-Item nachweisbar per D-Bus +(`busctl --user call ... org.kde.StatusNotifierItem Title` lieferte +`"Blitztext"`), kein `ServiceUnknown`-Fehler mehr im Log. + ### KDE Platform/Sdk 6.8 -- EOL-Hinweis Laut Flathub ist `org.kde.Platform`/`org.kde.Sdk` 6.8 als EOL markiert. diff --git a/packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml b/packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml index 58070f8..ee40e61 100644 --- a/packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml +++ b/packaging/flatpak/io.github.TimInTech.BlitztextLinux.yaml @@ -16,6 +16,7 @@ finish-args: - --socket=wayland - --socket=fallback-x11 - --socket=pulseaudio + - --talk-name=org.kde.StatusNotifierWatcher modules: - name: blitztext-linux-deps From f49594a0cabbfcdda2c90880e64f566c0affc5bb Mon Sep 17 00:00:00 2001 From: gummiflip Date: Sun, 12 Jul 2026 20:19:31 +0200 Subject: [PATCH 3/3] fix(docs): avoid secret-like API key examples --- README.de.md | 5 ++--- README.md | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/README.de.md b/README.de.md index 8747aec..b68ed55 100644 --- a/README.de.md +++ b/README.de.md @@ -404,11 +404,10 @@ Der Einstellungs-Dialog hat drei Tabs: API-Keys werden niemals in `config.json` gespeichert — sie werden zur Laufzeit aus Umgebungsvariablen gelesen. -**Empfohlen: `secrets.env`.** Lege deine(n) Key(s) in `~/.config/blitztext-linux/secrets.env` ab, ein `NAME=WERT`-Paar pro Zeile, zum Beispiel: +**Empfohlen: `secrets.env`.** Lege deine(n) Key(s) in `~/.config/blitztext-linux/secrets.env` ab, ein `NAME=WERT`-Paar pro Zeile — der Variablenname richtet sich nach dem unter **Einstellungen → KI-Workflows → „API-Key-Umgebung"** gewählten Anbieter (z. B. die OpenAI-Variable für OpenAI, die OpenRouter-Variable für OpenRouter), `WERT` ist der geheime Key von diesem Anbieter: ```bash -OPENAI_API_KEY=sk-... -# OPENROUTER_API_KEY=sk-or-... += ``` `./run.sh` und der systemd-User-Service laden diese Datei automatisch. `config.json` speichert nur den *Namen* der zu lesenden Umgebungsvariable (`openai_api_key_env`), niemals den Key selbst. diff --git a/README.md b/README.md index 5e1b01e..fb53385 100644 --- a/README.md +++ b/README.md @@ -404,11 +404,10 @@ The settings dialog has three tabs: API keys are never stored in `config.json` — they are read from environment variables at runtime. -**Recommended: `secrets.env`.** Place your key(s) in `~/.config/blitztext-linux/secrets.env`, one `NAME=VALUE` pair per line, for example: +**Recommended: `secrets.env`.** Place your key(s) in `~/.config/blitztext-linux/secrets.env`, one `NAME=VALUE` pair per line — the variable name matches the provider selected under **Settings → AI Workflows → "API key environment"** (e.g. the OpenAI variable for OpenAI, the OpenRouter variable for OpenRouter), and `VALUE` is the secret key you got from that provider: ```bash -OPENAI_API_KEY=sk-... -# OPENROUTER_API_KEY=sk-or-... += ``` `./run.sh` and the systemd user service load this file automatically. `config.json` only stores the *name* of the environment variable to read (`openai_api_key_env`), never the key itself.