From 3be5c08b74a98f2c494a2b23e969202f893dc162 Mon Sep 17 00:00:00 2001 From: gummiflip Date: Thu, 2 Jul 2026 10:08:36 +0200 Subject: [PATCH] docs(readme): reconcile config example and install steps with code Fixes drift between the README (EN+DE) and the actual runtime: - Wrong JSON field names in the example config: base_url -> llm_base_url, compose_signature -> compose_signature_text (must match app/config.py). - Wrong tts_openai_voice default documented (nova, actually marin). - Missing config fields never documented: transcription_hotkey, paste_key_delay_ms, notes_folder, history_size, tts_voice, tts_provider, tts_openai_model, tts_speed. - hotkey_mode example value aligned with the actual code default (hold). - install.sh's interactive hotkey-mode prompt (BLITZTEXT_NO_HOTKEY) was undocumented in "What does the script do?" and "After installation". - Manual-install instructions were missing the CPU-only PyTorch step that scripts/install.sh performs to avoid pulling multi-GB CUDA wheels. CI badge, screenshots, and the upstream blitztext-app attribution link were checked and are already accurate -- left untouched. --- README.de.md | 36 +++++++++++++++++++++++++++--------- README.md | 38 ++++++++++++++++++++++++++++---------- 2 files changed, 55 insertions(+), 19 deletions(-) diff --git a/README.de.md b/README.de.md index 29a9b5e..daa49a9 100644 --- a/README.de.md +++ b/README.de.md @@ -48,12 +48,13 @@ bash scripts/install.sh 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. +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 erforderlich** (oder ab-/anmelden), damit die Gruppe `input` aktiv wird. Danach checken: +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 ``` @@ -102,9 +103,11 @@ 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 ``` @@ -347,14 +350,23 @@ Der Einstellungs-Dialog hat drei Tabs: "language": "de", "ui_language": "de", "backend": "openai-whisper", - "hotkey_mode": "toggle", + "hotkey_mode": "hold", + "transcription_hotkey": "KEY_LEFTALT", "openai_api_key_env": "OPENAI_API_KEY", "autopaste": true, + "paste_key_delay_ms": 80, "audio_device": "@DEFAULT_SOURCE@", + "notes_folder": "~/Blitztext-Notizen", + "history_size": 50, "llm_provider": "openai", - "base_url": "", + "llm_base_url": "", "llm_model": "gpt-4o-mini", - "compose_signature": "", + "tts_provider": "piper", + "tts_voice": "", + "tts_openai_model": "gpt-4o-mini-tts", + "tts_openai_voice": "marin", + "tts_speed": 1.0, + "compose_signature_text": "", "compose_signature_auto_append": false, "compose_custom_preset_text": "", "workflows": { @@ -373,18 +385,24 @@ Der Einstellungs-Dialog hat drei Tabs: - **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`. - **openai_api_key_env**: Name der Umgebungsvariable für den API-Key. Standard: `OPENAI_API_KEY`. Für OpenRouter: `OPENROUTER_API_KEY`. - **llm_provider**: `openai` (Standard), `openrouter` oder `custom`. -- **base_url**: Eigene API-Base-URL. Leer = OpenAI-Standard. Für OpenRouter: `https://openrouter.ai/api/v1`. +- **llm_base_url**: Eigene API-Base-URL. Leer = OpenAI-Standard. Für OpenRouter: `https://openrouter.ai/api/v1`. - **llm_model**: Modellname beim Anbieter, z. B. `gpt-4o-mini` (OpenAI) oder `openai/gpt-4o` (OpenRouter). - **autopaste**: Fügt per `ydotool` ein. +- **paste_key_delay_ms**: Verzögerung in Millisekunden zwischen simulierten Tastenereignissen für Auto-Paste. Standard: `80`. - **audio_device**: Name der Audioquelle. -- **compose_signature**: Signaturtext, der im Compose-Fenster angehängt wird. +- **notes_folder**: Ordner für Diktat-Notizen; er muss innerhalb deines Home-Verzeichnisses liegen. Standard: `~/Blitztext-Notizen`. +- **history_size**: Anzahl der zuletzt gespeicherten Transkripte im Verlaufsfenster. Auf 10-100 begrenzt. Standard: `50`. +- **compose_signature_text**: Signaturtext, der im Compose-Fenster angehängt wird. - **compose_signature_auto_append**: Signatur nach jeder Generierung im Compose-Fenster automatisch anhängen (`true`/`false`). - **compose_custom_preset_text**: Freier System-Prompt für die Option „Eigenes Preset…" im Compose-Fenster. - **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`, `nova`). +- **tts_voice**: Stimmenname für den aktiven TTS-Anbieter. Standard: `""` = Piper-Standardstimme. +- **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`. +- **tts_speed**: Sprechgeschwindigkeit für „Vorlesen" als Multiplikator. Standard: `1.0`. - **workflows**: Feintuning von Tonalität (`text_improver_tone`), Schreibstil-Vorlage (`writing_preset`), Emojis (`emoji_density`) und dem Dampf-Prompt (`dampf_system_prompt`). diff --git a/README.md b/README.md index 09b2f34..e538480 100644 --- a/README.md +++ b/README.md @@ -48,12 +48,13 @@ bash scripts/install.sh 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. Sets up a `.venv` environment and installs `openai-whisper`/`faster-whisper`. -4. Prepares `ydotool.service` and the systemd user service. +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** (or log out/in) so the `input` group becomes active. Then verify: +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 ``` @@ -102,9 +103,11 @@ 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 ``` @@ -351,14 +354,23 @@ The settings dialog has three tabs: "language": "de", "ui_language": "en", "backend": "openai-whisper", - "hotkey_mode": "toggle", + "hotkey_mode": "hold", + "transcription_hotkey": "KEY_LEFTALT", "openai_api_key_env": "OPENAI_API_KEY", "autopaste": true, + "paste_key_delay_ms": 80, "audio_device": "@DEFAULT_SOURCE@", + "notes_folder": "~/Blitztext-Notizen", + "history_size": 50, "llm_provider": "openai", - "base_url": "", + "llm_base_url": "", "llm_model": "gpt-4o-mini", - "compose_signature": "", + "tts_provider": "piper", + "tts_voice": "", + "tts_openai_model": "gpt-4o-mini-tts", + "tts_openai_voice": "marin", + "tts_speed": 1.0, + "compose_signature_text": "", "compose_signature_auto_append": false, "compose_custom_preset_text": "", "workflows": { @@ -377,18 +389,24 @@ The settings dialog has three tabs: - **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`. - **openai_api_key_env**: Name of the environment variable for the API key. Default: `OPENAI_API_KEY`. For OpenRouter use `OPENROUTER_API_KEY`. - **llm_provider**: `openai` (default), `openrouter`, or `custom`. -- **base_url**: Custom API base URL. Empty = OpenAI default. For OpenRouter: `https://openrouter.ai/api/v1`. +- **llm_base_url**: Custom API base URL. Empty = OpenAI default. For OpenRouter: `https://openrouter.ai/api/v1`. - **llm_model**: Model name at the provider, e.g. `gpt-4o-mini` (OpenAI) or `openai/gpt-4o` (OpenRouter). - **autopaste**: Pastes via `ydotool`. +- **paste_key_delay_ms**: Delay in milliseconds between synthetic key events for auto-paste. Default: `80`. - **audio_device**: Name of the audio source. -- **compose_signature**: Signature text appended in the Compose window. +- **notes_folder**: Folder for dictation notes; it must stay inside your home directory. Default: `~/Blitztext-Notizen`. +- **history_size**: Number of recent transcripts kept in the History window. Clamped to 10-100. Default: `50`. +- **compose_signature_text**: Signature text appended in the Compose window. - **compose_signature_auto_append**: Auto-append signature after every generation in Compose (`true`/`false`). - **compose_custom_preset_text**: Free-form system prompt for the "Custom preset…" option in the Compose window. - **tts_provider**: TTS provider for "Read aloud" — `piper` (local, default) or `openai` (cloud). -- **tts_openai_model** / **tts_openai_voice**: Model and voice for OpenAI Cloud TTS (default: `gpt-4o-mini-tts`, `nova`). -- **tts_openai_consent**: `true` once the one-time privacy confirmation for Cloud TTS has been granted. +- **tts_voice**: Voice name used by the active TTS provider. Default: `""` = Piper default voice. +- **tts_openai_model** / **tts_openai_voice**: Model and voice for OpenAI Cloud TTS (default: `gpt-4o-mini-tts`, `marin`). +- **tts_openai_consent**: `true` once the one-time privacy confirmation for Cloud TTS has been granted. Default: `false`. +- **tts_speed**: Speech speed multiplier for "Read aloud". Default: `1.0`. - **workflows**: Fine-tuning of tonality (`text_improver_tone`), writing-style preset (`writing_preset`), emojis (`emoji_density`), and the steam-release prompt (`dampf_system_prompt`).