Documentation

Install First run Usage Voices CLI How it works Troubleshooting Uninstall

Install

Requirements: macOS (Apple Silicon recommended) and Homebrew.

curl -fsSL https://raw.githubusercontent.com/EloiGils/outloud/main/install.sh | bash

Or from a clone:

git clone https://github.com/EloiGils/outloud.git
cd outloud
./install.sh

The installer sets up:

a private Python environment at ~/.outloud/venv with the Kokoro-82M voice model (~2 GB including PyTorch — one-time download),
mpv as the audio engine and Hammerspoon as the UI layer (via Homebrew),
the outloud CLI and a launchd daemon that keeps the voice model warm from login (that's why it speaks in ~1.7 s).

First run

macOS will ask you to grant Hammerspoon Accessibility permission (System Settings → Privacy & Security → Accessibility). This is what lets the hotkey grab your text selection.
Select any text, press ⌥⌘L, and listen.
Pick your voice and language in the 🔊 menu bar icon → Voice.

The very first reading after login takes a few extra seconds while the model warms up. Every reading after that starts in about 1-2 seconds.

Usage

Action	How
Read the selected text	`⌥⌘L` — in any app
Stop	`⌥⌘K` or ✕ on the HUD
Search reading history	`⌥⌘H` — Spotlight-style, Enter replays
Pause / resume (exact)	⏸ / ▶ on the HUD
Replay from the top	🔁 on the HUD (instant)
Change speed live	− / + on the HUD (0.5×-3×, persists as your default)
Re-listen to a recent reading	🔊 menu bar → click any entry

While reading, a floating HUD shows what's playing:

🔊 Reading your article…    −  1.5×  +    ⏸  🔁  ✕

Voices & languages

outloud ships with 50+ Kokoro voices across 9 languages. Switch in the 🔊 menu → Voice, or per-call from the CLI (-l language, --voice):

Code	Language	Example voices
`a`	English (US)	af_heart, am_adam
`b`	English (UK)	bf_emma
`e`	Spanish	ef_dora, em_alex, em_santa
`f`	French	ff_siwis
`i`	Italian	if_sara, im_nicola
`p`	Portuguese (BR)	pf_dora, pm_alex
`h`	Hindi	hf_alpha, hm_omega
`j`	Japanese*	jf_alpha
`z`	Mandarin*	zf_xiaobei

*Japanese and Mandarin need one extra: ~/.outloud/venv/bin/pip install "misaki[ja]" (or "misaki[zh]").

CLI reference

outloud "read this sentence"      # read text
cat article.md | outloud          # from a pipe
outloud                           # read the clipboard
outloud -s 1.6                    # speed
outloud -l e --voice em_alex      # Spanish, male voice

outloud --pause | --resume        # exact pause / resume
outloud --replay                  # restart current reading (instant)
outloud --speed-live 2.0          # change speed of current reading
outloud --stop

outloud --history                 # list past readings
outloud --history 50 --json       # for scripts/integrations
outloud --reread 20260721-134536  # re-listen (cached audio, ~0.4s)
outloud --last                    # re-listen to the most recent

Spanish flag aliases work everywhere: --pausa, --reanudar, --repetir, --historial, --releer, --ultimo.

How it works

select text ──⌥⌘L──▶ Hammerspoon UI ──▶ outloud CLI ──▶ daemon (Kokoro, warm)
                                                          │ sentence-by-sentence
                                                          ▼
                            HUD controls ◀──socket──▶ mpv (gapless playlist,
                                                      exact pause, live speed)

Warm daemon — the model loads once at login, not per reading.
Sentence streaming — the first chunk is cut extra short (~30-90 chars) so audio starts in ~1 s while the rest synthesizes in the background.
mpv as the player — its IPC socket gives exact pause and live speed with pitch correction. (afplay can't truly pause: the audio clock keeps running.)
CPU on purpose — on Apple Silicon, Kokoro is ~2.3× faster on CPU than on MPS/GPU, because one operator falls back per call.

Troubleshooting

The hotkey does nothing

Check Hammerspoon has Accessibility permission (System Settings → Privacy & Security → Accessibility) and that the 🔨 icon is in your menu bar. Then reload: click it → "Reload Config".

"No text selected" in iTerm

outloud reads iTerm's clipboard (iTerm blocks synthetic keystrokes but copies selections automatically). Make sure iTerm's "Copy to pasteboard on selection" (Settings → General → Selection) is enabled — it is by default.

First reading is slow

The daemon warms the model for your system language at login. The first reading in a different language loads that pipeline once (~5 s), then it's fast.

Where is my data?

History and cached audio: ~/Library/Application Support/Outloud. Daemon log: ~/.cache/outloud-daemon.log. Settings live in Hammerspoon (hs.settings, keys outloud.*).

Uninstall

cd outloud && ./uninstall.sh

Removes the CLI, daemon, Python environment and UI module. Your reading history stays in ~/Library/Application Support/Outloud until you delete it.