hermes/blitztext-app-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b72936be31
blitztext-app-linux/README.md

12 KiB
Raw Blame History

Blitztext App Linux

Blitztext App Linux is a native Linux dictation and writing assistant. Focus any text field, trigger a workflow, speak, and Blitztext types the result back into the application you were already using.

It can type a plain transcript, rewrite rough speech with an OpenAI-compatible LLM, route spoken commands to different workflows, benchmark STT engines, and stream live words from a Riva/NIM realtime speech server.

This is a host desktop app, not a browser app and not a hosted service. The current Linux version is built around GTK, AppIndicator, global hotkeys, faster-whisper, optional OpenAI-compatible endpoints, optional Riva/NIM realtime STT, and xdotool text delivery.

Status: experimental Linux/X11 app. Bring your own local models or endpoints. No hosted Blitztext backend is included.

Inspiration

Blitztext App Linux is inspired by cmagnussen/blitztext-app, the original macOS menu-bar app for turning speech into text and cleaner writing. This repository keeps the spirit of that workflow while implementing a Linux-native version with Linux desktop APIs and Linux-friendly model backends.

Features

  • Native Linux tray app: run Blitztext from the system tray, open the GTK control panel, or run it headless with global hotkeys only.
  • Plain dictation: record speech, transcribe it, and type the raw text into the focused X11 window.
  • Rewrite workflows: turn rough speech into a nicer email, improved text, a calmer message, emoji-rich text, or any custom prompt you define.
  • Realtime STT streaming: use a riva_realtime STT engine, such as Nemotron ASR Streaming, to type stable words while you are still speaking.
  • Voice-keyword routing: use one routing hotkey and say a workflow keyword at the start or end of your speech to choose the preset.
  • Two input styles: use direct workflow hotkeys, or the modifier workflow: Ctrl+Super to start, Ctrl to stop and type, Alt to stop/type/send, Esc to cancel.
  • Push-to-talk option: hold the start modifier to record and release it to finish.
  • Multiple STT engines: local faster-whisper, OpenAI-compatible batch STT endpoints, and Riva/NIM realtime WebSocket STT.
  • Multiple LLM engines: OpenAI-compatible chat endpoints for OpenAI, local vLLM, llama-swap, Ollama /v1, LM Studio, Groq, OpenRouter, and similar servers.
  • STT benchmark tab: compare configured STT engines against a reference WAV and transcript.
  • Settings UI: edit workflows, engines, input mode, microphone, language, benchmark files, autostart, logs, and About metadata.
  • About page: shows the app version, source repository, changelog, license, and legal notes.
  • Debian package: build a local .deb with the launcher, icon, bundled Python environment, and system dependency declarations.

How It Works

Batch workflows
---------------
focused app -> global hotkey -> record mic -> STT engine
                                      |
                                      +-> mode "transcribe" -> type/paste text
                                      |
                                      +-> mode "rewrite" -> LLM -> type/paste text

Realtime workflow
-----------------
focused app -> stream workflow -> mic PCM chunks -> Riva/NIM WebSocket
                                               |
                                               +-> stable partial text -> xdotool

Blitztext remembers the focused X11 window when recording starts, then delivers the final text back to that window. Delivery can be direct typing or clipboard paste, depending on your configuration.

Requirements

  • Linux desktop running an X11 session.
  • Python 3.11+ when running from source.
  • xdotool for text delivery.
  • notify-send from libnotify-bin for desktop notifications.
  • One recorder: pw-record, parecord, or arecord.
  • python3-gi and AppIndicator/Ayatana typelibs for the GTK tray.
  • Optional: CUDA-capable faster-whisper/CTranslate2 setup for GPU local STT.
  • Optional: an OpenAI-compatible chat endpoint for rewrite workflows.
  • Optional: a Riva/NIM realtime server for live streaming STT.

On Ubuntu/Debian:

sudo apt install xdotool libnotify-bin pipewire-bin python3-gi

Wayland is not the primary target yet. The current app uses xdotool, so use an X11 session for reliable typing into other applications.

Install

Debian Package

The recommended Ubuntu/Debian path is to build and install the local package:

cd linux
bash packaging/build-deb.sh
sudo apt install ./dist/blitztext_*.deb

This installs Blitztext under /opt/blitztext, adds a desktop launcher, installs the app icon, and provides the blitztext command.

Start it with:

blitztext tray

From Source

cd linux
./install.sh
.venv/bin/python -m blitztext tray

install.sh creates a virtual environment with --system-site-packages so the app can see the system python3-gi package used by GTK/AppIndicator.

Run

blitztext tray          # tray app with workflow menu, default installed mode
blitztext gui           # GTK control panel
blitztext run           # headless hotkey daemon
blitztext config-path   # print config file path
blitztext --version     # print app version

From a source checkout, use:

cd linux
.venv/bin/python -m blitztext tray
.venv/bin/python -m blitztext gui
.venv/bin/python -m blitztext run
.venv/bin/python -m blitztext transcribe sample.wav

Default Workflows

Workflow Mode Default trigger Result
Transcribe transcribe voice-routing default Types the raw transcript
Nicer email rewrite Ctrl+Alt+E Turns rough notes into a polished email
Improve text rewrite Ctrl+Alt+I Cleans spelling, grammar, and wording
Calm down rewrite Ctrl+Alt+C Rewrites frustrated speech into a calm message
Add emojis rewrite Ctrl+Alt+J Keeps the text and adds fitting emojis
STT Streaming stream user-created / optional Types live words from realtime STT

The default config uses voice-keyword routing as the primary input style. Press the routing hotkey, speak normally, and optionally say a preset keyword such as "nicer email" or "calm down" at the beginning or end of the utterance.

Configuration

Blitztext writes its configuration to:

~/.config/blitztext/config.toml

You can edit it through Settings or directly as TOML. The settings window contains:

  • Presets: workflow name, icon, description, mode, hotkey, keywords, prompt, model override, and temperature override.
  • Engines: STT and LLM engine presets, status checks, and STT test.
  • Input: modifier mode, direct hotkey mode, push-to-talk, microphone, output method, typing delay, language, and quality gates.
  • General: notifications, autostart, and app behavior.
  • Benchmark: compare STT engines with a reference WAV and text file.
  • Log: inspect runtime messages.
  • About: version, changelog, source, license, and legal information.

STT Engines

Local transcription uses faster-whisper:

[stt]
active = "Local faster-whisper"

[[stt_engine]]
name = "Local faster-whisper"
type = "local"

[whisper]
model = "small"
device = "auto"
compute_type = "auto"
beam_size = 5

Batch remote transcription uses OpenAI-compatible /audio/transcriptions servers:

[[stt_engine]]
name = "faster-whisper-server"
type = "openai"
url = "http://localhost:8010/v1"
model = "Systran/faster-whisper-base"
api_key_env = ""

Realtime streaming uses a Riva/NIM realtime WebSocket server:

[[stt_engine]]
name = "Nemotron ASR Streaming"
type = "riva_realtime"
url = "http://127.0.0.1:8006/v1"
model = ""
api_key_env = ""

Streaming engines are live-only. They are used by workflows with mode = "stream", not by batch transcription or the benchmark tab.

Realtime STT Streaming

To use Nemotron ASR Streaming or another compatible Riva/NIM realtime server:

  1. Start the realtime STT server.
  2. Open Settings > Engines.
  3. Click + Stream to add the Nemotron ASR Streaming preset.
  4. Save and restart Blitztext if prompted.
  5. Create or edit a workflow with mode = "stream".

Example:

[general]
language = "en-US"

[stt]
active = "Nemotron ASR Streaming"

[[workflow]]
name = "STT Streaming"
description = "Live words while you speak."
hotkey = "<ctrl>+<alt>+s"
mode = "stream"

The tested Nemotron ASR Streaming NIM exposes an English en-US model. For that server, use language = "en" or language = "en-US".

Rewrite Engines

Rewrite workflows send the transcript to an OpenAI-compatible chat endpoint:

[llm]
active = "Default"

[[llm_engine]]
name = "Default"
type = "cloud"
url = "https://api.openai.com/v1"
model = "gpt-4o-mini"
api_key_env = "OPENAI_API_KEY"
temperature = 0.3

For local rewriting, point the URL at a local OpenAI-compatible server:

[[llm_engine]]
name = "Local llama-swap"
type = "local"
url = "http://localhost:28080/v1"
model = "Qwen3.5-4B"
api_key_env = ""
temperature = 0.3

Privacy

Blitztext App Linux does not include a hosted backend. Where your audio or text goes depends on the engines you configure:

Local STT:              your desktop -> local faster-whisper
Remote batch STT:       your desktop -> configured /audio/transcriptions endpoint
Realtime STT:           your desktop -> configured Riva/NIM realtime endpoint
Rewrite workflows:      your desktop -> configured OpenAI-compatible chat endpoint
Text delivery:          Blitztext -> xdotool -> focused X11 window

Do not use remote endpoints with sensitive content unless you understand and accept the data handling of those services. See docs/privacy.md for more detail.

Project Structure

linux/
  blitztext/      Linux app package: GTK UI, tray, daemon, STT, LLM, config
  packaging/      Debian packaging, desktop file, app icons
  README.md       Detailed Linux usage guide
  CHANGELOG.md    Linux app changelog
docs/             Setup, privacy, roadmap, release, and project notes
BlitztextMac/     Legacy/upstream macOS reference code kept for context
README.md         This Linux-first project overview

Development

Useful checks:

cd linux
.venv/bin/python -m py_compile blitztext/*.py
.venv/bin/python -m blitztext --version
.venv/bin/python -m blitztext config-path

Useful docs:

Current Limits

  • X11 is required for reliable text delivery through xdotool.
  • Realtime streaming depends on a compatible Riva/NIM realtime server.
  • Rewrite workflows depend on the LLM endpoint you configure.
  • Local STT speed depends on your faster-whisper model, CPU/GPU, and CTranslate2 build.
  • This is experimental open-source software provided as-is.

License

Code is released under the MIT License. See LICENSE.

Project names, logos, and app icons are not automatically granted as trademarks or brand assets. See TRADEMARKS.md.

Legal / Impressum & Datenschutz

This is an experimental, non-commercial open-source project, provided as-is under the MIT License without warranty or support. Nothing is sold here and no installation or operation is performed on your behalf.

The companion website (blitztext.de) is operated by Blackboat Internet GmbH: