{"id":30412159,"url":"https://github.com/superstarryeyes/lue","last_synced_at":"2026-02-19T07:01:31.583Z","repository":{"id":310230190,"uuid":"1039114099","full_name":"superstarryeyes/lue","owner":"superstarryeyes","description":"Terminal eBook Reader with Audiobook-Quality Text-to-Speech — Supports EPUB, PDF, DOCX, HTML, RTF, TXT, and MD.","archived":false,"fork":false,"pushed_at":"2025-12-15T19:12:26.000Z","size":3810,"stargazers_count":644,"open_issues_count":1,"forks_count":23,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-12-19T02:19:33.337Z","etag":null,"topics":["book","cli","docx","ebook","epub","modular","pdf","reader","terminal","text-to-speech","tts","tui","txt","voice"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/superstarryeyes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-16T14:07:49.000Z","updated_at":"2025-12-18T18:26:58.000Z","dependencies_parsed_at":"2025-08-16T17:40:34.866Z","dependency_job_id":"1033da69-ef32-4a4c-a697-6a718bfef456","html_url":"https://github.com/superstarryeyes/lue","commit_stats":null,"previous_names":["superstarryeyes/lue"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/superstarryeyes/lue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstarryeyes%2Flue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstarryeyes%2Flue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstarryeyes%2Flue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstarryeyes%2Flue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superstarryeyes","download_url":"https://codeload.github.com/superstarryeyes/lue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstarryeyes%2Flue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29605798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T06:47:36.664Z","status":"ssl_error","status_checked_at":"2026-02-19T06:45:47.551Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["book","cli","docx","ebook","epub","modular","pdf","reader","terminal","text-to-speech","tts","tui","txt","voice"],"created_at":"2025-08-22T02:01:27.081Z","updated_at":"2026-02-19T07:01:31.578Z","avatar_url":"https://github.com/superstarryeyes.png","language":"Python","funding_links":[],"categories":["Python","网站生成与排版"],"sub_categories":["电子书"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://github.com/superstarryeyes/lue/blob/main/images/lue-icon.png?raw=true\" alt=\"Lue Icon\" width=\"35%\" /\u003e\n\n### Lue - Terminal eBook Reader with Text-to-Speech\n[![License: GPL v3+](https://img.shields.io/badge/License-GPLv3+-86c9fa.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python](https://img.shields.io/badge/python-3.10+-86c9fa.svg)](https://www.python.org/downloads/)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows%20(WSL)-86c9fa)](https://github.com/superstarryeyes/lue)\n[![Terminal](https://img.shields.io/badge/interface-terminal-86c9fa.svg)](https://github.com/superstarryeyes/lue)\n[![Discord](https://img.shields.io/badge/Discord-Join%20our%20Community-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/z8sE2gnMNk)\n\n[Features](#-features) • [Quick Start](#-quick-start-macos-and-linux) • [Installation](#-installation-macos-linux-and-windows) • [Usage](#-usage) • [Customize](#️-customize) • [Development](#-development)\n\n\u003cimg src=\"https://github.com/superstarryeyes/lue/blob/main/images/lue-screenshot.gif\" alt=\"Lue Screenshot\" width=\"100%\" /\u003e\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n| **Feature**                             | **Description**                                                                                |\n| --------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| **📖 Multi-Format Support**             | Support for EPUB, PDF, TXT, DOCX, DOC, HTML, RTF, and Markdown with seamless format detection  |\n| **👄 Modular TTS System**               | Edge TTS (default) and Kokoro TTS (local/offline) with extensible architecture for new models  |\n| **🌍 Cross-Platform \u0026 Multilingual**    | Full support for macOS, Linux, Windows (via WSL) with 100+ languages and consistent global experience    |\n| **🎛️ Speed Adjustment**                 | Adjust text-to-speech playback speed from 1x to 3x for personalized listening experience       |\n| **🎯 Auto-Scroll \u0026 Precise Word Highlighting**        | Automatic scrolling and word-level highlighting synchronized with actual speech, improving focus and concentration     |\n| **💾 Smart Persistence**                | Automatic progress saving, state restoration, and cross-session continuity for seamless reading|\n| **⚡️ Fast Navigation**                  | Intuitive shortcuts, flexible controls, mouse support and optional smooth scrolling for efficient book navigation     |\n| **⚙️ Extensive Customization**          | Fully customizable keyboard layouts (including Vim-style bindings), adjustable UI elements, colors, and display modes|\n\n---\n\n## 🚀 Quick Start (macOS and Linux)\n\n\u003e **Want to try Lue right away?** Follow these simple steps:\n\n```bash\n# 1. Install FFmpeg (required for audio processing)\n# macOS\nbrew install ffmpeg\n# Ubuntu/Debian  \nsudo apt install ffmpeg\n\n# 2. Install the latest version from PyPI\npip install lue-reader \n\n# 3. Practice using Lue with the navigation guide\nlue --guide\n\n# 4. Start reading!\nlue path/to/your/book.epub \n```\n\n\u003e **📝 Note:** Quick start uses Edge TTS (requires internet). For offline capabilities, see [full installation](#-installation-macos-linux-and-windows).\n\n---\n\n## 📦 Installation (macOS, Linux and Windows)\n\n### Prerequisites\n\n#### Core Requirements\n- **FFmpeg** - Audio processing (required)\n\n#### Optional Dependencies  \n- **espeak** - Kokoro TTS support\n\n#### macOS (Homebrew)\n```bash\nbrew install ffmpeg\n# Optional\nbrew install espeak\n```\n\n#### Ubuntu/Debian\n```bash\nsudo apt update \u0026\u0026 sudo apt install ffmpeg\n# Optional  \nsudo apt install espeak\n```\n\n#### Arch Linux (AUR)\n```bash\n# Using yay\nyay -S lue-reader-git\n\n# Or using paru\nparu -S lue-reader-git\n```\n\n#### Windows\n```bash\n# 1. Install WSL\n# Open PowerShell as Administrator:\nwsl --install\n\n# 2. Restart your PC if prompted, then launch Ubuntu from Start Menu\n\n# 3. Inside Ubuntu terminal:\nsudo apt update \u0026\u0026 sudo apt upgrade -y\nsudo apt install ffmpeg python3 python3-pip -y\n# Optional  \nsudo apt install espeak\n```\n\n### Install Lue\n\n#### Standard Installation\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/superstarryeyes/lue.git\ncd lue\n\n# 2. Install dependencies\npip install -r requirements.txt\n\n# 3. Install Lue\npip install .\n```\n\n#### Enable Kokoro TTS (Optional)\n\nFor local/offline TTS capabilities:\n\n```bash\n# 1. Edit requirements.txt - uncomment Kokoro packages:\nkokoro\u003e=0.9.4\nsoundfile\u003e=0.13.1\nhuggingface-hub\u003e=0.34.4\n\n# 2. Install PyTorch\n# CPU version:\npip install torch torchvision torchaudio\n# GPU version (CUDA):\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121\n\n# 3. Install updated requirements\npip install -r requirements.txt\n\n# 4. Install Lue\npip install .\n```\n\n---\n\n## 💻 Usage\n\n### Basic Commands\n\n```bash\n# Start with default TTS\nlue path/to/your/book.epub\n\n# Launch without arguments to open the last book you were reading\nlue\n\n# Practice Lue default keys with the navigation guide\nlue --guide\n\n# View available command line options\nlue --help\n\n# Use specific TTS model (edge/kokoro/none) \nlue --tts kokoro path/to/your/book.epub\n\n# Use a specific voice (full list at VOICES.md)\nlue --voice \"en-US-AriaNeural\" path/to/your/book.epub\n\n# Set the speech speed (e.g., 1.5x)\nlue --speed 1.5 path/to/your/book.epub\n\n# Specify a language code if needed\nlue --lang a path/to/your/book.epub\n\n# Seconds of overlap between sentences\nlue --over 0.2 path/to/your/book.epub\n\n# Enable PDF cleaning filter (removes page numbers, headers and footnotes, default: 10% (0.1) from both bottom and top of the page)\nlue --filter path/to/your/book.pdf\n\n# Set custom PDF filter margins (0.0-1.0, where 0.1 = 10% of page)\nlue --filter 0.15 path/to/your/book.pdf          # Both margins to 15%\nlue --filter 0.12 0.20 path/to/your/book.pdf     # Header 12%, footnote 20%\n\n# Use the Vim keyboard layout\nlue --keys vim path/to/your/book.epub\n\n```\n\n### Keyboard Controls (Default)\n\n\u003cdiv align=\"center\"\u003e\n\n| **Key Binding**                         | **Action Description**                                                                         |\n| --------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `q`                                     | Quit the application and save current reading progress automatically                           |\n| `p`                                     | Pause or resume the text-to-speech audio playback                                              |\n| `a`                                     | Toggle auto-scroll mode to automatically advance during TTS playback                           |\n| `t`                                     | Select and highlight the top sentence of the current visible page                              |\n| `h` / `l`                               | Move the reading line to the previous or next paragraph in the document                        |\n| `j` / `k`                               | Move the reading line to the previous or next sentence in the document                         |\n| `i` / `m`                               | Jump up or down by full pages for rapid navigation through longer documents                    |\n| `u` / `n`                               | Scroll up or down by smaller increments for fine-grained position control                      |\n| `y` / `b`                               | Jump directly to the beginning or end of the document for quick navigation                     |\n| `r`                                     | Open the recent books menu to quickly switch between 5 last read books                       |\n| `,` / `.`                               | Decrease or increase text-to-speech playback speed (1x to 3x)                                  |\n| `s` / `w`                               | Toggle sentence highlighting or word highlighting on/off                                       |\n| `v`                                     | Cycle through UI complexity modes (Minimal, Medium, Full)                                      |\n\n\u003c/div\u003e\n\n### Mouse Controls\n\n- **🖱️ Click** - Jump to sentence\n- **🔄 Scroll** - Navigate content  \n- **📍 Progress bar click** - Jump to position\n\n## ⚙️ Customize\n\n### UI Modes\n\nLue offers three UI complexity modes that you can cycle through using the `v` key or set as your default in the [config.py](lue/config.py) file:\n\n- **Mode 0 (Minimal)** - Clean text-only display with no borders or UI elements\n- **Mode 1 (Medium)** - Displays a top title bar with progress information and borders\n- **Mode 2 (Full)** - Full UI with both top title bar and bottom control information\n\nAdditionally, 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](lue/config.py) file.\n\n### Keyboard Layouts\n\nLue 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](lue/config.py) file. You can create your own keyboard layout by copying and modifying one of the existing layout files:\n\n- **Default Layout** - [keys_default.json](lue/keys_default.json) - Standard keyboard layout\n- **Vim Layout** - [keys_vim.json](lue/keys_vim.json) - Vim-style keyboard layout\n- **Custom Layout** - Customize your own navigation keys by creating your own keyboard layout json file\n\n### Color Themes\n\nLue allows you to customize the color theme, visual icons/symbols and all ui elements of the interface by modifying the classes in [ui.py](lue/ui.py). Create your own theme or choose one of the three themes that come with the default installation.\n\n- **Default Theme** - The default colorful theme with various colors for different UI elements\n- **Black Theme** - A dark monochrome theme that's suitable for bright backgrounds\n- **White Theme** - A light monochrome theme that's suitable for dark backgrounds\n\n---\n\n## 🧩 Development\n\n\u003e **Interested in extending Lue?** \n\nCheck out the [Developer Guide](DEVELOPER.md) for instructions on adding new TTS models and contributing to the project.\n\n### Data Storage\n\n**Reading Progress:**\n- **macOS:** `~/Library/Application Support/lue/`\n- **Linux:** `~/.local/share/lue/`  \n- **Windows (WSL):** `~/.local/share/lue/` (within WSL filesystem)\n\n**Error Logs:**\n- **macOS:** `~/Library/Logs/lue/error.log`\n- **Linux:** `~/.cache/lue/log/error.log`\n- **Windows (WSL):** `~/.cache/lue/log/error.log` (within WSL filesystem)\n\n---\n\n## 🛠️ Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\nJoin our Discord community for discussions, support and collaboration for creating modules for new TTS models!\n\n[![Join our Discord](https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord\u0026style=for-the-badge)](https://discord.gg/z8sE2gnMNk)\n\n---\n\n## 📄 License\n\nThis project is licensed under the **GPL-3.0-or-later License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca title=\"This tool is Tool of The Week on Terminal Trove, The $HOME of all things in the terminal\" href=\"https://terminaltrove.com/\"\u003e\u003cimg src=\"https://cdn.terminaltrove.com/media/badges/tool_of_the_week/png/terminal_trove_tool_of_the_week_gold_transparent.png\" width=\"40%\" alt=\"Terminal Trove Tool of The Week\" /\u003e\u003c/a\u003e\n\n*Made with 💖 for CLI enthusiasts and bookworms*\n\n**⭐ Star this repo** if you find it useful!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperstarryeyes%2Flue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperstarryeyes%2Flue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperstarryeyes%2Flue/lists"}