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

scribe_cli-0.16.0/.github/FUNDING.yml

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

scribe_cli-0.16.0/.gitignore

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

scribe_cli-0.16.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: scribe-cli
+Version: 0.16.0
+Summary: Speech-to-text CLI and system-tray app for dictating into any focused window. Local (vosk, faster-whisper) or cloud (groq, openai) backends, batch or streaming.
+Author-email: Mahé Perrette <mahe.perrette@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Mahé Perrette
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        Note: This project relies on external packages that may have more restrictive
+        licenses. For example, the `pynput` package is licensed under LGPLv3, which
+        has different requirements compared to the MIT License. Please review the
+        licenses of all dependencies before using or distributing this software to
+        ensure compliance with their respective terms.
+Project-URL: Homepage, https://github.com/perrette/scribe
+Keywords: speech-to-text,speech recognition,transcription,dictation,voice-typing,voice-to-text,realtime,streaming,language,AI,local,API,cli,tray,vosk,whisper,openai,groq,gpt-4o,linux,wayland,keyboard,clipboard
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+Requires-Dist: tqdm
+Requires-Dist: requests
+Requires-Dist: pyperclip
+Requires-Dist: unidecode
+Requires-Dist: termcolor
+Requires-Dist: 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: vosk
+Requires-Dist: vosk; extra == "vosk"
+Provides-Extra: app
+Requires-Dist: pystray; extra == "app"
+Requires-Dist: PyGObject; extra == "app"
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.37.0; extra == "openai"
+Requires-Dist: soundfile; extra == "openai"
+Provides-Extra: groq
+Requires-Dist: openai<3,>=2.37.0; extra == "groq"
+Requires-Dist: soundfile; extra == "groq"
+Provides-Extra: all
+Requires-Dist: pynput; extra == "all"
+Requires-Dist: faster-whisper; extra == "all"
+Requires-Dist: openai<3,>=2.37.0; extra == "all"
+Requires-Dist: soundfile; extra == "all"
+Requires-Dist: vosk; extra == "all"
+Requires-Dist: pystray; extra == "all"
+Dynamic: license-file
+
+[![pypi](https://img.shields.io/pypi/v/scribe-cli)](https://pypi.org/project/scribe-cli)
+![](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fperrette%2Fscribe%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+
+# Scribe  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" width="48">
+
+**Talk. It types.** Scribe is a speech-to-text CLI and tray app that
+pipes transcribed text straight into the focused window. It supports local and
+cloud-based APIs, batch and streaming workflows.
+
+## What it does
+
+- Records from your mic and transcribes via one of four backends —
+  **Vosk** (local, streaming), **Whisper** (local, batch), **OpenAI**
+  (cloud, batch *or* streaming), **Groq** (cloud, batch).
+- Delivers the transcript three ways: paste into the focused window
+  (default), copy to clipboard, or print to the terminal.
+- Runs as a **system tray icon** with a single Record button, or as an
+  interactive **terminal TUI** — same menu in both.
+- Hooks into your DE's keyboard shortcuts via `SIGUSR1` (toggle
+  recording) and `SIGUSR2` (cancel).
+- Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows;
+  works under Termux for clipboard / terminal output.
+
+## Getting started
+
+```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
+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.
+
+See documentation below for setting up keyboard input on Ubuntu Wayland.
+
+### 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.
+
+## Backends at a glance
+
+| Backend         | `--backend` | Default model              | Streaming model(s)        | Requires                            |
+|-----------------|-------------|----------------------------|---------------------------|-------------------------------------|
+| Groq (cloud)    | `groq`      | `whisper-large-v3-turbo`   | —                         | `GROQ_API_KEY`                      |
+| OpenAI (cloud)  | `openai`    | `gpt-4o-mini-transcribe`   | `gpt-realtime-whisper`    | `OPENAI_API_KEY`                    |
+| Whisper (local) | `whisper`   | `small`                    | —                         | `pip install scribe-cli[whisper]`   |
+| Vosk (local)    | `vosk`      | language-dependent         | all Vosk models           | `pip install scribe-cli[vosk]`      |
+
+Whether a transcription appears live as you speak or all at once when
+you stop depends on the **model** picked — see
+[docs/backends.md](docs/backends.md).
+
+## Documentation
+
+- [Installation & dependencies](docs/installation.md) — PortAudio,
+  extras, Ubuntu / GNOME tray libs.
+- [Backends in detail](docs/backends.md) — model lists, when to pick
+  which, the realtime model.
+- [Keyboard modes & typer backends](docs/keyboard.md) — keystroke vs
+  clipboard, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](docs/tray.md) — menu tree, icon
+  states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart (`scribe-install`)](docs/desktop-install.md)
+  — GNOME / KDE launcher integration.
+- [Fine tuning & CLI reference](docs/cli.md) — every `scribe --help`
+  flag with examples.
+
+## Compatibility
+
+Initially developed for Python 3 on Ubuntu 24.04 (GNOME + Wayland);
+works on macOS and Windows too. Wayland keystroke injection is
+convoluted but [solved](docs/keyboard.md). For dependencies of
+individual subsystems, check `pynput` (keyboard) and `pystray` (tray
+icon).

scribe_cli-0.16.0/README.md

@@ -0,0 +1,82 @@
+[![pypi](https://img.shields.io/pypi/v/scribe-cli)](https://pypi.org/project/scribe-cli)
+![](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fperrette%2Fscribe%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+
+# Scribe  <img src="https://github.com/perrette/scribe/raw/main/scribe_data/share/icon.png" width="48">
+
+**Talk. It types.** Scribe is a speech-to-text CLI and tray app that
+pipes transcribed text straight into the focused window. It supports local and
+cloud-based APIs, batch and streaming workflows.
+
+## What it does
+
+- Records from your mic and transcribes via one of four backends —
+  **Vosk** (local, streaming), **Whisper** (local, batch), **OpenAI**
+  (cloud, batch *or* streaming), **Groq** (cloud, batch).
+- Delivers the transcript three ways: paste into the focused window
+  (default), copy to clipboard, or print to the terminal.
+- Runs as a **system tray icon** with a single Record button, or as an
+  interactive **terminal TUI** — same menu in both.
+- Hooks into your DE's keyboard shortcuts via `SIGUSR1` (toggle
+  recording) and `SIGUSR2` (cancel).
+- Cross-platform: tested on Ubuntu (X11 and Wayland), macOS, Windows;
+  works under Termux for clipboard / terminal output.
+
+## Getting started
+
+```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
+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.
+
+See documentation below for setting up keyboard input on Ubuntu Wayland.
+
+### 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.
+
+## Backends at a glance
+
+| Backend         | `--backend` | Default model              | Streaming model(s)        | Requires                            |
+|-----------------|-------------|----------------------------|---------------------------|-------------------------------------|
+| Groq (cloud)    | `groq`      | `whisper-large-v3-turbo`   | —                         | `GROQ_API_KEY`                      |
+| OpenAI (cloud)  | `openai`    | `gpt-4o-mini-transcribe`   | `gpt-realtime-whisper`    | `OPENAI_API_KEY`                    |
+| Whisper (local) | `whisper`   | `small`                    | —                         | `pip install scribe-cli[whisper]`   |
+| Vosk (local)    | `vosk`      | language-dependent         | all Vosk models           | `pip install scribe-cli[vosk]`      |
+
+Whether a transcription appears live as you speak or all at once when
+you stop depends on the **model** picked — see
+[docs/backends.md](docs/backends.md).
+
+## Documentation
+
+- [Installation & dependencies](docs/installation.md) — PortAudio,
+  extras, Ubuntu / GNOME tray libs.
+- [Backends in detail](docs/backends.md) — model lists, when to pick
+  which, the realtime model.
+- [Keyboard modes & typer backends](docs/keyboard.md) — keystroke vs
+  clipboard, Wayland / `eitype`, `--type-direct`.
+- [System tray & global hotkeys](docs/tray.md) — menu tree, icon
+  states, `SIGUSR1`/`SIGUSR2`.
+- [Desktop entry & autostart (`scribe-install`)](docs/desktop-install.md)
+  — GNOME / KDE launcher integration.
+- [Fine tuning & CLI reference](docs/cli.md) — every `scribe --help`
+  flag with examples.
+
+## Compatibility
+
+Initially developed for Python 3 on Ubuntu 24.04 (GNOME + Wayland);
+works on macOS and Windows too. Wayland keystroke injection is
+convoluted but [solved](docs/keyboard.md). For dependencies of
+individual subsystems, check `pynput` (keyboard) and `pystray` (tray
+icon).

scribe_cli-0.16.0/docs/backends.md

@@ -0,0 +1,122 @@
+# Backends in detail
+
+Scribe ships four 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 (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:
+`groq → openai → whisper → vosk`.
+
+## `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.
+
+You can also auto-cut on silence:
+
+```bash
+scribe --silence-db -40 --silence 2
+```
+
+cuts the recording when a silence below −40 dB lasts more than 2
+seconds. The defaults (`--silence-db -200`, `--silence 120`) effectively
+disable this and keep full manual control.
+
+Streaming models (Vosk, `gpt-realtime-whisper`) emit partials as you
+speak and stop on the same Stop / Ctrl+C action — there is no silence
+threshold to tune.

scribe_cli-0.16.0/docs/cli.md

@@ -0,0 +1,95 @@
+# 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. |
+| `--api-key KEY`                 | API key for cloud backends; falls back to `OPENAI_API_KEY` / `GROQ_API_KEY` env. |
+| `--download-folder-whisper DIR` | Folder to store Whisper models.                                         |
+| `--download-folder-vosk DIR`    | Folder to store Vosk models.                                            |
+
+## 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.                                                 |
+
+## Realtime (`gpt-realtime-whisper`)
+
+| Flag                                              | Purpose                                                                                      |
+|---------------------------------------------------|----------------------------------------------------------------------------------------------|
+| `--realtime-delay {minimal,low,medium,high,xhigh}` | Trade off latency vs accuracy on `gpt-realtime-whisper` (default `medium`). Lower = faster partials but more paste churn in the focused window. |
+
+This flag only affects the OpenAI realtime model; the other backends
+ignore it.
+
+## Silence detection (whisper, openai batch, groq)
+
+| Flag                          | Default | Purpose                                                       |
+|-------------------------------|---------|---------------------------------------------------------------|
+| `--duration SECS`             | `120`   | Max recording duration in seconds.                            |
+| `--silence SECS`              | `120`   | Silence duration in seconds that triggers a cut (default effectively disables it). |
+| `--silence-db DB`             | `-200`  | Silence threshold in dB (default effectively disables it).    |
+| `-a, --restart-after-silence` | off     | Resume recording after a silence-triggered transcription.     |
+
+Streaming models (Vosk, `gpt-realtime-whisper`) ignore these — they
+have their own end-of-utterance signal.
+
+## Frontend
+
+| Flag                        | Purpose                                                              |
+|-----------------------------|----------------------------------------------------------------------|
+| `--frontend {tray,terminal}` | UI to launch (default `tray`).                                       |
+| `--no-prompt`               | In terminal mode, skip the interactive menu and record immediately.  |
+| `--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
+```
+
+Cut on 2 s of silence below −40 dB and auto-restart afterwards:
+
+```bash
+scribe --silence-db -40 --silence 2 -a
+```
+
+Stream OpenAI realtime transcripts with the most aggressive latency
+setting:
+
+```bash
+scribe --model gpt-realtime-whisper --realtime-delay minimal
+```
+
+Run scribe headlessly into a file without touching the clipboard or
+focused window:
+
+```bash
+scribe --frontend terminal --no-prompt --mode terminal -o session.txt
+```

scribe_cli-0.16.0/docs/desktop-install.md

@@ -0,0 +1,44 @@
+# Desktop entry & autostart (`scribe-install`)
+
+On Linux (GNOME, KDE, anything supporting the freedesktop
+[`.desktop`](https://specifications.freedesktop.org/desktop-entry-spec/)
+spec), the `scribe-install` command generates a `scribe.desktop` file
+under `$HOME/.local/share/applications` so scribe shows up in your
+launcher / dash.
+
+Any extra arguments are passed straight through to `scribe`, plus two
+install-only options: `--name` (the human-readable label) and
+`--frontend {tray,terminal}` (default: `tray`).
+
+## Two common flavors
+
+```bash
+scribe-install --name "Scribe"
+scribe-install --name "Scribe Terminal" --frontend terminal
+```
+
+- The first creates an app named **Scribe** that runs in tray mode
+  (no terminal window), with the tray icon as the only mode of
+  interaction.
+- The second creates an app named **Scribe Terminal** that opens a
+  terminal window and runs the interactive TUI.
+
+Keyboard mode defaults to `keystroke` — pass `--mode clipboard` or
+`--mode terminal` if you want a different default for the installed
+app.
+
+## Wayland / eitype auto-prompt
+
+After writing the desktop file, `scribe-install` checks whether you're
+on a Wayland session without `eitype` (the recommended typer backend
+for GNOME / KDE / Hyprland — see [keyboard.md](keyboard.md)). If so:
+
+- If `cargo` is already on your `$PATH`, it asks whether to run
+  `cargo install --git https://github.com/Adam-D-Lewis/eitype` for you
+  (~1–2 min, no `sudo`, writes only to `~/.cargo/bin`).
+- If `cargo` is missing, it prints the rustup + cargo-install recipe
+  so you can run it manually.
+
+`ydotool` is never auto-installed: enabling it grants kernel-level
+input access (via the `input` group or a setuid daemon) and ought to
+be a conscious choice. See its package docs if you need it.

scribe_cli-0.16.0/docs/installation.md

@@ -0,0 +1,84 @@
+# Installation & dependencies
+
+Scribe is a Python package distributed on PyPI as
+[`scribe-cli`](https://pypi.org/project/scribe-cli) (the `-cli` suffix
+disambiguates it from an unrelated package). It runs on Linux (X11 and
+Wayland), macOS, and Windows; on Android it works under Termux for
+clipboard / terminal output.
+
+## System dependencies
+
+Scribe records audio via PortAudio (through `sounddevice`) and reads /
+writes the clipboard via `xclip` on Linux. On Ubuntu:
+
+```bash
+sudo apt-get install portaudio19-dev xclip
+```
+
+On macOS use Homebrew:
+
+```bash
+brew install portaudio
+```
+
+(Windows ships everything needed via the wheels.)
+
+## Python package
+
+The simplest install pulls every optional dependency:
+
+```bash
+pip install scribe-cli[all]
+```
+
+For local development from a clone:
+
+```bash
+git clone https://github.com/perrette/scribe.git
+cd scribe
+pip install -e .[all]
+```
+
+## Pick-and-choose extras
+
+If you don't want everything, `scribe-cli` ships granular extras matching
+the four backends and the tray UI:
+
+| Extra        | Pulls in                                           | Needed for                              |
+|--------------|----------------------------------------------------|-----------------------------------------|
+| `[whisper]`  | `faster-whisper`                                   | local Whisper backend                   |
+| `[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                          |
+
+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.
+
+## Ubuntu / GNOME tray dependencies
+
+The tray icon needs system libraries for the AppIndicator stack:
+
+```bash
+sudo apt install libcairo-dev libgirepository1.0-dev gir1.2-appindicator3-0.1
+pip install PyGObject pystray
+```
+
+These come for free with `[all]` or `[app]`, but the apt packages must
+be installed first so `PyGObject` can compile.
+
+## Keyboard injection backends
+
+The Python `pynput` package is the default typer and is pulled in by
+`[keyboard]` / `[all]`. The other typer backends (`eitype`, `wtype`,
+`ydotool`) are OS-level binaries — see [keyboard.md](keyboard.md) for
+when you need them and how to install each.
+
+## Model cache
+
+Local backends (Vosk, Whisper) download their model files on first use
+to `$XDG_CACHE_HOME/<backend>` (defaults to `$HOME/.cache/<backend>`).
+Override with `--download-folder-vosk` / `--download-folder-whisper`.