Add README and cross-platform export tool

README documents minimal setup, run, and config for Linux and Windows. export.py bundles just the source into a zip (no .venv, caches, or API key files) for moving to another machine; it's pure stdlib run via 'uv run export.py', so it behaves identically on Linux and Windows with no shell required. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-31 09:03:43 -04:00
parent 777d4bef33
commit 5864d78081
2 changed files with 119 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Blurt
+
+Tray-based push-to-talk voice-to-text for Linux and Windows. Toggle recording
+with a hotkey, speak, toggle off — Blurt transcribes the clip and copies the
+text to your clipboard.
+
+If a transcript starts with `to my agent`, the rest is dispatched as an agent
+task instead of copied.
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.11+.
+
+```sh
+uv sync
+```
+
+### API key
+
+Blurt reads the key for its current model's provider in this order:
+environment variable → OS keyring → local file.
+
+| Provider   | Env var              | Keyring (`service` / `user`)    | File                 |
+|------------|----------------------|---------------------------------|----------------------|
+| OpenAI     | `OPENAI_API_KEY`     | `openai-api-key` / `felixm`     | `api_key.txt`        |
+| OpenRouter | `OPENROUTER_API_KEY` | `openrouter-api-key` / `felixm` | `openrouter_key.txt` |
+
+Key files and runtime config stay local (gitignored).
+
+## Running
+
+**Linux** — `uv run blurt` starts the tray icon. Bind a hotkey to
+`./blurt-toggle`, which signals the running instance to start/stop recording.
+
+**Windows** — launch `blurt.vbs` (runs Blurt with no console window). The
+global hotkey is **F20**.
+
+## Configuration
+
+Set from the tray menu, or via files / env vars:
+
+- **Model** — `model.txt` / `BLURT_TRANSCRIPTION_MODEL`. For lowest latency use
+  `openai/whisper-large-v3-turbo` (OpenRouter, served by Groq).
+- **Language** — `language.txt` / `BLURT_TRANSCRIPTION_LANGUAGE` (`en`, `de`).
+- **Input device** — tray menu.
+
+Logs are written to `blurt.log` in your temp directory (openable from the tray
+menu).
+
+## Moving to another machine
+
+`uv run export.py` writes a zip of just the source (no 200 MB+ `.venv`, no
+caches, no key files) to your temp directory. It's pure Python, so it runs the
+same on Linux and Windows — no shell needed — and it only reads, so it's safe
+while Blurt is recording. Unzip on the other machine and `uv sync` to rebuild
+`.venv` for that OS. (Or simply `git clone` the repo fresh.)