scribe-cli 0.13.1__tar.gz → 0.17.0__tar.gz

scribe_cli-0.17.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [ perrette ]

scribe_cli-0.17.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__
+*.pyc
+.venv
+build
+dist
+scribe/_version.py
+
+# Autonomous roadmap workflows (local coordination artifacts; never committed)
+workflows/

scribe_cli-0.17.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: scribe-cli
+Version: 0.17.0
+Summary: Speech-to-text CLI and system-tray app for dictating into any focused window. Local (vosk, faster-whisper) or cloud (groq, openai) backends, batch or streaming.
+Author-email: Mahé Perrette <mahe.perrette@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Mahé Perrette
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        Note: This project relies on external packages that may have more restrictive
+        licenses. For example, the `pynput` package is licensed under LGPLv3, which
+        has different requirements compared to the MIT License. Please review the
+        licenses of all dependencies before using or distributing this software to
+        ensure compliance with their respective terms.
+Project-URL: Homepage, https://github.com/perrette/scribe
+Keywords: speech-to-text,speech recognition,transcription,dictation,voice-typing,voice-to-text,realtime,streaming,language,AI,local,API,cli,tray,vosk,whisper,openai,groq,gpt-4o,linux,wayland,keyboard,clipboard
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+Requires-Dist: tqdm
+Requires-Dist: requests
+Requires-Dist: pyperclip
+Requires-Dist: unidecode
+Requires-Dist: termcolor
+Requires-Dist: platformdirs
+Requires-Dist: desktop-ai-core>=0.2.0
+Provides-Extra: keyboard
+Requires-Dist: pynput; extra == "keyboard"
+Provides-Extra: whisper
+Requires-Dist: faster-whisper; extra == "whisper"
+Provides-Extra: whisper-futo
+Requires-Dist: pywhispercpp; extra == "whisper-futo"
+Provides-Extra: vosk
+Requires-Dist: vosk; extra == "vosk"
+Provides-Extra: app
+Requires-Dist: pystray; extra == "app"
+Requires-Dist: PyGObject; extra == "app"
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.37.0; extra == "openai"
+Requires-Dist: soundfile; extra == "openai"
+Provides-Extra: groq
+Requires-Dist: openai<3,>=2.37.0; extra == "groq"
+Requires-Dist: soundfile; extra == "groq"
+Provides-Extra: all
+Requires-Dist: pynput; extra == "all"
+Requires-Dist: faster-whisper; extra == "all"
+Requires-Dist: pywhispercpp; extra == "all"
+Requires-Dist: openai<3,>=2.37.0; extra == "all"
+Requires-Dist: soundfile; extra == "all"
+Requires-Dist: vosk; extra == "all"
+Requires-Dist: pystray; extra == "all"
+Dynamic: license-file
+
+[![pypi](https://img.shields.io/pypi/v/scribe-cli)](https://pypi.org/project/scribe-cli)
+![](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fperrette%2Fscribe%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+
+# Scribe  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" width="48">
+
+**Talk. It types.** Scribe is a speech-to-text CLI and tray app that
+pipes transcribed text straight into the focused window. It supports local and
+cloud-based APIs, batch and streaming workflows.
+
+## What it does
+
+- Records from your mic and transcribes via one of four backends —
+  **Vosk** (local, streaming), **Whisper** (local, batch), **OpenAI**
+  (cloud, batch *or* streaming), **Groq** (cloud, batch).
+- Delivers the transcript three ways: paste into the focused window
+  (default), copy to clipboard, or print to the terminal.
+- Runs as a **system tray icon** with a single Record button, or as an
+  interactive **terminal TUI** — same menu in both.
+- Hooks into your DE's keyboard shortcuts via `SIGUSR1` (toggle
+  recording) and `SIGUSR2` (cancel).
+- Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows;
+  works under Termux for clipboard / terminal output.
+
+## Install
+
+```bash
+sudo apt-get install portaudio19-dev xclip   # Ubuntu; macOS: brew install portaudio
+pip install scribe-cli[all]
+export GROQ_API_KEY=YOURAPIKEY                # or OPENAI_API_KEY, or skip and run local
+```
+
+See documentation below for setting up keyboard input on Ubuntu Wayland.
+
+
+## Usage
+
+In a terminal:
+
+```bash
+scribe
+```
+
+This launches the system tray icon. Press Record, speak, press Stop —
+the transcription lands in the focused window. Scribe picks the first
+backend whose key / dependency is present, in order **`groq` →
+`openai` → `whisper` → `vosk`**, so with `GROQ_API_KEY` set the
+command above is equivalent to:
+
+```bash
+scribe --backend groq --model whisper-large-v3-turbo
+```
+
+<img src=https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png width=300px>
+
+You can override the defaults or drop the tray entirely:
+
+```bash
+scribe --backend openai --model gpt-4o-mini-transcribe # OpenAI sweet spot
+scribe --backend openai --model gpt-realtime-whisper   # OpenAI streaming
+scribe --backend whisper --model small                 # local, no API key
+scribe --frontend terminal                             # interactive TUI menu
+scribe --frontend terminal --no-interactive            # record immediately, no menu
+scribe --mode clipboard                                # copy to clipboard, no keystroke
+scribe --mode terminal                                 # only print to stdout
+scribe -o transcript.txt                               # also append to a file
+```
+
+With `--no-interactive` (terminal frontend only), scribe skips the
+interactive menu and starts recording right away — handy for scripted,
+one-shot transcriptions. `--no-prompt` is kept as a deprecated alias.
+
+Bias the recogniser toward names, jargon, or a domain glossary with
+`--prompt "free text hint"` and `--words word1 word2 ...` (each also
+accepts a `--prompt-file` / `--words-file` companion). See
+[docs/backends.md › Vocabulary biasing](docs/backends.md#vocabulary-biasing)
+for what each backend does with them.
+
+
+## Backends at a glance
+
+| Backend         | `--backend` | Default model              | Streaming model(s)        | Requires                            |
+|-----------------|-------------|----------------------------|---------------------------|-------------------------------------|
+| Groq (cloud)    | `groq`      | `whisper-large-v3-turbo`   | —                         | `GROQ_API_KEY`                      |
+| OpenAI (cloud)  | `openai`    | `gpt-4o-mini-transcribe`   | `gpt-realtime-whisper`    | `OPENAI_API_KEY`                    |
+| Whisper (local) | `whisper`   | `small`                    | —                         | `pip install scribe-cli[whisper]`   |
+| Vosk (local)    | `vosk`      | language-dependent         | all Vosk models           | `pip install scribe-cli[vosk]`      |
+
+Whether a transcription appears live as you speak or all at once when
+you stop depends on the **model** picked — see
+[docs/backends.md](docs/backends.md).
+
+
+### Getting an API key
+
+Groq is a good cloud backend to start with — very fast, quite accurate, and the
+**free tier** is generous enough for everyday dictation. Sign up at
+[console.groq.com](https://console.groq.com/), create an API key
+under **Settings → API Keys**, and export it as `GROQ_API_KEY`.
+
+I personally use [OpenAI](https://openai.com/api/) with `gpt-4o-mini-transcribe` as it is also fast and perhaps more accurate for my accent-tainted English.
+
+
+## Documentation
+
+- [Installation & dependencies](docs/installation.md) — PortAudio,
+  extras, Ubuntu / GNOME tray libs.
+- [Backends in detail](docs/backends.md) — model lists, when to pick
+  which, the realtime model.
+- [Keyboard modes & typer backends](docs/keyboard.md) — keystroke vs
+  clipboard, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](docs/tray.md) — menu tree, icon
+  states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart (`scribe-install`)](docs/desktop-install.md)
+  — GNOME / KDE launcher integration.
+- [Fine tuning & CLI reference](docs/cli.md) — every `scribe --help`
+  flag with examples.
+
+## Compatibility
+
+Initially developed for Python 3 on Ubuntu 24.04 (GNOME + Wayland);
+works on macOS and Windows too. Wayland keystroke injection is
+convoluted but [solved](docs/keyboard.md). For dependencies of
+individual subsystems, check `pynput` (keyboard) and `pystray` (tray
+icon).

scribe_cli-0.17.0/README.md

@@ -0,0 +1,124 @@
+[![pypi](https://img.shields.io/pypi/v/scribe-cli)](https://pypi.org/project/scribe-cli)
+![](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fperrette%2Fscribe%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+
+# Scribe  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" width="48">
+
+**Talk. It types.** Scribe is a speech-to-text CLI and tray app that
+pipes transcribed text straight into the focused window. It supports local and
+cloud-based APIs, batch and streaming workflows.
+
+## What it does
+
+- Records from your mic and transcribes via one of four backends —
+  **Vosk** (local, streaming), **Whisper** (local, batch), **OpenAI**
+  (cloud, batch *or* streaming), **Groq** (cloud, batch).
+- Delivers the transcript three ways: paste into the focused window
+  (default), copy to clipboard, or print to the terminal.
+- Runs as a **system tray icon** with a single Record button, or as an
+  interactive **terminal TUI** — same menu in both.
+- Hooks into your DE's keyboard shortcuts via `SIGUSR1` (toggle
+  recording) and `SIGUSR2` (cancel).
+- Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows;
+  works under Termux for clipboard / terminal output.
+
+## Install
+
+```bash
+sudo apt-get install portaudio19-dev xclip   # Ubuntu; macOS: brew install portaudio
+pip install scribe-cli[all]
+export GROQ_API_KEY=YOURAPIKEY                # or OPENAI_API_KEY, or skip and run local
+```
+
+See documentation below for setting up keyboard input on Ubuntu Wayland.
+
+
+## Usage
+
+In a terminal:
+
+```bash
+scribe
+```
+
+This launches the system tray icon. Press Record, speak, press Stop —
+the transcription lands in the focused window. Scribe picks the first
+backend whose key / dependency is present, in order **`groq` →
+`openai` → `whisper` → `vosk`**, so with `GROQ_API_KEY` set the
+command above is equivalent to:
+
+```bash
+scribe --backend groq --model whisper-large-v3-turbo
+```
+
+<img src=https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png width=300px>
+
+You can override the defaults or drop the tray entirely:
+
+```bash
+scribe --backend openai --model gpt-4o-mini-transcribe # OpenAI sweet spot
+scribe --backend openai --model gpt-realtime-whisper   # OpenAI streaming
+scribe --backend whisper --model small                 # local, no API key
+scribe --frontend terminal                             # interactive TUI menu
+scribe --frontend terminal --no-interactive            # record immediately, no menu
+scribe --mode clipboard                                # copy to clipboard, no keystroke
+scribe --mode terminal                                 # only print to stdout
+scribe -o transcript.txt                               # also append to a file
+```
+
+With `--no-interactive` (terminal frontend only), scribe skips the
+interactive menu and starts recording right away — handy for scripted,
+one-shot transcriptions. `--no-prompt` is kept as a deprecated alias.
+
+Bias the recogniser toward names, jargon, or a domain glossary with
+`--prompt "free text hint"` and `--words word1 word2 ...` (each also
+accepts a `--prompt-file` / `--words-file` companion). See
+[docs/backends.md › Vocabulary biasing](docs/backends.md#vocabulary-biasing)
+for what each backend does with them.
+
+
+## Backends at a glance
+
+| Backend         | `--backend` | Default model              | Streaming model(s)        | Requires                            |
+|-----------------|-------------|----------------------------|---------------------------|-------------------------------------|
+| Groq (cloud)    | `groq`      | `whisper-large-v3-turbo`   | —                         | `GROQ_API_KEY`                      |
+| OpenAI (cloud)  | `openai`    | `gpt-4o-mini-transcribe`   | `gpt-realtime-whisper`    | `OPENAI_API_KEY`                    |
+| Whisper (local) | `whisper`   | `small`                    | —                         | `pip install scribe-cli[whisper]`   |
+| Vosk (local)    | `vosk`      | language-dependent         | all Vosk models           | `pip install scribe-cli[vosk]`      |
+
+Whether a transcription appears live as you speak or all at once when
+you stop depends on the **model** picked — see
+[docs/backends.md](docs/backends.md).
+
+
+### Getting an API key
+
+Groq is a good cloud backend to start with — very fast, quite accurate, and the
+**free tier** is generous enough for everyday dictation. Sign up at
+[console.groq.com](https://console.groq.com/), create an API key
+under **Settings → API Keys**, and export it as `GROQ_API_KEY`.
+
+I personally use [OpenAI](https://openai.com/api/) with `gpt-4o-mini-transcribe` as it is also fast and perhaps more accurate for my accent-tainted English.
+
+
+## Documentation
+
+- [Installation & dependencies](docs/installation.md) — PortAudio,
+  extras, Ubuntu / GNOME tray libs.
+- [Backends in detail](docs/backends.md) — model lists, when to pick
+  which, the realtime model.
+- [Keyboard modes & typer backends](docs/keyboard.md) — keystroke vs
+  clipboard, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](docs/tray.md) — menu tree, icon
+  states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart (`scribe-install`)](docs/desktop-install.md)
+  — GNOME / KDE launcher integration.
+- [Fine tuning & CLI reference](docs/cli.md) — every `scribe --help`
+  flag with examples.
+
+## Compatibility
+
+Initially developed for Python 3 on Ubuntu 24.04 (GNOME + Wayland);
+works on macOS and Windows too. Wayland keystroke injection is
+convoluted but [solved](docs/keyboard.md). For dependencies of
+individual subsystems, check `pynput` (keyboard) and `pystray` (tray
+icon).

scribe_cli-0.17.0/docs/backends.md

@@ -0,0 +1,204 @@
+# Backends in detail
+
+Scribe ships five speech-to-text backends. They are all picked through
+the same `--backend` / `--model` CLI flags (or the **Model** submenu in
+the tray / terminal frontend). Whether a transcription is *streaming*
+(text appears live as you speak) or *batch* (text arrives at end of
+recording) depends on the **model** chosen — not the backend.
+
+## At a glance
+
+| Backend                | `--backend`     | Default model              | Streaming model(s)        | Requires                                |
+|------------------------|-----------------|----------------------------|---------------------------|-----------------------------------------|
+| Groq (cloud)           | `groq`          | `whisper-large-v3-turbo`   | —                         | `GROQ_API_KEY`                          |
+| OpenAI (cloud)         | `openai`        | `gpt-4o-mini-transcribe`   | `gpt-realtime-whisper`    | `OPENAI_API_KEY`                        |
+| Whisper FUTO (local)   | `whisper-futo`  | `small`                    | —                         | `pip install scribe-cli[whisper-futo]`  |
+| Whisper (local)        | `whisper`       | `small`                    | —                         | `pip install scribe-cli[whisper]`       |
+| Vosk (local)           | `vosk`          | language-dependent         | all Vosk models           | `pip install scribe-cli[vosk]`          |
+
+Run `scribe` without arguments and it picks the first backend whose
+dependency / API key is present, preferring cloud over local and the
+faster local option first:
+`groq → openai → whisper-futo → whisper → vosk`.
+
+## `whisper-futo` (local, fast on short dictations)
+
+Runs locally via [whisper.cpp](https://github.com/ggml-org/whisper.cpp)
+(through [`pywhispercpp`](https://github.com/absadiki/pywhispercpp))
+using [FUTO's ACFT-finetuned models](https://github.com/futo-org/whisper-acft).
+ACFT (Audio Context Fine-Tuning) lets the encoder run on the actual
+audio length instead of always padding to 30 s — a meaningful speedup
+on short dictations, which is the typical scribe workload.
+
+The available models offered in the tray menu are
+`tiny / base / small`. FUTO has not released ACFT weights for
+`medium / large / turbo`; for those sizes use the `whisper` backend.
+
+With `--language en` (or `-l en`) scribe auto-substitutes the
+English-only variant (e.g. `small` → `small.en`) when it exists.
+
+Models are auto-downloaded on first use from `voiceinput.futo.org`
+to `$XDG_CACHE_HOME/whisper-futo/` (override with
+`--download-folder-whisper-futo`).
+
+For audio ≥ 30 s the ACFT speedup tapers off and the encoder window
+collapses to the standard 30 s; quality and speed in that regime are
+similar to the `whisper` backend. Pick `whisper-futo` if most of your
+dictations are short, the `whisper` backend if you regularly do
+multi-minute recordings or need `medium` / `large` / `turbo`.
+
+## `whisper` (local)
+
+Runs locally via
+[`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) and
+defaults to the `small` model. Excellent at full-utterance
+transcription in
+[many languages](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages),
+but it does not stream — text appears at end-of-recording — and
+execution time depends on model size and hardware.
+
+The available models offered in the tray menu are
+`tiny / base / small / medium / large-v3 / large-v3-turbo`. Larger
+models trade speed for accuracy.
+
+With `--language en` (or `-l en`) scribe auto-substitutes the
+English-only variant (e.g. `small` → `small.en`) when it exists.
+
+## `vosk` (local, streaming)
+
+Vosk transcribes in real time and is very good at one language at a
+time, but tends to make more mistakes than Whisper and does not produce
+punctuation. It becomes really useful in longer, interactive sessions
+where the live "appears as you speak" UX matters — see
+[keyboard.md](keyboard.md) for how the keystroke mode interacts with
+streaming models.
+
+There are many [Vosk models](https://alphacephei.com/vosk/models)
+available; a handful are pre-mapped to common languages (`en`, `fr`,
+`de`, `it`) in
+[`scribe/models.toml`](../scribe/models.toml). Pick one with
+`-l <lang>` or browse the full list interactively from the menu.
+
+## `openai` (OpenAI cloud)
+
+The OpenAI backend supports three models:
+
+- `gpt-4o-mini-transcribe` *(default)* — fast, low-cost batch
+  transcription.
+- `gpt-4o-transcribe` — higher-quality batch transcription.
+- `gpt-realtime-whisper` *(streaming)* — partial transcripts arrive
+  as you speak. Same UX as Vosk but using OpenAI's cloud model.
+
+All three share the same `OPENAI_API_KEY` and the `[openai]` extra; no
+extra dependencies. Set the key once:
+
+```bash
+export OPENAI_API_KEY=YOURAPIKEY
+scribe --backend openai                          # default: gpt-4o-mini-transcribe
+scribe --model gpt-4o-transcribe                 # batch, higher quality
+scribe --model gpt-realtime-whisper              # streaming
+```
+
+`--model` alone auto-routes to the `openai` backend for any of the
+three models above, so `--backend openai` is optional.
+
+### `--realtime-delay` (gpt-realtime-whisper only)
+
+The streaming model has a latency-vs-accuracy knob exposed as
+`--realtime-delay {minimal,low,medium,high,xhigh}` (default `medium`).
+Lower values emit partial transcripts sooner — at the cost of more
+revisions arriving in the focused window. Higher values batch tokens
+into longer chunks so what gets pasted is more stable.
+
+See OpenAI's
+[gpt-realtime-whisper model card](https://developers.openai.com/api/docs/models/gpt-realtime-whisper)
+for the full picture.
+
+## `groq` (Groq cloud)
+
+Talks to Groq's OpenAI-compatible API and defaults to
+`whisper-large-v3-turbo`. Typically the fastest cloud option for
+full-utterance transcription:
+
+```bash
+export GROQ_API_KEY=YOURAPIKEY
+scribe --backend groq
+```
+
+The `groq` backend reuses the `openai` Python client under the hood, so
+installing `[openai]` is enough for both.
+
+## Stopping a recording
+
+For batch models (Whisper local, Whisper-via-API, Groq, `gpt-4o-*`) the
+recording continues for up to 2 minutes until you stop it manually
+(Stop in the tray, Ctrl+C in the terminal) — the transcription happens
+once when you stop.
+
+Streaming models (Vosk, `gpt-realtime-whisper`) emit partials as you
+speak and stop on the same Stop / Ctrl+C action.
+
+## Vocabulary biasing
+
+`--prompt TEXT` and `--words W [W ...]` (plus the `--prompt-file` /
+`--words-file` companions) bias the recogniser toward a particular
+style, domain, or word list. The concept is generic across the
+whisper-family backends but each backend exposes it slightly
+differently:
+
+| Backend                              | `--prompt`                    | `--words`                                              |
+|--------------------------------------|-------------------------------|--------------------------------------------------------|
+| `whisper` (faster-whisper, local)    | passed as `initial_prompt=`   | passed as `hotwords=` — a **dedicated biasing channel** separate from the prompt |
+| `openai` batch (`gpt-4o*-transcribe`) | passed as `prompt=`           | joined onto the prompt string                          |
+| `groq` (`whisper-large-v3-turbo`)     | passed as `prompt=`           | joined onto the prompt string                          |
+| `openai` realtime (`gpt-realtime-whisper`) | included in the session config as `transcription.prompt` | joined onto the prompt string |
+| `vosk`                               | *ignored* (no soft prompt)    | *ignored* (Vosk only supports a hard `grammar` allowlist; not yet exposed) |
+
+The whisper-family APIs cap the prompt around ~224 tokens; longer
+hints are silently truncated. Faster-whisper's `hotwords` channel is
+the one place a separate "dictionary" really exists — everywhere else
+`--words` is just a convenience to keep your word list out of the
+prompt string in the CLI.
+
+Both flags read from the corresponding `*-file` argument when present.
+Inline + file inputs are combined.
+
+```bash
+# Inline
+scribe --prompt "ML systems infra: K8s, etcd, Envoy." \
+       --words kubectl envoyproxy etcdctl
+
+# From files (handy for long-lived glossaries)
+scribe --prompt-file ~/.config/scribe/prompt.txt \
+       --words-file  ~/.config/scribe/words.txt
+```
+
+When *no* prompt/words flag is given, scribe also auto-loads
+`prompt.txt` and `words.txt` from the platform user-config dir
+(`~/.config/scribe/` on Linux, `~/Library/Application Support/scribe/`
+on macOS, `%LOCALAPPDATA%\scribe\` on Windows — resolved via
+`platformdirs`) if they exist. To suppress the default for one
+invocation, pass an explicit empty value: `--prompt ""` (or
+`--prompt-file ""`) suppresses the prompt default; `--words` with no
+arguments (or `--words-file ""`) suppresses the words default. Each
+side is independent.
+
+## Pseudo-streaming (experimental)
+
+`--pseudo-streaming` makes a batch backend behave streaming-like by
+cutting the running buffer into chunks driven by silence:
+
+```bash
+scribe --pseudo-streaming --streaming-window 5
+```
+
+After `--streaming-window` seconds of buffered audio, scribe cuts at
+the first silence of at least `--silence-duration` and transcribes the
+chunk; if no silence arrives by `2 × --streaming-window`, it
+force-cuts. The session continues until you stop it. Default `5` s
+trades a little Whisper context for snappier "text appears as you
+speak" UX; raise it (10–30 s) if accuracy on long sentences matters
+more than latency.
+
+This is experimental and off by default. The tray menu surfaces the
+same toggle under Options ▶ Advanced ▶ Pseudo-streaming.