Blitztext Linux

Your local AI voice assistant for Linux desktops on Wayland

🇬🇧 English | 🇩🇪 Deutsch

Record speech via hotkey, transcribe locally or online, optionally rewrite it with an LLM, and paste it directly into the active application.

🔗 Website: timintech.github.io/blitztextweb

_{Hold Alt (default hotkey), speak, release — the transcript lands directly in the active application.}

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).
• Compose window: Type, paste, or dictate any text, pick a text action, and let the AI rewrite it — no microphone needed. Includes tone selector, custom instruction with prompt inspection, variant navigation, and signature support.
• OpenRouter & custom LLM endpoints: Use OpenRouter or any OpenAI-compatible API as an alternative to OpenAI for all AI workflows.
• Audio export: Save read-aloud output as an audio file directly from the Read Aloud window.
• Custom names / terms: Extend the AI's vocabulary with your own terms, names, or technical words for perfect transcriptions.
• Global hotkeys: Record from anywhere in the system at any time.
• Auto-paste: Detects speech and pastes it right where your cursor is.
• 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.

The 5 workflows and hotkeys

Blitztext registers global hotkeys via evdev. With these combinations you have full control:

AI workflows

The AI workflows help with phrasing, tone, and emojis. You'll find the relevant settings under Settings → Text & AI:

LLM providers. Blitztext supports three provider modes, selectable under Settings → Text & AI → "LLM provider":

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

Text actions. Rewriting is built around five clearly separated actions. You select them under Settings → Text & AI → "Text action", in the Compose window, or in the ⋯ menu of the main widget:

The target tone applies to Improve text and Change tone. Older configurations with the previous nine writing-style presets are migrated automatically to the closest action (e.g. "Email – formal" → Change tone, professional). Custom names/terms are preserved in every action.

Compose window

The Compose window (✍ Edit text… in the tray menu or the pen button in the main widget) lets you draft, rewrite, and refine text using the AI — without recording your voice. It is ideal for polishing emails, notes, or messages before pasting them anywhere.

How to open: Click the tray icon → ✍ Edit text… or click the gold pen button in the main window widget.

What you can do in the Compose window:

_{Inspect and edit the LLM instruction directly inside the Compose window.}

Tray icon and context menu

The microphone in the system tray is your indicator of the current state:

Green (IDLE) Ready — waiting for your action.

Red (RECORDING) Recording is actively running.

Orange (TRANSCRIBING) Magic in progress (transcription / AI rephrasing).

Gray (ERROR) Oops, something went wrong.

The tray context menu gives you quick access to all workflows, the compose window, text actions, dictation mode, history, and settings:

Main window: Single-panel widget

The main window is a compact, frameless desktop widget with a consistent dark look, gold accents, and immediate visual feedback:

Idle Ready, standing by for input.

Recording Live timer and stereo wave bars.

Processing Animated gold spinning ring.

Options menu Workflows and quick actions.

• Central gold microphone: Prominent circular button with metallic gradient and lightning bolt cut-out. Click to toggle recording on and off.
• Dynamic visual feedback:
  • Idle: Green status dot with duration counter (Ready: 00:00).
  • Recording: Amber indicator, live recording timer, and animated stereo wave bars flanking the mic.
  • Processing: Rotating gold progress ring around the microphone (Transcribing…).
• Tool row:
  • ✍ Compose button (highlighted pen icon): Opens the Compose window for drafting and rewriting.
  • 🕒 History button (with counter badge): Opens the transcript history with recent entries.
  • 🔊 Read aloud button (speaker icon): Opens the TTS window to synthesize speech.
  • ⚙ Settings button (gear icon): Opens the settings dialog.
  • ⋯ More options button: Pops up quick access to Dictate & improve, text improvement presets (Shorten, Expand, Change tone), Custom instruction, Batch dictation, and Discard.

The widget opens at startup, via the tray entry Show window, or by clicking the tray icon. Closing only hides the widget — the app keeps running in the background tray.

Dictation, history, and read-aloud

In addition to the workflows, the tool offers three convenience functions:

  

.venv/bin/pip install piper-tts
# Place voices (.onnx + .onnx.json) into ~/.local/share/piper-voices/

Installation & Start

Quick install (recommended)

The easiest way to set up Blitztext on your system:

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, installs the systemd user service, and enables it for autostart without starting it immediately.

After installation

1. Restart required only if you chose hotkey mode (or log out/in) so the input group becomes active. Then verify:

   bash scripts/verify.sh
   

2. Test manually:

   ./run.sh
   

   (Does the tray icon appear and do the hotkeys respond? Then everything went smoothly!)
3. Close the manual test app, then start the already enabled autostart service:

   systemctl --user start blitztext-linux
   

Ubuntu 26.04 GNOME / Wayland status (verified 2026-08-10): A clean installation on Python 3.14.4 passed scripts/verify.sh with 17 PASS, 0 FAIL, 0 WARN before the first user configuration and 18 PASS, 0 FAIL, 0 WARN afterwards. The main window, GNOME AppIndicator tray, audio recording, local openai-whisper transcription, the global Left-Alt hotkey, Wayland clipboard, ydotool auto-paste, and systemd user-service autostart were all exercised in the real desktop session. This verification applies to the native install, not the experimental Flatpak manifest.

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

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

sudo usermod -aG input $USER

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

pipx install --python "$(command -v python3)" openai-whisper
pipx inject openai-whisper faster-whisper   # optional, for accelerated execution

systemctl --user start ydotool.service

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

./run.sh

Configuration

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). The configuration file can be opened directly from the settings: Settings → General → "Open configuration file".

The settings dialog has three tabs:

Speech Recognition — Whisper model, backend, language, hotkey mode, and recording key.


Text & AI — system prompt, API key environment, LLM provider, base URL, model, text action, and emoji density.


General — Auto-Paste, dictation folder, history size, interface language, and signature.

{
  "model": "base",
  "language": "de",
  "ui_language": "en",
  "backend": "openai-whisper",
  "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",
  "llm_base_url": "",
  "llm_model": "gpt-4o-mini",
  "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": {
    "text_improver_tone": "neutral",
    "writing_preset": "standard",
    "emoji_density": "medium",
    "dampf_system_prompt": ""
  }
}

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 — the variable name matches the provider selected under Settings → Text & AI → "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:

<VARIABLE_NAME>=<your-secret-value>

./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 → Text & AI → "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 (Dictate & improve, Make it factual, Add emojis) 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

Run the test suite locally:

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 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 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 for how to propose changes.

.
├── app/
│   ├── __init__.py
│   ├── audio_recorder.py   # PulseAudio/PipeWire recording via parec
│   ├── blitztext_linux.py  # PyQt6 main application (system tray)
│   ├── compose_window.py   # Compose window for text-only AI rewriting
│   ├── config.py           # Configuration manager
│   ├── history_panel.py    # Transcript history panel
│   ├── hotkey_service.py   # evdev-based hotkey daemon
│   ├── i18n.py             # Interface translations (DE/EN)
│   ├── llm_service.py      # OpenAI / OpenRouter / custom endpoint interface
│   ├── main_window.py      # Main application window
│   ├── paste_service.py    # Wayland clipboard integration
│   ├── transcribe.py       # Whisper transcription
│   ├── tts_window.py       # Read Aloud window with audio export
│   ├── workflows.py        # Workflow definitions
│   └── writing_presets.py  # Text action definitions and legacy preset migration
├── packaging/flatpak/      # Experimental Flatpak MVP spike (see above)
├── tests/                  # Test suite
└── README.md               # This document (German version: README.de.md)

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:

The original project is an experimental, non-commercial open-source project under the MIT license. The associated website (blitztext.de) is operated by Blackboat Internet GmbH:

• Imprint: https://www.blackboat.com/impressum
• Privacy: https://www.blackboat.com/datenschutz

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.

The Linux verification script also includes improved session-aware desktop diagnostics for X11, Wayland, and clipboard backends. The compatibility matrix is diagnostic guidance, not a support promise.