lue-reader 0.2.0

A terminal-based eBook reader with modular text-to-speech capabilities and multi-format support

Lue - Terminal eBook Reader with Text-to-Speech

Features • Quick Start • Installation • Usage • Development

---

✨ Features

Feature	Description
📖 Multi-Format Support	Support for EPUB, PDF, TXT, DOCX, DOC, HTML, RTF, and Markdown with seamless format detection
👄 Modular TTS System	Edge TTS (default) and Kokoro TTS (local/offline) with extensible architecture for new models
🌍 Cross-Platform & Multilingual	Full support for macOS, Linux, Windows with 100+ languages and consistent global experience
🎛️ Speed Adjustment	Adjust text-to-speech playback speed from 1x to 3x for personalized listening experience
🎯 Precise Word Highlighting	Word-level highlighting synchronized with actual speech, improving focus and concentration
🌌 Rich Terminal UI	Clean, responsive interface with customizable color themes and full mouse & keyboard support
💾 Smart Persistence	Automatic progress saving, state restoration, and cross-session continuity for seamless reading
⚡️ Fast Navigation	Intuitive shortcuts, flexible controls, and optional smooth scrolling for efficient book navigation

---

🚀 Quick Start

Want to try Lue right away? Follow these simple steps:

# 1. Install FFmpeg (required for audio processing)
# macOS
brew install ffmpeg
# Ubuntu/Debian  
sudo apt install ffmpeg
# Windows: Download from ffmpeg.org and add to PATH

# 2. Install the latest version from PyPI
pip install lue-reader

# 3. Start reading!
lue path/to/your/book.epub 

📝 Note: Quick start uses Edge TTS (requires internet). For offline capabilities, see full installation.

---

📦 Installation

Prerequisites

Core Requirements

• FFmpeg - Audio processing (required)

Optional Dependencies

• espeak - Kokoro TTS support
• antiword - .doc file support

macOS (Homebrew)

brew install ffmpeg
# Optional
brew install espeak antiword

Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg
# Optional  
sudo apt install espeak antiword

Windows

Download FFmpeg from ffmpeg.org and add to PATH.

Install Lue

Standard Installation

# 1. Clone repository
git clone https://github.com/superstarryeyes/lue.git
cd lue

# 2. Install dependencies
pip install -r requirements.txt

# 3. Install Lue
pip install .

Enable Kokoro TTS (Optional)

For local/offline TTS capabilities:

# 1. Edit requirements.txt - uncomment Kokoro packages:
kokoro>=0.9.4
soundfile>=0.13.1
huggingface-hub>=0.34.4

# 2. Install PyTorch
# CPU version:
pip install torch torchvision torchaudio
# GPU version (CUDA):
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 3. Install updated requirements
pip install -r requirements.txt

# 4. Install Lue
pip install .

---

💻 Usage

Basic Commands

# Start with default TTS
lue path/to/your/book.epub

# Launch without arguments to open the last book you were reading
lue

# Use specific TTS model (edge/kokoro/none) 
lue --tts kokoro path/to/your/book.epub

# Use a specific voice (full list at VOICES.md)
lue --voice "en-US-AriaNeural" path/to/your/book.epub

# Set the speech speed (e.g., 1.5x)
lue --speed 1.5 path/to/your/book.epub

# Specify a language code if needed
lue --lang a path/to/your/book.epub

# Seconds of overlap between sentences
lue --over 0.2 path/to/your/book.epub

# Enable PDF cleaning filter (removes page numbers, headers and footnotes)
lue --filter path/to/your/book.pdf

# View available options
lue --help

Keyboard Controls

Key Binding	Action Description
q	Quit the application and save current reading progress automatically
p	Pause or resume the text-to-speech audio playback
a	Toggle auto-scroll mode to automatically advance during TTS playback
t	Select and highlight the top sentence of the current visible page
h / l	Move the reading line to the previous or next paragraph in the document
j / k	Move the reading line to the previous or next sentence in the document
i / m	Jump up or down by full pages for rapid navigation through longer documents
u / n	Scroll up or down by smaller increments for fine-grained position control
y / b	Jump directly to the beginning or end of the document for quick navigation
, / .	Decrease or increase text-to-speech playback speed (1x to 3x)
s / w	Toggle sentence highlighting or word highlighting on/off

Mouse Controls

• 🖱️ Click - Jump to sentence
• 🔄 Scroll - Navigate content
• 📍 Progress bar click - Jump to position

---

🧩 Development

Interested in extending Lue?

Check out the Developer Guide for instructions on adding new TTS models and contributing to the project.

Data Storage

Reading Progress:

• macOS: ~/Library/Application Support/lue/
• Linux: ~/.local/share/lue/
• Windows: C:\Users\<User>\AppData\Local\lue\

Error Logs:

• macOS: ~/Library/Logs/lue/error.log
• Linux: ~/.cache/lue/log/error.log
• Windows: C:\Users\<User>\AppData\Local\lue\Logs\error.log

---

📄 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

---

🛠️ Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Made with 💖 for CLI enthusiasts and bookworms

⭐ Star this repo if you find it useful!