# Lue Reader: A Terminal eBook Reader With Synchronized Text-to-Speech

> Lue renders EPUB, PDF, DOCX, HTML, RTF, TXT and Markdown in the terminal and reads them aloud, highlighting each word as it is spoken. Here is how the TTS pipeline works, how to install it, and where it falls short.

**paulilaaso/lue** — Terminal eBook Reader with Audiobook-Quality Text-to-Speech — Supports EPUB, PDF, DOCX, HTML, RTF, TXT, and MD.

- Repository: https://github.com/paulilaaso/lue
- Stars: 817 · Forks: 46
- Language: Python
- License: GPL-3.0
- Published: 2026-09-16 · Updated: 2026-09-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/paulilaaso-lue

## What Lue Solves, and for Whom

Most terminal readers stop at pagination. Lue adds a speech layer: the same window that shows the text also plays it, and the highlight follows the audio rather than a timer. The README describes this as blending reading and listening, with synchronized word highlighting and smooth auto-scrolling.

The target user is narrow but real. You read EPUB, PDF, DOCX, HTML, RTF, TXT or Markdown files, you are comfortable in a shell, and you want either eyes-free consumption or a second channel while you read. The project is classified in pyproject.toml as Development Status 4 - Beta, so treat it as a tool for individual use rather than something to build a workflow on top of. It is not a library, not a service, and not a GUI application.

## The Two TTS Backends and How Audio Reaches the Terminal

Lue ships two speech engines behind one flag. Edge TTS is the default and the only one installed by the core dependency list: requirements.txt pins edge-tts>=7.2.7, and pyproject.toml lists edge-tts>=7.2.0 as a required dependency. It synthesizes speech through Microsoft's online service, which is why the Quick Start note says the default path requires internet.

Kokoro is the offline option and lives in an optional extra. The kokoro extra in pyproject.toml pulls kokoro>=0.9.4, soundfile>=0.13.1 and huggingface-hub>=0.34.4, and the README instructs you to install PyTorch separately, either the CPU build or the CUDA build from the PyTorch index. The espeak package is listed as an optional prerequisite for Kokoro support, so a Linux or macOS install that skips it may still work for Edge TTS but not for local synthesis.

FFmpeg sits under both engines. It is the one hard prerequisite in the README, used for audio processing, and it is not a Python package, so pip cannot install it for you.

The reading pipeline itself is a format-specific parse into a common text model. PyMuPDF handles PDF, python-docx handles DOCX, striprtf handles RTF, the Markdown package handles Markdown, and EPUB, HTML and TXT are covered by the remaining stack. PDFs get an extra pass: the --filter flag strips page numbers, headers and footnotes before the text reaches the reader. That is a heuristic, and the README exposes its margins precisely because the default will not suit every layout.

## Installing Lue and Reading Your First Book

The fastest path is PyPI, and it assumes FFmpeg is already present. Install FFmpeg first, then the package, then run the built-in navigation guide before opening a book.

```bash
brew install ffmpeg
pip install lue-reader
lue --guide
lue path/to/your/book.epub
```

On Ubuntu or Debian the FFmpeg step is `sudo apt install ffmpeg`. The guide is a practice mode for the default key bindings, so if you have never used the reader it is worth the two minutes before you load anything.

If you want the offline engine, the README does not treat it as a one-line install. You install PyTorch for your platform, uncomment the Kokoro lines in requirements.txt, then reinstall requirements and the package.

```bash
pip install torch torchvision torchaudio
pip install -r requirements.txt
pip install .
lue --tts kokoro path/to/your/book.epub
```

For the CUDA build the README gives `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121`. Arch users have a third route: `yay -S lue-reader-git` from the AUR. Windows users do not get a native install; the README routes them through WSL, installing ffmpeg, python3 and python3-pip inside the Ubuntu environment.

Once a book is open, the practical flags are --voice, --speed (1x to 3x), --over for sentence overlap in seconds, --keys vim for a Vim layout, and --mode 0 through 3 for minimal, medium, full and speed-reading layouts. Progress saves on quit with `q`.

## Where Lue Gets in the Way

The default engine needs a network connection. That is the single biggest constraint, and it is stated plainly in the Quick Start note rather than hidden. Anyone reading on a plane, in an air-gapped environment, or behind a proxy that blocks the Edge endpoint will get no audio until they set up Kokoro, and Kokoro costs a PyTorch install plus a model download through huggingface-hub.

PDF extraction is the second weak point. Lue leans on PyMuPDF plus a margin filter, and the filter is percentage-based: the default removes 10 percent from the top and bottom of each page. Books with running heads inside that band will lose text; books with footnotes deeper than the band will read them aloud. The README gives you `--filter 0.12 0.20` style control, but tuning it is manual work per document.

The project is also beta. pyproject.toml marks it Development Status 4 - Beta, the version is 0.5.0, and the release history shows a gap of roughly seven months between v0.4.0 in December 2025 and v0.5.0 in July 2026. That cadence is not a red flag, but it does mean the CLI surface can still move. The last push to the repository was on 2026-07-16.

Finally, this is not the right tool for annotation, library management, or syncing across devices. There is no such feature in the README, and nothing in the repository layout suggests one.

## How Lue Differs From a General Terminal Pager

The obvious comparison is less, or a pager-style reader such as the ones built into editors. Those tools render bytes and let you scroll. They have no concept of a sentence, a chapter, or a speech cursor, and they cannot open an EPUB at all without help.

Lue's difference is the document model. Because it parses formats into structured text, it can move the reading line by sentence with `j` and `k`, by paragraph with `h` and `l`, and by chapter with `z` and `x`, and it can open a chapter index with `c`. Those bindings only make sense if the underlying text has been segmented, which is exactly what the format parsers produce and what a pager never does.

The other difference is the audio path. A pager plus a separate speech tool means two processes and no shared cursor; Lue keeps the highlight and the speech in one loop, which is why word-level highlighting is listed as a feature rather than an add-on.

## Licence and Long-Term Cost

Lue is GPL-3.0. If you install it and read books with it, the licence obligations are minimal. If you fork it, bundle it into a product, or link it into a larger application, the copyleft terms apply to the combined work, and the LICENSE file at the repository root is the authoritative text. That is a description of the licence, not legal advice; consult a lawyer before shipping anything derived from it.

Upgrade cost is low but not zero. `pip install lue-reader` pulls the current release, and the dependency list is small: python-docx, striprtf, rich, PyMuPDF, Markdown, platformdirs and edge-tts. PyMuPDF and edge-tts are the two that change behaviour most often, since one governs PDF extraction and the other governs the default voice service. If you pin versions, pin those two.

## Conclusion

Adopt Lue if you already live in a terminal, read long-form documents, and want speech and text in the same window; skip it if you need a GUI, guaranteed offline audio without extra setup, or a stable 1.0 API. Before committing, run pip install lue-reader, check that ffmpeg is on your PATH, and test one EPUB and one PDF with --tts edge to confirm audio, highlighting and progress saving behave as the README describes.

## FAQ

### Does Lue Reader need an internet connection?

The default Edge TTS engine does, as the Quick Start note states. For offline use you install the Kokoro extra plus PyTorch, then run with --tts kokoro.

### Which file formats can Lue Reader open?

EPUB, PDF, TXT, DOCX, HTML, RTF and Markdown, according to the feature table. PDFs additionally support the --filter flag for removing page numbers, headers and footnotes.

### Can I run Lue Reader on Windows?

The README routes Windows users through WSL rather than a native install. Inside the Ubuntu environment you install ffmpeg, python3 and python3-pip, then follow the Linux steps.

## Sources

- [Issues](https://github.com/paulilaaso/lue/issues)
- [License: GPL-3.0](https://github.com/paulilaaso/lue/blob/main/LICENSE)
- [paulilaaso/lue on GitHub](https://github.com/paulilaaso/lue)
- [README](https://github.com/paulilaaso/lue/blob/main/README.md)
- [Releases](https://github.com/paulilaaso/lue/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/paulilaaso-lue