scribe-cli 1.1.1__tar.gz → 1.2.0__tar.gz

scribe_cli-1.2.0/.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Cache mkdocs-material assets
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ github.sha }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install .[docs]
+      - run: mkdocs gh-deploy --force

scribe_cli-1.2.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: scribe-cli
+Version: 1.2.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
+Project-URL: Source, https://github.com/perrette/scribe
+Project-URL: Issues, https://github.com/perrette/scribe/issues
+Project-URL: Documentation, https://perrette.github.io/scribe/
+Project-URL: Changelog, https://github.com/perrette/scribe/releases
+Project-URL: Funding, https://github.com/sponsors/perrette
+Keywords: speech-to-text,stt,transcription,dictation,voice-typing,voice-recognition,multilingual,realtime,streaming,cli,tray,vosk,whisper,faster-whisper,openai,groq,gpt-4o,linux,wayland,keyboard,clipboard,microphone,audio
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Environment :: Console
+Classifier: Environment :: X11 Applications
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Natural Language :: English
+Classifier: Natural Language :: French
+Classifier: Natural Language :: German
+Classifier: Natural Language :: Italian
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Utilities
+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.3.1
+Requires-Dist: onnxruntime
+Requires-Dist: pynput
+Requires-Dist: pystray
+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: PyGObject; sys_platform == "linux" and 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: vad
+Provides-Extra: all
+Requires-Dist: faster-whisper; extra == "all"
+Requires-Dist: openai<3,>=2.37.0; extra == "all"
+Requires-Dist: soundfile; extra == "all"
+Requires-Dist: vosk; extra == "all"
+Requires-Dist: PyGObject; sys_platform == "linux" and extra == "all"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin>=6.0; extra == "docs"
+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)
+[![docs](https://img.shields.io/badge/docs-perrette.github.io%2Fscribe-blue)](https://perrette.github.io/scribe/)
+
+# Scribe  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" width="48">
+
+Scribe is a speech-to-text CLI and tray app that pipes transcribed text
+into the focused window. It supports local and cloud-based APIs, batch and
+streaming workflows.
+
+<!-- intro-start -->
+- **Five backends, one interface.** Records from your mic and transcribes via
+  **Vosk** (local, streaming), **Whisper** (local, batch), **Whisper FUTO**
+  (local, batch — ACFT-tuned for short dictations), **OpenAI** (cloud, batch
+  *or* streaming), or **Groq** (cloud, batch).
+- **Four ways to deliver the transcript.** Paste into the focused window
+  (default), copy to the clipboard, print to the terminal, or append to a file.
+- **Tray or terminal.** Runs as a **system tray icon** with a single Record
+  button, or as an interactive **terminal TUI** — same menu in both.
+- **Hotkey-friendly.** Hooks into your desktop's keyboard shortcuts via
+  `SIGUSR1` (toggle recording) and `SIGUSR2` (cancel), plus built-in global
+  hotkeys on X11 / Windows.
+- **Cross-platform.** Tested on Ubuntu (X11 and Wayland), macOS, and Windows;
+  works under Termux for clipboard / terminal output.
+<!-- intro-end -->
+
+<img src=https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png width=300px>
+
+## Installation
+
+**Linux / macOS:**
+
+```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
+```
+
+**Windows** (PowerShell) — no system packages needed; `sounddevice` bundles
+PortAudio and the clipboard is native, so skip the `apt`/`brew` step:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1          # if blocked: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+pip install scribe-cli[whisper]        # local Whisper; or [all], or a cloud backend
+$env:GROQ_API_KEY = "YOURAPIKEY"        # or OPENAI_API_KEY, or skip and run local
+```
+
+See the [installation page](https://perrette.github.io/scribe/installation/)
+for the full per-platform walkthrough (extras, Ubuntu / GNOME tray libs, the
+Windows quickstart).
+
+## Quickstart
+
+```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-futo` →
+`whisper` → `vosk`**. Override the defaults or drop the tray entirely:
+
+```bash
+scribe --backend whisper --model small   # local, no API key
+scribe --frontend terminal               # interactive TUI menu
+scribe --mode clipboard                  # copy to clipboard, no keystroke
+```
+
+See the [quickstart](https://perrette.github.io/scribe/quickstart/) for more.
+
+## Documentation
+
+Full documentation lives at **<https://perrette.github.io/scribe/>**:
+
+- [Installation & dependencies](https://perrette.github.io/scribe/installation/)
+  — PortAudio, extras, Ubuntu / GNOME tray libs, Windows.
+- [Quickstart](https://perrette.github.io/scribe/quickstart/) — your first
+  dictation.
+- [Backends in detail](https://perrette.github.io/scribe/backends/) — model
+  lists, streaming recipes, vocabulary biasing, the realtime model.
+- [Output modes & typer backends](https://perrette.github.io/scribe/output/) —
+  keystroke vs clipboard, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](https://perrette.github.io/scribe/tray/) —
+  menu tree, icon states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart (`scribe-install`)](https://perrette.github.io/scribe/desktop-install/)
+  — GNOME / KDE launcher integration.
+- [Fine tuning & CLI reference](https://perrette.github.io/scribe/cli/) — every
+  `scribe --help` flag with examples.
+
+## From the same author
+
+A few other open-source tools I maintain.
+
+**Scientific writing & data**
+
+- [**texmark**](https://perrette.github.io/texmark/) — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
+- [**papers**](https://perrette.github.io/papers/) — command-line BibTeX bibliography and PDF library manager.
+- [**datamanifest**](https://perrette.github.io/datamanifest/) — declarative, reproducible dataset management. *(See also the [datamanifest.toml](https://perrette.github.io/datamanifest.toml/) format spec and the [DataManifest.jl](https://awi-esc.github.io/DataManifest.jl/) Julia port.)*
+
+**Speech to Text (dictate) and Text to Speech (read-aloud) tools**
+
+- [**bard**](https://perrette.github.io/bard/) — text-to-speech reader.
+
+## Compatibility
+
+| OS                 | Status                                                              |
+|--------------------|---------------------------------------------------------------------|
+| Ubuntu 24.04       | Primary dev platform (GNOME, X11 and Wayland).                      |
+| macOS              | Works.                                                              |
+| Windows 11         | Tested and working on Python 3.14 (64-bit / `win_amd64`). Dependencies resolve pre-built wheels; no C toolchain or Python downgrade needed. |
+
+Wayland keystroke injection is convoluted but
+[solved](https://perrette.github.io/scribe/output/).

scribe_cli-1.2.0/README.md

@@ -0,0 +1,114 @@
+[![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)
+[![docs](https://img.shields.io/badge/docs-perrette.github.io%2Fscribe-blue)](https://perrette.github.io/scribe/)
+
+# Scribe  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" width="48">
+
+Scribe is a speech-to-text CLI and tray app that pipes transcribed text
+into the focused window. It supports local and cloud-based APIs, batch and
+streaming workflows.
+
+<!-- intro-start -->
+- **Five backends, one interface.** Records from your mic and transcribes via
+  **Vosk** (local, streaming), **Whisper** (local, batch), **Whisper FUTO**
+  (local, batch — ACFT-tuned for short dictations), **OpenAI** (cloud, batch
+  *or* streaming), or **Groq** (cloud, batch).
+- **Four ways to deliver the transcript.** Paste into the focused window
+  (default), copy to the clipboard, print to the terminal, or append to a file.
+- **Tray or terminal.** Runs as a **system tray icon** with a single Record
+  button, or as an interactive **terminal TUI** — same menu in both.
+- **Hotkey-friendly.** Hooks into your desktop's keyboard shortcuts via
+  `SIGUSR1` (toggle recording) and `SIGUSR2` (cancel), plus built-in global
+  hotkeys on X11 / Windows.
+- **Cross-platform.** Tested on Ubuntu (X11 and Wayland), macOS, and Windows;
+  works under Termux for clipboard / terminal output.
+<!-- intro-end -->
+
+<img src=https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png width=300px>
+
+## Installation
+
+**Linux / macOS:**
+
+```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
+```
+
+**Windows** (PowerShell) — no system packages needed; `sounddevice` bundles
+PortAudio and the clipboard is native, so skip the `apt`/`brew` step:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1          # if blocked: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+pip install scribe-cli[whisper]        # local Whisper; or [all], or a cloud backend
+$env:GROQ_API_KEY = "YOURAPIKEY"        # or OPENAI_API_KEY, or skip and run local
+```
+
+See the [installation page](https://perrette.github.io/scribe/installation/)
+for the full per-platform walkthrough (extras, Ubuntu / GNOME tray libs, the
+Windows quickstart).
+
+## Quickstart
+
+```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-futo` →
+`whisper` → `vosk`**. Override the defaults or drop the tray entirely:
+
+```bash
+scribe --backend whisper --model small   # local, no API key
+scribe --frontend terminal               # interactive TUI menu
+scribe --mode clipboard                  # copy to clipboard, no keystroke
+```
+
+See the [quickstart](https://perrette.github.io/scribe/quickstart/) for more.
+
+## Documentation
+
+Full documentation lives at **<https://perrette.github.io/scribe/>**:
+
+- [Installation & dependencies](https://perrette.github.io/scribe/installation/)
+  — PortAudio, extras, Ubuntu / GNOME tray libs, Windows.
+- [Quickstart](https://perrette.github.io/scribe/quickstart/) — your first
+  dictation.
+- [Backends in detail](https://perrette.github.io/scribe/backends/) — model
+  lists, streaming recipes, vocabulary biasing, the realtime model.
+- [Output modes & typer backends](https://perrette.github.io/scribe/output/) —
+  keystroke vs clipboard, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](https://perrette.github.io/scribe/tray/) —
+  menu tree, icon states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart (`scribe-install`)](https://perrette.github.io/scribe/desktop-install/)
+  — GNOME / KDE launcher integration.
+- [Fine tuning & CLI reference](https://perrette.github.io/scribe/cli/) — every
+  `scribe --help` flag with examples.
+
+## From the same author
+
+A few other open-source tools I maintain.
+
+**Scientific writing & data**
+
+- [**texmark**](https://perrette.github.io/texmark/) — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
+- [**papers**](https://perrette.github.io/papers/) — command-line BibTeX bibliography and PDF library manager.
+- [**datamanifest**](https://perrette.github.io/datamanifest/) — declarative, reproducible dataset management. *(See also the [datamanifest.toml](https://perrette.github.io/datamanifest.toml/) format spec and the [DataManifest.jl](https://awi-esc.github.io/DataManifest.jl/) Julia port.)*
+
+**Speech to Text (dictate) and Text to Speech (read-aloud) tools**
+
+- [**bard**](https://perrette.github.io/bard/) — text-to-speech reader.
+
+## Compatibility
+
+| OS                 | Status                                                              |
+|--------------------|---------------------------------------------------------------------|
+| Ubuntu 24.04       | Primary dev platform (GNOME, X11 and Wayland).                      |
+| macOS              | Works.                                                              |
+| Windows 11         | Tested and working on Python 3.14 (64-bit / `win_amd64`). Dependencies resolve pre-built wheels; no C toolchain or Python downgrade needed. |
+
+Wayland keystroke injection is convoluted but
+[solved](https://perrette.github.io/scribe/output/).

{scribe_cli-1.1.1 → scribe_cli-1.2.0}/docs/backends.md

@@ -76,7 +76,7 @@ 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
+[`scribe/models.toml`](https://github.com/perrette/scribe/blob/main/scribe/models.toml). Pick one with
 `-l <lang>` or browse the full list interactively from the menu.
 
 ## `openai` (OpenAI cloud)
@@ -134,9 +134,12 @@ 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.
+recording continues until you stop it manually (Stop in the tray,
+Ctrl+C in the terminal), with a safety stop after `--clip-timeout`
+seconds (10 minutes by default) — the transcription happens once when
+you stop. Silent pauses are capped at `--clip-max-silence` seconds
+(2 by default) in the audio sent for transcription, so dead air does
+not count toward what the cloud APIs bill by duration.
 
 Streaming models (Vosk, `gpt-realtime-whisper`) emit partials as you
 speak and stop on the same Stop / Ctrl+C action.
@@ -230,7 +233,7 @@ column in the table above):
   multilingual coverage for English accuracy.
 - **Vosk** — language isn't a runtime parameter; vosk ships a
   separate model per language. `-l fr` looks up the vosk model
-  pre-mapped to French in [`scribe/models.toml`](../scribe/models.toml)
+  pre-mapped to French in [`scribe/models.toml`](https://github.com/perrette/scribe/blob/main/scribe/models.toml)
   and instantiates that one. Vosk has no auto-detect path, so the
   Language menu's `Auto` entry on vosk falls back to a sensible
   default — the tray shows `Auto (🇬🇧 en)` to make this explicit

{scribe_cli-1.1.1 → scribe_cli-1.2.0}/docs/cli.md

@@ -7,7 +7,7 @@ scribe --help
 ```
 
 The flags are grouped to mirror the source-of-truth in
-[`scribe/app.py`](../scribe/app.py).
+[`scribe/app.py`](https://github.com/perrette/scribe/blob/main/scribe/app.py).
 
 ## Backend
 
@@ -124,7 +124,8 @@ silence-chunking knobs; they have their own end-of-utterance signal.
 | `--stream-first-chunk-min SECS`   | `3.0`   | Minimum chunk size for the *first* chunk of a streaming thread (default `3.0`). Higher than `--stream-chunk-min` so the bootstrap chunk has enough audio for Whisper to produce a punctuated transcript whose tail seeds the rolling prompt for the rest. Applies on recording start and right after a context-reset silence. Inactive when `--stream-context-length 0`. Clamped to `≤ --stream-chunk-max`. Set equal to `--stream-chunk-min` to disable. |
 | `--stream-chunk-silence-break SECS` | `0.6` | Silence duration that triggers a chunk cut (default `0.6`). Special value `0` enables Auto mode (best-silence-in-window at force-cut time). |
 | `--stream-context-reset-silence X` | `3.0`  | Multiplier of `--stream-chunk-silence-break` above which the rolling cross-chunk prompt context is discarded (default `3.0`, i.e. 1.8 s at default silence-break). Use `inf` to never reset. |
-| `--clip-timeout SECS`             | `120`   | Auto-stop after this many seconds in Clip mode (default `120`). |
+| `--clip-timeout SECS`             | `600`   | Auto-stop after this many seconds in Clip mode (default `600`). |
+| `--clip-max-silence SECS`         | `2.0`   | In Clip mode, cap each silent pause at this many seconds in the audio sent for transcription (default `2.0`). Remote APIs bill by audio duration, so trimmed silence is not paid for; pauses up to the cap are kept for punctuation cues. `0` disables trimming. |
 | `--stream-timeout SECS`           | `None`  | Auto-stop after this many seconds in Stream mode (`None` = Always On, no auto-stop). Tray equivalent: **Stream timeout** in the Stream (advanced) submenu. |
 
 Native streamers (vosk, `gpt-realtime-whisper`) are always streaming

scribe_cli-1.2.0/docs/index.md

@@ -0,0 +1,58 @@
+<!--
+  Home page. The feature bullets are pulled straight from README.md (single
+  source of truth) via the include-markdown plugin; everything else links into
+  the guide.
+-->
+<p align="center">
+  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" alt="Scribe" width="96">
+</p>
+
+# Scribe
+
+Scribe is a speech-to-text CLI and tray app that pipes transcribed text
+into the focused window. It supports local and cloud-based APIs, batch and
+streaming workflows.
+
+{%
+  include-markdown "../README.md"
+  start="<!-- intro-start -->"
+  end="<!-- intro-end -->"
+%}
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png" alt="Scribe tray menu" width="300">
+</p>
+
+## Get started
+
+```bash
+pip install scribe-cli[all]
+scribe
+```
+
+- **[Installation](installation.md)** — PortAudio, extras, Ubuntu / GNOME tray libs, Windows.
+- **[Quickstart](quickstart.md)** — your first dictation in a couple of minutes.
+- **[Backends](backends.md)** — Vosk, Whisper, Whisper FUTO, OpenAI, Groq; streaming vs batch.
+- **[CLI reference](cli.md)** — every `scribe --help` flag with examples.
+
+## Guides
+
+- [Backends in detail](backends.md) — model lists, streaming recipes, vocabulary biasing.
+- [Output modes](output.md) — keystroke vs clipboard vs terminal vs file, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](tray.md) — menu tree, icon states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart](desktop-install.md) — `scribe-install` launcher integration.
+- [CLI reference](cli.md) — full flag reference and fine tuning.
+
+## From the same author
+
+A few other open-source tools I maintain.
+
+**Scientific writing & data**
+
+- [**texmark**](https://perrette.github.io/texmark/) — write scientific articles in Markdown and convert them to journal-ready LaTeX/PDF.
+- [**papers**](https://perrette.github.io/papers/) — command-line BibTeX bibliography and PDF library manager.
+- [**datamanifest**](https://perrette.github.io/datamanifest/) — declarative, reproducible dataset management. *(See also the [datamanifest.toml](https://perrette.github.io/datamanifest.toml/) format spec and the [DataManifest.jl](https://awi-esc.github.io/DataManifest.jl/) Julia port.)*
+
+**Speech to Text (dictate) and Text to Speech (read-aloud) tools**
+
+- [**bard**](https://perrette.github.io/bard/) — text-to-speech reader.

{scribe_cli-1.1.1 → scribe_cli-1.2.0}/docs/installation.md

@@ -9,7 +9,11 @@ clipboard / terminal output.
 ## System dependencies
 
 Scribe records audio via PortAudio (through `sounddevice`) and reads /
-writes the clipboard via `xclip` on Linux. On Ubuntu:
+writes the clipboard via `xclip` on Linux — preferred over `wl-copy`
+on Wayland, where the latter briefly steals keyboard focus on GNOME
+< 47 and breaks pasting into Electron apps (see
+[Clipboard backend on Wayland](output.md#clipboard-backend-on-wayland)).
+On Ubuntu:
 
 ```bash
 sudo apt-get install portaudio19-dev xclip

{scribe_cli-1.1.1 → scribe_cli-1.2.0}/docs/output.md

@@ -52,6 +52,24 @@ the moment scribe fires the paste: the terminal then sees
 remember Shift for terminal targets, nothing for GUI apps where plain
 `Ctrl+V` already works (including VS Code's editor pane).
 
+### Clipboard backend on Wayland
+
+The paste path writes the clipboard through `pyperclip`, which on a
+Wayland session would normally use `wl-copy`. On compositors without a
+data-control protocol (GNOME < 47), `wl-copy` has to create a temporary
+invisible window and briefly take keyboard focus in order to own the
+selection. Most apps tolerate that focus blip, but Electron apps often
+don't return focus to the input field inside the page afterwards, so
+the synthesised Ctrl+V lands nowhere.
+
+Scribe therefore prefers `xclip` whenever XWayland is available: the
+clipboard is set through XWayland with no focus change, and the
+compositor syncs the X and Wayland selections both ways, so every app
+— X11-hosted or Wayland-native — sees the same text. The clipboard is
+a single session-global resource owned by the compositor; which tool
+set it is invisible to the app you paste into. When `xclip` or
+XWayland is missing, scribe falls back to `wl-copy`.
+
 ### `--type-direct` — bypass the clipboard
 
 In keystroke mode `--type-direct` (or **Options → Keyboard → Input
@@ -214,8 +232,9 @@ scribe --mode clipboard
 The transcription is copied to the system clipboard at end of recording
 and you press Ctrl+V (or Ctrl+Shift+V in a terminal) yourself. No
 keystrokes are synthesised, so there is no typer-backend involvement
-and no Wayland portal prompt — `pyperclip` / `wl-copy` is all that is
-needed.
+and no Wayland portal prompt — `pyperclip` (backed by `xclip` or
+`wl-copy`, see [Clipboard backend on Wayland](#clipboard-backend-on-wayland))
+is all that is needed.
 
 As with keystroke mode, the clipboard is left holding the
 transcription after scribe finishes; save any previous clipboard

scribe_cli-1.2.0/docs/quickstart.md

@@ -0,0 +1,80 @@
+# Quickstart
+
+Once Scribe is [installed](installation.md), launch it from a terminal:
+
+```bash
+scribe
+```
+
+This starts the **system tray icon**. Press Record, speak, press Stop — the
+transcription lands in the focused window.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/perrette/scribe/main/docs/app-tray-menu.png" alt="Scribe tray menu" width="300">
+</p>
+
+## Backend auto-selection
+
+Scribe picks the first backend whose key / dependency is present, in order
+**`groq` → `openai` → `whisper-futo` → `whisper` → `vosk`**. So with
+`GROQ_API_KEY` set, `scribe` is equivalent to:
+
+```bash
+scribe --backend groq --model whisper-large-v3-turbo
+```
+
+See [Backends](backends.md) for the full picture (streaming vs batch, model
+lists, when to pick which).
+
+## Overriding the defaults
+
+You can override the backend / model 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 --record                                        # start recording immediately on launch (tray or terminal)
+scribe --record --frontend terminal --mode file        # one-shot batched dictation → file
+scribe --record --frontend terminal --mode file --stream  # streamed: chunks appended live as you speak
+scribe --mode clipboard                                # copy to clipboard, no keystroke
+scribe --mode terminal                                 # only print to stdout
+scribe --mode file -o transcript.txt                   # append to a file (no keystroke / clipboard)
+```
+
+With `--no-interactive` (terminal frontend only), Scribe skips the interactive
+menu and starts recording right away — handy for scripted, one-shot
+transcriptions. See [Output modes](output.md) for where the transcript goes,
+and the [CLI reference](cli.md) for every flag.
+
+## Getting an API key
+
+Groq is the **recommended cloud backend by default** — extremely fast (by a
+wide margin compared to other cloud STT options, especially in **Stream** mode
+where the per-chunk roundtrip latency dominates the perceived speed), 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`:
+
+```bash
+export GROQ_API_KEY=YOURAPIKEY
+```
+
+[OpenAI](https://openai.com/api/) with `gpt-4o-mini-transcribe` is another
+fast option (`export OPENAI_API_KEY=...`), and the local Whisper / Vosk
+backends need no key at all.
+
+## Biasing the recogniser
+
+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):
+
+```bash
+scribe --prompt "Patient notes from a cardiology consult." \
+       --words tachycardia bradycardia echocardiogram metoprolol
+```
+
+See [Backends › Vocabulary biasing](backends.md#vocabulary-biasing) for what
+each backend does with them.

{scribe_cli-1.1.1 → scribe_cli-1.2.0}/docs/roadmap-libei.md

@@ -37,7 +37,7 @@ scribe has two output paths into the focused app:
    added pain of layout-dependent character handling and 100+ keystrokes
    per utterance.
 
-Both paths live in [`scribe/keyboard.py`](../scribe/keyboard.py).
+Both paths live in [`scribe/keyboard.py`](https://github.com/perrette/scribe/blob/main/scribe/keyboard.py).
 
 ## Target architecture
 
@@ -85,7 +85,7 @@ delegates `paste_text()` to `Typer.paste()`.
 No new functionality; pure refactor so that subsequent phases plug in cleanly.
 
 - Extract `Typer` protocol + `PynputTyper` from
-  [`scribe/keyboard.py`](../scribe/keyboard.py).
+  [`scribe/keyboard.py`](https://github.com/perrette/scribe/blob/main/scribe/keyboard.py).
 - Move `paste_text()` and `safe_type_text()` into `PynputTyper`.
 - `type_text(...)` becomes a thin facade that resolves a typer via
   `pick_typer()` and delegates. Keep the public signature unchanged so