🔊 outloud
Free, open-source, local text-to-speech for macOS.
Like Handy, but for reading aloud.
Select text in any app — browser, terminal, PDF, mail — press ⌥⌘L, and a
natural voice reads it to you. Everything runs locally on your Mac: no cloud, no
API keys, no subscription, no telemetry. Ever.
Features
- Works everywhere — one global hotkey reads the selection in any app
(Accessibility API first, smart clipboard fallback, special handling for
terminals with Secure Keyboard Entry).
- Starts speaking in ~1-2 seconds, no matter how long the text is: a
resident daemon keeps the model warm and synthesizes sentence-by-sentence,
streaming into the player while the rest is still being generated.
- Floating HUD while reading: live speed control (−/+, applied instantly
mid-playback with pitch correction), exact pause/resume, instant replay, stop.
- Reading history with cached audio — re-listen to anything instantly from
the 🔊 menu bar icon or the Spotlight-style search (⌥⌘H).
- 9 languages, 50+ voices via Kokoro-82M:
English (US/UK), Spanish, French, Italian, Portuguese, Hindi, Japanese*, Chinese*.
- Scriptable CLI:
outloud "text", echo text | outloud, outloud --history,
outloud --last — build your own integrations.
*Japanese and Chinese need extras: ~/.outloud/venv/bin/pip install "misaki[ja]" / "misaki[zh]".
Install
Requires macOS and Homebrew.
git clone https://github.com/EloiGils/outloud.git
cd outloud
./install.sh
The installer sets up: a private Python env with Kokoro (~2 GB incl. PyTorch),
mpv as the audio engine, a launchd daemon that keeps the
model warm from login, and the Hammerspoon
UI module (hotkeys + HUD + menu bar). First run: grant Hammerspoon
Accessibility permission when macOS asks.
To remove everything: ./uninstall.sh.
Usage
| |
|---|
| ⌥⌘L | read the selected text aloud |
| ⌥⌘K | stop |
| ⌥⌘H | search your reading history |
| 🔊 menu bar | recent readings, voice & speed settings |
| HUD | − 1.5× + live speed · ⏸ exact pause · 🔁 replay · ✕ |
outloud "read this sentence" # CLI
cat article.md | outloud -l a # pipe, English
outloud -l e --voice em_alex # Spanish, male voice
outloud --history # list past readings
outloud --reread 20260721-134536 # re-listen (instant, cached audio)
outloud -l auto -o note.m4a < notes.txt # save to an audio file instead of playing it
-o FILE writes .m4a, .wav or .mp3 (mp3 needs ffmpeg) using the warm daemon, without
playing anything, so scripts and AI agents can hand someone an audio file. -l auto picks the
language from the text.
How it works
select text ──⌥⌘L──▶ Hammerspoon UI ──▶ outloud CLI ──▶ daemon (Kokoro warm, CPU)
│ sentence-by-sentence
▼
HUD controls ◀──socket──▶ mpv (gapless playlist,
exact pause, live speed)
Design notes learned the hard way:
afplay can't truly pause (the audio clock keeps running) — mpv's IPC
socket gives exact pause and live speed with pitch correction.- On Apple Silicon, Kokoro is ~2.3× faster on CPU than on MPS/GPU
(one istftnet op falls back per call). The daemon pins CPU on purpose.
- The first text chunk is cut extra-short (~30-90 chars) so the first audio
lands in about a second; later chunks are full sentences.
Roadmap
Credits
Standing on excellent shoulders: Kokoro-82M
(Apache-2.0) · mpv · Hammerspoon ·
UX inspired by Handy and Speechify.
License
MIT
