scribe-cli 0.16.0__tar.gz → 0.17.1__tar.gz

{scribe_cli-0.16.0 → scribe_cli-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scribe-cli
-Version: 0.16.0
+Version: 0.17.1
 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
@@ -50,11 +50,14 @@ 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
@@ -69,6 +72,7 @@ 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"
@@ -98,29 +102,60 @@ cloud-based APIs, batch and streaming workflows.
 - Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows;
   works under Termux for clipboard / terminal output.
 
-## Getting started
+## 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
 ```
 
-Scribe picks the first backend whose key / dependency is present, in
-order **`groq` → `openai` → `whisper` → `vosk`**, and launches the
-tray icon. Press Record, speak, press Stop.
+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:
 
-See documentation below for setting up keyboard input on Ubuntu Wayland.
+```bash
+scribe --backend groq --model whisper-large-v3-turbo
+```
 
-### Getting an API key
+<img src=https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png width=300px>
 
-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`.
+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.
 
-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.
 
 ## Backends at a glance
 
@@ -135,6 +170,17 @@ 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,

{scribe_cli-0.16.0 → scribe_cli-0.17.1}/README.md

@@ -21,29 +21,60 @@ cloud-based APIs, batch and streaming workflows.
 - Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows;
   works under Termux for clipboard / terminal output.
 
-## Getting started
+## 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
 ```
 
-Scribe picks the first backend whose key / dependency is present, in
-order **`groq` → `openai` → `whisper` → `vosk`**, and launches the
-tray icon. Press Record, speak, press Stop.
+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:
 
-See documentation below for setting up keyboard input on Ubuntu Wayland.
+```bash
+scribe --backend groq --model whisper-large-v3-turbo
+```
 
-### Getting an API key
+<img src=https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png width=300px>
 
-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`.
+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.
 
-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.
 
 ## Backends at a glance
 
@@ -58,6 +89,17 @@ 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,

scribe_cli-0.17.1/docs/backends.md

@@ -0,0 +1,238 @@
+# 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 |
+| `whisper-futo` (pywhispercpp, local) | passed as `initial_prompt=`   | joined onto the prompt string (no separate hotwords channel here) |
+| `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`) | *silently ignored* — the model rejects the prompt parameter server-side (HTTP 400 *"The 'prompt' parameter is not supported for this model."*). The kwarg stays accepted for plumbing compatibility but never reaches the API. | same — joined into the (ignored) prompt |
+| `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.
+
+### Cross-chunk prompt context
+
+In pseudo-streaming mode scribe automatically augments each chunk's
+prompt with the trailing ~200 characters of the *previous* chunk's
+transcription. This rolling tail is concatenated onto whatever static
+`--prompt` / `--words` you configured and reaches the backend through
+the same channel as the static prompt (the vocabulary biasing table
+above). The motivation is cross-chunk continuity:
+
+- **Capitalization drift** — without context, a chunk that starts
+  right after a period might come back lowercased.
+- **Article gender (FR/IT/ES/…)** — `"la nouveau"` → `"le nouveau"`
+  once the prior chunk has established the noun.
+- **Language lock** — `whisper.cpp` auto-detects language per call;
+  feeding the previous chunk's tokens keeps the language stable
+  across cuts.
+
+Whisper's prompt window is capped at ~224 tokens; 200 chars of French
+sits well under that and leaves room for your static prompt + words
+list.
+
+The rolling tail is **dropped** whenever the pause that triggered the
+chunk cut exceeded 1.5 seconds — a long pause is treated as a new
+sentence/idea boundary, where carrying a possibly-bad prior chunk
+forward biases the next one more than it helps. This mirrors
+`whisper.cpp`'s `--keep-context off` default: prior-text conditioning
+can self-reinforce errors (hallucinations, decoder repetition loops)
+more readily than it provides useful continuity, so we cap it at
+natural sentence boundaries.
+
+Short pauses (mid-sentence punctuation) keep the context; the cut at
+the start of every new recording also clears it.

scribe_cli-0.17.1/docs/cli.md

@@ -0,0 +1,137 @@
+# Fine tuning & CLI reference
+
+For a complete, always-current listing run:
+
+```bash
+scribe --help
+```
+
+The flags are grouped to mirror the source-of-truth in
+[`scribe/app.py`](../scribe/app.py).
+
+## Backend
+
+| Flag                            | Purpose                                                                 |
+|---------------------------------|-------------------------------------------------------------------------|
+| `--backend {vosk,whisper,openai,groq}` | Speech-recognition backend (prompted if omitted).                |
+| `--model NAME`                  | Model name for the chosen backend. Auto-routes to the right backend for known model names (e.g. `--model gpt-realtime-whisper` selects `openai`). |
+| `-l, --language LANG`           | Language alias selecting a preset Vosk model (`en`/`fr`/`de`/`it`), or `en` for English-only Whisper models. |
+| `--download-folder-whisper DIR` | Folder to store Whisper models.                                         |
+| `--download-folder-vosk DIR`    | Folder to store Vosk models.                                            |
+
+## Prompting & vocabulary biasing
+
+Bias the model toward particular names, jargon, or topics. Two
+complementary knobs:
+
+| Flag                     | Purpose                                                                                          |
+|--------------------------|--------------------------------------------------------------------------------------------------|
+| `--prompt TEXT`          | Free-text style / context hint shown to the model.                                               |
+| `--prompt-file PATH`     | Reads the prompt from a file; appended to `--prompt` if both are given.                          |
+| `--words W [W ...]`      | List of words to emphasise. Joined onto the prompt for cloud Whisper; routed to faster-whisper's dedicated `hotwords` channel locally. |
+| `--words-file PATH`      | Whitespace-separated words from a file; merged with `--words`.                                   |
+
+The whisper-family APIs cap the prompt around ~224 tokens; longer hints
+are silently truncated. Vosk has no soft prompt and ignores both flags.
+See [backends.md › Vocabulary biasing](backends.md#vocabulary-biasing)
+for the per-backend wiring.
+
+**Default files.** When none of the four flags above are given, scribe
+also looks for `prompt.txt` and `words.txt` in the platform user-config
+dir and loads them if they exist — handy for a long-lived personal
+glossary. The path is resolved via `platformdirs`:
+
+- Linux: `$XDG_CONFIG_HOME/scribe/` (default `~/.config/scribe/`)
+- macOS: `~/Library/Application Support/scribe/`
+- Windows: `%LOCALAPPDATA%\scribe\`
+
+To suppress the default on a single invocation, pass an empty value:
+`--prompt ""`, `--prompt-file ""`, or `--words` with no arguments. Each
+flag suppresses only its own side (giving `--prompt ""` still loads
+`words.txt` if present).
+
+## Audio
+
+| Flag                  | Purpose                                                  |
+|-----------------------|----------------------------------------------------------|
+| `--input-device N`    | Microphone device index (see `python -m sounddevice`).   |
+
+## Output
+
+| Flag                        | Purpose                                                                                     |
+|-----------------------------|---------------------------------------------------------------------------------------------|
+| `-m, --mode {keystroke,clipboard,terminal}` | Where transcribed text goes (default `keystroke`). See [keyboard.md](keyboard.md). |
+| `--typer {auto,eitype,pynput,wtype,ydotool}` | Keystroke-injection backend (default `auto`).                                |
+| `--type-direct`             | In keystroke mode, type the transcription as keystrokes instead of synthesising Ctrl+V.     |
+| `-o, --output-file FILE`    | Also append the transcription to this file.                                                 |
+
+## Silence detection (shared)
+
+| Flag                       | Default | Purpose                                                                |
+|----------------------------|---------|------------------------------------------------------------------------|
+| `--duration SECS`          | `120`   | Max recording duration in seconds.                                     |
+| `--silence-db DB`          | `-40`   | dBFS volume floor for "this frame is silent". Used by every silence-driven behavior. |
+| `--silence-duration SECS`  | `0.6`   | How long silence must persist before triggering a backend's silence behavior (realtime auto-commit, pseudo-streaming cut). |
+
+## Realtime (`gpt-realtime-whisper`)
+
+| Flag                                              | Default  | Purpose                                                                                                                                                                                  |
+|---------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--realtime-delay {minimal,low,medium,high,xhigh}` | `medium` | Trade off latency vs accuracy on `gpt-realtime-whisper`. Lower = faster partials but more paste churn in the focused window.                                                             |
+| `--realtime-gate` / `--no-realtime-gate`          | on       | Drop silent frames (per `--silence-db`) before sending them over the WebSocket so silent audio isn't billed as input tokens. After `--silence-duration` of silence, also commit mid-session so trailing words flush live. |
+
+Streaming models (Vosk, `gpt-realtime-whisper`) ignore the batch
+silence-chunking knobs; they have their own end-of-utterance signal.
+
+## Frontend
+
+| Flag                        | Purpose                                                              |
+|-----------------------------|----------------------------------------------------------------------|
+| `--frontend {tray,terminal}` | UI to launch (default `tray`).                                       |
+| `--no-interactive`          | In terminal mode, skip the interactive menu and record immediately. (`--no-prompt` is kept as a deprecated alias.) |
+| `--vosk-models M [M ...]`   | Vosk models offered in the tray menu.                                |
+| `--whisper-models M [M ...]` | Whisper models offered in the tray menu.                             |
+
+## Examples
+
+Predefine the tray menu's Whisper / Vosk model lists:
+
+```bash
+scribe --vosk-models vosk-model-fr-0.22 \
+       --whisper-models small large-v3-turbo
+```
+
+Stream OpenAI realtime transcripts with the most aggressive latency
+setting:
+
+```bash
+scribe --model gpt-realtime-whisper --realtime-delay minimal
+```
+
+Disable the realtime silence gate (e.g. to A/B against a noisy
+environment) — you'll pay for silent audio while the session is open:
+
+```bash
+scribe --model gpt-realtime-whisper --no-realtime-gate
+```
+
+Run scribe headlessly into a file without touching the clipboard or
+focused window:
+
+```bash
+scribe --frontend terminal --no-interactive --mode terminal -o session.txt
+```
+
+Bias the recogniser toward domain jargon (medical terms, proper names):
+
+```bash
+scribe --prompt "Patient notes from a cardiology consult." \
+       --words tachycardia bradycardia echocardiogram metoprolol
+```
+
+Or store the lists in files for reuse across sessions:
+
+```bash
+scribe --prompt-file ~/.config/scribe/prompt.txt \
+       --words-file  ~/.config/scribe/words.txt
+```

{scribe_cli-0.16.0 → scribe_cli-0.17.1}/docs/keyboard.md

@@ -167,3 +167,34 @@ If `eitype` is unavailable, two older workarounds also work:
 Roadmap for native libei integration (eventual Python bindings,
 expanded compositor support) is tracked in
 [docs/roadmap-libei.md](roadmap-libei.md).
+
+## Realtime backend: delta coalescing
+
+The `gpt-realtime-whisper` backend emits one transcription delta per
+word/subword at ~30–80 ms intervals — much faster than the
+`pyperclip.copy()` + Ctrl+V cycle can settle on Wayland (≥100 ms,
+because `wl-copy` is asynchronous). Pasting every delta led to
+clipboard races where successive copies overwrote each other before
+Ctrl+V landed, manifesting as dropped and duplicated words
+(*"fait fait le mot mot time time…"*).
+
+In **paste mode** (default keystroke output) scribe therefore
+coalesces deltas: incoming tokens accumulate into a small buffer and
+are flushed only when *either* ~400 ms have elapsed since the last
+flush, *or* the buffer ends on sentence-final punctuation
+(`. ! ? \n`). A 200 ms floor between any two flushes prevents
+back-to-back punctuation flushes from racing each other through the
+clipboard.
+
+With **`--type-direct`** the coalescing is bypassed entirely — each
+delta goes through the chosen typer as a raw keystroke synchronously
+(uinput / xtest / portal libei), no clipboard involved, no race to
+defeat. The UX is also snappier: tokens appear one at a time rather
+than in ~400 ms-cadenced bursts.
+
+macOS and Windows clipboards are synchronous, so the race that
+motivates coalescing is essentially a Wayland artefact; scribe still
+coalesces in paste mode there for consistency, but it's harmless.
+This whole behaviour is realtime-specific — Vosk's per-phrase commits
+already arrive at a sane cadence, and the pseudo-streaming backends
+emit one chunk per silence cut (already coarse enough).

{scribe_cli-0.16.0 → scribe_cli-0.17.1}/docs/tray.md

@@ -58,8 +58,10 @@ Options ▶
     Keyboard backend ▶            eitype / pynput / ydotool / wtype
                                   (rows incompatible with this OS are hidden;
                                    submenu hidden entirely when ≤ 1 row left)
-    Advanced ▶                    auto-restart after silence, duration,
-                                    silence threshold, output file
+    Advanced ▶                    silence duration, silence threshold,
+                                    realtime gate, pseudo-streaming
+                                    [experimental], streaming window
+                                    [experimental], output file
 Quit
 ```
 

{scribe_cli-0.16.0 → scribe_cli-0.17.1}/pyproject.toml

@@ -20,6 +20,7 @@ dependencies = [
     "pyperclip",
     "unidecode",
     "termcolor",
+    "platformdirs",
     "desktop-ai-core>=0.2.0",
 ]
 
@@ -61,11 +62,12 @@ keywords = [
 [project.optional-dependencies]
 keyboard = ["pynput"]
 whisper = ["faster-whisper"]
+whisper-futo = ["pywhispercpp"]
 vosk = ["vosk"]
 app = ["pystray", "PyGObject"]
 openai = ["openai>=2.37.0,<3", "soundfile"]
 groq = ["openai>=2.37.0,<3", "soundfile"]
-all = ["pynput", "faster-whisper", "openai>=2.37.0,<3", "soundfile", "vosk", "pystray"]
+all = ["pynput", "faster-whisper", "pywhispercpp", "openai>=2.37.0,<3", "soundfile", "vosk", "pystray"]
 
 
 [tool.setuptools]