Read text aloud with high-quality neural TTS — from clipboard, stdin, or argument.

Lector wraps kokoro-onnx in a simple CLI with an interactive player. Audio is streamed chunk-by-chunk so reading starts immediately, even for long texts.

You need uv, a Python package manager. It handles everything else (including Python itself) automatically.

curl -LsSf https://astral.sh/uv/install.sh | sh

brew install uv

sudo apt install libportaudio2 portaudio19-dev   # Debian / Ubuntu

sudo apt install xclip          # X11
sudo apt install xsel           # X11 (alternative)
sudo apt install wl-clipboard   # Wayland

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your shell after installing so that the uv command is available.

uv tool install git+https://github.com/clstaudt/lector

Or from a local checkout:

uv tool install /path/to/lector

The first run downloads model files (~300 MB) to ~/.lector/models/.

# Read text directly
lector read "The quick brown fox jumps over the lazy dog."

# Read from the clipboard
lector read --clipboard

# Pipe text in
cat article.txt | lector read

Lector detects the language automatically and picks a matching voice.

Language is detected automatically by default (--lang auto). Set it explicitly with --lang:

lector read "Bonjour, comment allez-vous ?"           # auto-detected
lector read --lang de "Guten Morgen, wie geht es Ihnen?"  # explicit

If a detected language is not supported, Lector falls back to English.

German uses a separate community model (Kokoro-82M-ONNX-German-Martin), fetched automatically on first use (or in advance with lector download --german).

lector voices                 # all voices, grouped by language
lector voices --lang fr-fr    # only French voices

Pick a specific voice with --voice (this also implies the language):

lector read --voice af_nicole --speed 0.9 "Hello!"

See the full list at Kokoro-82M/VOICES.md.

Add a Quick Action so Read with Lector appears in the right-click Services menu:

lector install-service

Select text in any app → right-click → Services → Read with Lector. You may need to enable it in System Settings → Keyboard → Keyboard Shortcuts → Services.

Key lector read options: --lang, --voice, --speed.

uv tool upgrade lector

uv tool uninstall lector
rm -rf ~/.lector   # remove downloaded models

git clone <repo-url> && cd lector
uv sync
uv run lector read "Hello!"
uv run pytest

GPL-3.0-or-later