lue-reader 0.5.0

---

Features

Feature	Description
Multi-Format Support	Support for EPUB, PDF, TXT, DOCX, 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 (via WSL) with 100+ languages and consistent global experience
Speed Adjustment	Adjust text-to-speech playback speed from 1x to 3x for personalized listening experience
Auto-Scroll & Precise Word Highlighting	Automatic scrolling and word-level highlighting synchronized with actual speech, improving focus and concentration
Smart Persistence	Automatic progress saving, state restoration, and cross-session continuity for seamless reading
Fast Navigation	Intuitive shortcuts, mouse support, smooth scrolling and chapters list for fast navigation.
Extensive Customization	Fully customizable keyboard layouts (including Vim-style bindings), adjustable UI elements, colors, and display modes

---

Quick Start (macOS and Linux)

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

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

# 3. Practice using Lue with the navigation guide
lue --guide

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

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

---

Installation (macOS, Linux and Windows)

Prerequisites

Core Requirements

• FFmpeg - Audio processing (required)

Optional Dependencies

• espeak - Kokoro TTS support

macOS (Homebrew)

brew install ffmpeg
# Optional
brew install espeak

Ubuntu/Debian

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

Arch Linux (AUR)

# Using yay
yay -S lue-reader-git

# Or using paru
paru -S lue-reader-git

Windows

# 1. Install WSL
# Open PowerShell as Administrator:
wsl --install

# 2. Restart your PC if prompted, then launch Ubuntu from Start Menu

# 3. Inside Ubuntu terminal:
sudo apt update && sudo apt upgrade -y
sudo apt install ffmpeg python3 python3-pip -y
# Optional  
sudo apt install espeak

Install Lue

Standard Installation

# 1. Clone repository
git clone https://github.com/paulilaaso/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

# Practice Lue default keys with the navigation guide
lue --guide

# View available command line options
lue --help

# 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, default: 10% (0.1) from both bottom and top of the page)
lue --filter path/to/your/book.pdf

# Set custom PDF filter margins (0.0-1.0, where 0.1 = 10% of page)
lue --filter 0.15 path/to/your/book.pdf          # Both margins to 15%
lue --filter 0.12 0.20 path/to/your/book.pdf     # Header 12%, footnote 20%

# Use the Vim keyboard layout
lue --keys vim path/to/your/book.epub

# Start in a specific visual layout mode: 0=minimal, 1=medium, 2=full, 3=speed reading
lue --mode 0 path/to/your/book.epub
lue -m 1 path/to/your/book.epub
lue -m 2 path/to/your/book.epub
lue -m 3 path/to/your/book.epub

Keyboard Controls (Default)

Mouse Controls

• Click - Jump to sentence
• Scroll - Navigate content
• Progress bar click - Jump to position

Customize

UI Modes

Lue offers four UI complexity modes that you can cycle through using the v key, set as your default in the config.py file, or choose at launch with -m / --mode:

• Mode 0 (Minimal) - Clean text-only display with no borders or UI elements
• Mode 1 (Medium) - Displays a top title bar with progress information and borders
• Mode 2 (Full) - Full UI with both top title bar and bottom control information
• Mode 3 (Speed Reading) - Single-word speed-reading display

Additionally, Lue provides customizable word-level and sentence-level highlighting that can be adjusted to suit your reading preferences. You can cycle through different highlighting modes using the w and s keys. These highlighting settings can also be configured as defaults in the config.py file.

Keyboard Layouts

Lue comes with two built-in keyboard layouts that can be set using -k/--key command line option or set as your default in the config.py file. You can create your own keyboard layout by copying and modifying one of the existing layout files:

• Default Layout - keys_default.json - Standard keyboard layout
• Vim Layout - keys_vim.json - Vim-style keyboard layout
• Custom Layout - Customize your own navigation keys by creating your own keyboard layout json file. Each command can accept a single key (e.g., "play_pause": "p") or multiple keys as an array (e.g., "play_pause": ["p", " "]).

Color Themes

Lue allows you to customize the color theme, visual icons/symbols and all ui elements of the interface by modifying the classes in ui.py. Create your own theme or choose one of the three themes that come with the default installation.

• Default Theme - The default colorful theme with various colors for different UI elements
• Black Theme - A dark monochrome theme that's suitable for bright backgrounds
• White Theme - A light monochrome theme that's suitable for dark backgrounds

---

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 (WSL): ~/.local/share/lue/ (within WSL filesystem)

Error Logs:

• macOS: ~/Library/Logs/lue/error.log
• Linux: ~/.cache/lue/log/error.log
• Windows (WSL): ~/.cache/lue/log/error.log (within WSL filesystem)

---

License

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

---