scribe-cli 1.1.0__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.0 → 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
@@ -275,20 +278,13 @@ Once the buffer has grown to at least `--stream-chunk-min` (default
 (default 10 s) regardless of silence, to cap latency. The session
 continues until you stop it manually.
 
-The **first** chunk of a streaming thread uses a different floor:
-`--stream-first-chunk-min` (default 3 s). The bootstrap chunk has no
-prior text to bias Whisper's punctuation/casing, so a longer audio
-window lets the model produce a properly-punctuated transcript whose
-tail then seeds the rolling prompt for every chunk after it.
-Subsequent chunks fall back to `--stream-chunk-min`. The override
-also re-engages right after a context-reset silence (i.e. when a long
-pause cleared the rolling tail — see *Cross-chunk prompt context*
-below). Set `--stream-first-chunk-min` equal to `--stream-chunk-min`
-to disable the override. It's automatically inactive when
-`--stream-context-length 0` (Patient profile), where there is no
-rolling context to bootstrap. Internally clamped to `≤
---stream-chunk-max` so a misconfigured pair can't deadlock the
-chunker.
+The first chunk uses a higher floor (`--stream-first-chunk-min`,
+default 3 s) so the bootstrap chunk has enough audio to seed the
+rolling prompt for the rest. Auto-disabled when
+`--stream-context-length 0` (Patient). If you stop talking before
+the floor is reached, a pause past `--stream-context-reset-silence ×
+--stream-chunk-silence-break` (default 1.8 s) flushes the buffer
+anyway — your utterance is never stranded.
 
 ### Does pseudo-streaming change the API cost?
 

{scribe_cli-1.1.0 → 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.0 → 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
@@ -21,7 +25,10 @@ On macOS use Homebrew:
 brew install portaudio
 ```
 
-(Windows ships everything needed via the wheels.)
+On Windows there are **no system packages to install**: `sounddevice`
+bundles PortAudio in its wheel and the clipboard uses the native Windows
+API, so neither `portaudio19-dev` nor `xclip` apply. See the
+[Windows quickstart](#windows) below.
 
 ## Python package
 
@@ -50,14 +57,52 @@ the four backends and the tray UI:
 | `[vosk]`     | `vosk`                                             | local Vosk backend (streaming)          |
 | `[openai]`   | `openai`, `soundfile`                              | OpenAI cloud backend (incl. realtime)   |
 | `[groq]`     | `openai`, `soundfile`                              | Groq cloud backend                      |
-| `[keyboard]` | `pynput`                                           | the `pynput` typer (XTest/Quartz/WinAPI)|
-| `[app]`      | `pystray`, `PyGObject`                             | system tray icon                        |
-| `[all]`      | all of the above                                   | one-shot setup                          |
+| `[keyboard]` | `pynput`                                           | back-compat only — `pynput` is a base dep now |
+| `[app]`      | `PyGObject` (Linux only)                            | the Linux AppIndicator tray binding     |
+| `[all]`      | every backend + Linux tray binding                 | one-shot setup                          |
+
+> **`pynput` and `pystray` are base dependencies.** The default run uses
+> the keyboard typer and the system-tray app, so both ship with the plain
+> `pip install scribe-cli` — you do **not** need `[keyboard]` or `[app]`
+> for the standard experience. `[app]` now only adds the Linux-only
+> `PyGObject` AppIndicator binding (skipped automatically on Windows/macOS
+> via a `sys_platform == 'linux'` marker, since it needs GTK and won't
+> pip-install elsewhere).
 
 You need at least one backend extra (or none if you only plan to use
 cloud backends *and* already have the `openai` package). The `groq`
 backend reuses the `openai` client, so `[openai]` covers both.
 
+## Windows
+
+Windows 11 is tested and working on Python 3.14 (64-bit). Every
+dependency — `onnxruntime`, `faster-whisper`/`ctranslate2`,
+`pystray`/`Pillow`, `pynput` — resolves a ready-made `win_amd64` wheel,
+so there is no build toolchain to install and no need to downgrade
+Python.
+
+From PowerShell:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+# If activation is blocked by the execution policy, run once:
+#   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+pip install -e .[whisper]      # or [all], or a cloud backend like [openai]
+scribe
+```
+
+That's the whole setup. There are **no system packages** to install
+(`apt`/`portaudio19-dev`/`xclip` are Linux-only) and **nothing to create
+by hand** — earlier builds needed a manual `C:\tmp` folder, which is no
+longer the case.
+
+- **Tray icon:** appears under the taskbar overflow arrow (`^`) by
+  default; pin it via *Settings → Personalization → Taskbar → Other
+  system tray icons*. A single click on the icon starts recording.
+- **Microphone:** if recording fails, enable *Settings → Privacy &
+  security → Microphone → "Let desktop apps access your microphone"*.
+
 ## Ubuntu / GNOME tray dependencies
 
 The tray icon needs system libraries for the AppIndicator stack:

{scribe_cli-1.1.0 → 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