---

✨ 功能

功能	描述
📖 多格式支持	支持 EPUB、PDF、TXT、DOCX、DOC、HTML、RTF 和 Markdown 格式，自动检测文件类型
👄 模块化TTS系统	Edge TTS（默认）和 Kokoro TTS（本地/离线）支持，可扩展架构适配新模型
🌍 跨平台与多语言	完全支持 macOS、Linux、Windows（通过 WSL），支持 100+ 种语言并提供一致的全球体验
🎛️ 速度调节	文本转语音播放速度可在 1x 到 3x 之间调节，提供个性化听读体验
🎯 自动滚动与精准文字高亮	自动滚动与逐字高亮同步语音播放，提升专注力
💾 智能持久化	自动保存阅读进度、状态恢复和跨会话连续性，实现无缝阅读体验
⚡️ 快捷导航	直观快捷键、灵活控制、鼠标支持和可选平滑滚动，提升书籍导航效率
⚙️ 深度自定义	完全可定制键盘布局（包括 Vim 风格绑定）、界面元素、颜色和显示模式

---

🚀 快速开始 (macOS和Linux)

想立即体验 Lue？ 按照以下步骤操作：

# 1. 安装 FFmpeg（音频处理必需）
# macOS
brew install ffmpeg
# Ubuntu/Debian  
sudo apt install ffmpeg

# 2. 从 PyPI 安装最新版本
pip install lue-reader 

# 3. 使用导航指南练习操作
lue --guide

# 4. 开始阅读！
lue path/to/your/book.epub 

📝 注意： 快速开始使用 Edge TTS（需要联网）。如需离线功能，请参见完整安装指南。

---

📦 安装指南 (macOS, Linux 和 Windows)

基础依赖

核心要求

• FFmpeg - 音频处理（必需）

可选依赖

• espeak - Kokoro TTS 支持

macOS (Homebrew)

brew install ffmpeg
# 可选
brew install espeak

Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg
# 可选  
sudo apt install espeak

Arch Linux (AUR)

# 使用 yay
yay -S lue-reader-git

# 或使用 paru
paru -S lue-reader-git

Windows

# 1. 安装 WSL
# 以管理员身份打开 PowerShell：
wsl --install

# 2. 如果提示重启，重启后从开始菜单启动 Ubuntu

# 3. 在 Ubuntu 终端中执行：
sudo apt update && sudo apt upgrade -y
sudo apt install ffmpeg python3 python3-pip -y
# 可选  
sudo apt install espeak

安装 Lue

标准安装

# 1. 克隆仓库
git clone https://github.com/superstarryeyes/lue.git
cd lue

# 2. 安装依赖
pip install -r requirements.txt

# 3. 安装 Lue
pip install .

启用 Kokoro TTS (可选)

启用本地/离线 TTS 功能：

# 1. 编辑 requirements.txt - 取消注释 Kokoro 相关包：
kokoro>=0.9.4
soundfile>=0.13.1
huggingface-hub>=0.34.4

# 2. 安装 PyTorch
# CPU 版本：
pip install torch torchvision torchaudio
# GPU 版本（CUDA）：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 3. 安装更新后的依赖
pip install -r requirements.txt

# 4. 安装 Lue
pip install .

---

💻 使用方法

基础命令

# 使用默认 TTS 启动
lue path/to/your/book.epub

# 不带参数启动以打开上次阅读的书籍
lue

# 使用导航指南练习默认快捷键
lue --guide

# 查看可用命令行选项
lue --help

# 使用特定 TTS 模型（edge/kokoro/none） 
lue --tts kokoro path/to/your/book.epub

# 使用特定语音（完整列表见 VOICES.md）
lue --voice "en-US-AriaNeural" path/to/your/book.epub

# 设置语音速度（如 1.5x）
lue --speed 1.5 path/to/your/book.epub

# 指定语言代码（如需要）
lue --lang a path/to/your/book.epub

# 设置句子间重叠时长（秒）
lue --over 0.2 path/to/your/book.epub

# 启用 PDF 清理过滤器（移除页码、页眉和脚注，默认页面上下各 10% (0.1)）
lue --filter path/to/your/book.pdf

# 自定义 PDF 过滤器边距（0.0-1.0，0.1=页面的10%）
lue --filter 0.15 path/to/your/book.pdf          # 上下边距均设为 15%
lue --filter 0.12 0.20 path/to/your/book.pdf     # 页眉 12%，脚注 20%

# 使用 Vim 键盘布局
lue --keys vim path/to/your/book.epub

键盘控制（默认设置）

鼠标控制

• 🖱️ 点击 - 跳转到指定句子
• 🔄 滚动 - 浏览内容
• 📍 进度条点击 - 跳转到指定位置

⚙️ 自定义设置

UI模式

Lue提供三种UI复杂度模式，可通过v键循环切换，或在config.py文件中设置默认模式：

• 模式0（极简） - 简洁纯文本显示，无边框和UI元素
• 模式1（中等） - 显示顶部标题栏（含进度信息）和边框
• 模式2（完整） - 完整UI，包含顶部标题栏和底部控制信息

此外，Lue提供可自定义的单词级和句子级高亮功能，可通过s和w键切换不同高亮模式。这些设置也可在config.py文件中配置为默认设置。

键盘布局

Lue提供两种内置键盘布局，可通过-k/--key命令行参数设置，或在config.py文件中设置默认布局。您可通过复制并修改现有布局文件创建自定义布局：

• 默认布局（Default Layout） - keys_default.json - 标准键盘布局
• Vim布局（Vim Layout） - keys_vim.json - 类Vim风格键盘布局
• 自定义布局 - 通过创建自定义JSON文件配置导航键

颜色主题

通过修改lue/ui.py中的类定义，可自定义界面颜色主题、视觉图标/符号和所有UI元素。可选择默认安装的三种主题或创建自定义主题：

• 默认主题（Default Theme） - 默认多彩主题，不同UI元素使用不同颜色
• 黑色主题（Black Theme） - 适合明亮背景的深色单色主题
• 白色主题（White Theme） - 适合暗色背景的浅色单色主题

---

🧩 开发相关

有兴趣扩展Lue功能？

请查阅开发者指南，了解如何添加新TTS模型和参与项目贡献。

数据存储

阅读进度：

• macOS： ~/Library/Application Support/lue/
• Linux： ~/.local/share/lue/
• Windows (WSL)： ~/.local/share/lue/ (位于WSL文件系统内)

错误日志：

• macOS： ~/Library/Logs/lue/error.log
• Linux： ~/.cache/lue/log/error.log
• Windows (WSL)： ~/.cache/lue/log/error.log (位于WSL文件系统内)

---

🛠️ 贡献指南

欢迎任何形式的贡献！欢迎提交Pull Request。

加入我们的Discord社区讨论、获取支持，并协作开发新TTS模型模块！

---

📄 许可协议

本项目采用GPL-3.0-or-later许可证，详见LICENSE文件。

---

Lue 快速上手指南

🧰 环境准备

系统要求

• macOS (推荐10.15+)
• Linux (Ubuntu 20.04+/Debian 11+/Arch)
• Windows (通过WSL2，推荐安装Ubuntu发行版)

前置依赖

核心依赖

# macOS (Homebrew)
brew install ffmpeg

# Ubuntu/Debian (国内用户可替换为清华/阿里源)
sudo apt install ffmpeg

# Windows (WSL2内安装)
sudo apt install ffmpeg

可选依赖 (离线TTS)

# 安装 espeak (Kokoro TTS依赖)
sudo apt install espeak  # Ubuntu/Debian
brew install espeak      # macOS

国内加速提示：安装Python包时建议添加国内镜像源，例如：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...

---

📦 安装步骤

标准安装 (在线TTS)

# 安装Lue核心 (推荐国内镜像加速)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple lue-reader

# 验证安装
lue --version

完全安装 (含离线TTS)

# 1. 安装PyTorch (国内镜像加速)
pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple

# 2. 安装Lue并启用Kokoro
git clone https://github.com/superstarryeyes/lue.git
cd lue

# 3. 修改 requirements.txt 启用Kokoro模块 (取消注释对应行)

# 4. 安装依赖 (国内镜像加速)
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 安装Lue
pip install .

---

🚀 基本使用

启动导航教程

lue --guide  # 熟悉基础操作

打开电子书

# 使用默认在线TTS朗读
lue path/to/book.epub

# 使用离线Kokoro TTS
lue --tts kokoro path/to/book.epub

# 恢复上次阅读进度
lue

常用控制

# 播放/暂停
p

# 退出并保存进度
q

# 调整语速 (1.5x)
lue --speed 1.5 path/to/book.epub

# 切换UI模式 (最小/中等/完整界面)
v

提示：Windows用户需在WSL2终端中运行上述命令，推荐使用Windows Terminal或Alacritty等现代终端模拟器。