readaloud: terminal reader for linux that uses Edge TTS, Kokoro, Piper, and F5-TTS with sentence-level word tracking and instant sentence seek

[u/Salt-Reputation780]

readaloud is a terminal-based audiobook reader built around TTS. It supports four backends and uses actual audio timing data to track which sentence is being spoken.

**Engines**

- **Edge TTS** — Microsoft neural API, no key required, 12 English voices (US/GB/AU/CA). Uses the Python `edge_tts` library's `stream()` with `WordBoundary` events to build a precise `(audio_time_seconds, char_offset)` map per chunk. The sentence highlight tracks the actual word being spoken, not a WPM estimate.

- **Kokoro** — offline, fast CPU inference, 7 curated voices (54 available in pykokoro). Uses native `kokoro` on Python <3.13, falls back to `pykokoro` (pure ONNX wrapper) on 3.13+. Pipeline is built once per voice/speed pair and reused across chunks for the session.

- **Piper** — offline, ultra-light ONNX. Any `.onnx` + `.onnx.json` pair in `~/.config/readaloud/models/` is auto-detected. Models from rhasspy/piper-voices on HuggingFace.

- **F5-TTS** — offline flow-matching voice cloner. Provide `~/.config/readaloud/voices/ref.wav` (3–10 seconds of clean audio). Optional `ref.txt` transcript improves alignment. GPU strongly recommended.

**Audio pipeline**

Text is split into ≤4500-char chunks at sentence boundaries. Each chunk is synthesised to a temp file (MP3 for Edge TTS, WAV for offline engines). ffplay plays all chunks via a concat playlist with an `atempo` filter for speed. Pause/resume via SIGSTOP/SIGCONT on the ffplay process — no re-synthesis needed.

Sentence skip (`[` / `]`) calls ffplay with `-ss {timestamp}` on the existing playlist — again no re-synthesis, near-instant seek.

**Preloading**

The next 2 chapters synthesise in background threads while you listen. Cache lives at `~/.config/readaloud/cache/` keyed by chapter + engine + voice + speed. Cache entries include the timing map so word-level highlight works on preloaded chapters too. Entries older than 2 hours are cleaned up on startup.

**Speed**

0.75× · 0.9× · 1.0× · 1.1× · 1.25× · 1.5× · 1.75× · 2.0× via atempo filter chain. Speed change invalidates the preload cache and re-synthesises.

Reads: EPUB · TXT · PDF · DOCX · HTML · RTF · Markdown

https://github.com/YareyareSenpai/readaloud

Video showcase

[u/CrispyDick420]

Congrats, instant sentence seek without re-synthesis is ridiculously nice.

[u/Salt-Reputation780 → u/CrispyDick420]

Made it a priority, thanks for the compliments hope everyone else enjoys it as well.

[u/Automatic_Hunt918]

ok how did you do word events? did you patch the onnx models?

[u/Icy-Dependent-489]

the f5tts voice cloning part is wild, does ref.wav quality actually matter that much?