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/).
