{"id":30348109,"url":"https://github.com/rudra-mondal/aperture-epub-reader","last_synced_at":"2025-08-18T17:37:41.990Z","repository":{"id":307666984,"uuid":"1030188489","full_name":"rudra-mondal/aperture-epub-reader","owner":"rudra-mondal","description":"🚀 Aperture is a modern, feature-rich desktop EPUB reader built with Python 🐍 and PyQt6. It focuses on a clean reading experience ✨ and powerful, integrated Kokoro Text-to-Speech (TTS) capabilities 🗣️🔊","archived":false,"fork":false,"pushed_at":"2025-08-01T12:01:57.000Z","size":936,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-01T14:35:03.511Z","etag":null,"topics":["aperture-book-reader","book-reader","epub","epub-reader","gui","kokoro","kokoro-82m","kokoro-tts","pyqt6","text-to-speech"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rudra-mondal.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}},"created_at":"2025-08-01T08:21:06.000Z","updated_at":"2025-08-01T12:02:01.000Z","dependencies_parsed_at":"2025-08-01T14:35:05.304Z","dependency_job_id":"dd372f6c-33ce-46b6-a4f6-a0719d7bb686","html_url":"https://github.com/rudra-mondal/aperture-epub-reader","commit_stats":null,"previous_names":["rudra-mondal/aperture-epub-reader"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rudra-mondal/aperture-epub-reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudra-mondal%2Faperture-epub-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudra-mondal%2Faperture-epub-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudra-mondal%2Faperture-epub-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudra-mondal%2Faperture-epub-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rudra-mondal","download_url":"https://codeload.github.com/rudra-mondal/aperture-epub-reader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudra-mondal%2Faperture-epub-reader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271032016,"owners_count":24687981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["aperture-book-reader","book-reader","epub","epub-reader","gui","kokoro","kokoro-82m","kokoro-tts","pyqt6","text-to-speech"],"created_at":"2025-08-18T17:37:38.467Z","updated_at":"2025-08-18T17:37:41.948Z","avatar_url":"https://github.com/rudra-mondal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg width=\"128\" height=\"128\" alt=\"Aperture logo\" src=\"https://github.com/user-attachments/assets/ca4671d7-e745-4efd-9e88-2911afe9def9\" /\u003e\u003c/p\u003e\n\n# Aperture EPUB Reader\n\n**Aperture is a modern, feature-rich desktop EPUB reader built with Python and PyQt6, focusing on a clean reading experience and powerful, integrated [Kokoro](https://github.com/hexgrad/kokoro) Text-to-Speech (TTS) capabilities.**\n\nAperture allows you to manage a local library of EPUB files, read them in a beautifully styled, distraction-free view, and listen to your books with high-quality, natural-sounding voices. Its core strength lies in its intelligent TTS engine that highlights text as it's spoken, providing an immersive read-aloud experience.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![PyQt6](https://img.shields.io/badge/Qt-PyQt6-green.svg)](https://riverbankcomputing.com/software/pyqt/)\n\n---\n\n\u003ch3 align=\"center\"\u003e\u003ci\u003e👇 Here is a quick look 👇\u003c/i\u003e\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"800\" alt=\"Screenshot 2025-08-01 175219\" src=\"https://github.com/user-attachments/assets/36f94e76-79a2-43b4-b756-28a16ee62117\" /\u003e\n\u003c/p\u003e\n\n\u003ch4 align=\"center\"\u003e\u003ci\u003eAperture's main reading interface\u003c/i\u003e\u003c/h4\u003e\n\n## ✨ Key Features\n\nAperture is more than just a file viewer; it's a complete reading environment.\n\n#### 📚 Library Management\n- **Persistent Library:** Your collection of books is saved locally in a `library.json` file, so they're always there when you open the app.\n- **Easy Import:** Add new `.epub` files to your library with a simple file dialog.\n- **Progress Saving:** Aperture automatically remembers the last chapter you were reading for each book and returns you to it.\n\n#### 📖 Core Reading Experience\n- **Clean, Customizable UI:** A clutter-free reading pane with custom styling for comfortable, long-form reading.\n- **Table of Contents (TOC):** Easily navigate your book with a clickable, hierarchical TOC.\n- **Chapter Navigation:** Move between chapters using \"Next\" and \"Previous\" buttons or the `Left` and `Right` arrow keys.\n- **Image \u0026 Link Handling:**\n    - Properly displays embedded images from the EPUB file.\n    - Internal links (e.g., footnotes) navigate within the app.\n    - External web links open securely in your system's default browser.\n\n#### 🔊 Advanced Text-to-Speech (TTS)\n- **High-Quality Voices:** Powered by the `kokoro-tts` library, offering a selection of natural-sounding male and female voices (US \u0026 UK accents).\n- **Real-time Sentence Highlighting:** The exact sentence being read is highlighted in the reader view, helping you follow along.\n- **Smooth Scrolling:** The view automatically scrolls to keep the highlighted sentence in focus.\n- **Playback Controls:** Full control with **Play/Pause/Resume** and **Stop** functionality.\n- **Adjustable Speed:** Fine-tune the reading speed from 0.5x to 2.0x to match your preference.\n\n#### 🧠 Smart Content Handling\n- **Intelligent Text Preparation:** Before TTS, the text is processed for better pronunciation:\n    - **Links:** URLs like `https://example.com` are read as \"example dot com\".\n    - **Acronyms:** Common acronyms (e.g., NASA, FBI) are preserved, while other all-caps phrases are converted to title case to avoid unnatural shouting.\n    - **Special Characters:** Symbols like `\u003e` or `-` are verbalized (e.g., \"is greater than\", \"minus\").\n- **Robust \u0026 Responsive:** TTS processing runs in a separate thread, ensuring the application UI remains fast and responsive at all times, even when generating audio for long chapters.\n\n---\n\n## 🛠️ Installation\n\nFollow these steps to get Aperture running on your local machine.\n\n#### Prerequisites\n- **Python 3.9+**\n- **Git**\n\n#### 1. Clone the Repository\nFirst, clone the project from GitHub:\n```bash\ngit clone https://github.com/rudra-mondal/aperture-epub-reader.git\ncd aperture-epub-reader\n```\n\n#### 2. Create a Virtual Environment (Recommended)\nIt's best practice to create a virtual environment to manage project dependencies.\n```bash\n# On macOS and Linux\npython3 -m venv venv\nsource venv/bin/activate\n\n# On Windows\npython -m venv venv\n.\\venv\\Scripts\\activate\n```\n\n#### 3. Install Dependencies\nInstall all the required Python libraries using the `requirements.txt` file.\n\n```bash\npip install -r requirements.txt\n```\n\u003e **Note on PyTorch:** The `kokoro-tts` library depends on PyTorch. The command above will install the standard CPU version. If you have a compatible NVIDIA GPU and want to leverage it, you may need to install a specific version of PyTorch by following the official instructions at [pytorch.org](https://pytorch.org/get-started/locally/).\n\n---\n\n## 🚀 Usage\n\n1.  **Run the application:**\n    ```bash\n    python main.py\n    ```\n\n2.  **Add a Book:**\n    - On the \"My Library\" screen, click the \"Add Book to Library\" button.\n    - Select a `.epub` file from your computer.\n\n3.  **Open a Book:**\n    - Double-click on any book title in your library to open the reading view.\n\n4.  **Read and Navigate:**\n    - Use the Table of Contents on the left to jump to specific chapters.\n    - Use the \"Next\" / \"Previous\" buttons or the `Left` / `Right` arrow keys to move between chapters.\n\n5.  **Use Text-to-Speech:**\n    - **Select Voice \u0026 Speed:** Choose your desired voice and playback speed from the control bar at the bottom.\n    - **▶ Read Aloud:** Click this to start the TTS. The button will change to \"❚❚ Pause\".\n    - **❚❚ Pause / ▶ Resume:** Click to pause or resume playback.\n    - **■ Stop:** Click to stop playback completely and reset the TTS.\n\n---\n\n## 🔧 Technical Deep Dive\n\n- **Framework:** The application is built with **PyQt6**, a comprehensive set of Python bindings for Qt v6.\n- **UI Structure:**\n    - A `QStackedWidget` is used to switch between the main library view and the reader view.\n    - The reader view uses a `QSplitter` to provide a resizable pane for the TOC and the content.\n- **EPUB Parsing:** The **`ebooklib`** library is used to parse `.epub` files, extract content, metadata, images, and the table of contents.\n- **Content Rendering:**\n    - Chapter content (XHTML) is rendered in a **`QWebEngineView`** (based on the Chromium engine).\n    - Before rendering, the HTML is processed with **`BeautifulSoup4`** to:\n        - Inject custom CSS for styling.\n        - Embed images as base64 data URIs to make them self-contained.\n        - Wrap each sentence in a `\u003cspan id=\"tts-sentence-X\"\u003e...\u003c/span\u003e` tag. This ID is the key to enabling the real-time highlighting feature.\n- **TTS Architecture (Producer-Consumer Model):**\n    - To prevent the UI from freezing during audio generation, TTS operates on a background `QThread`.\n    - **`TTSWorker` (Producer):** This object runs on the background thread. It iterates through the prepared text chunks, uses `kokoro-tts` to generate audio data, and puts the audio (`numpy` array) and its corresponding sentence ID into a shared `queue.Queue`.\n    - **`TTSWorker` (Consumer):** The main loop of the worker's `run` method retrieves audio chunks from the queue. It emits a signal to the main thread to highlight the new sentence ID, then plays the audio using **`sounddevice`**. This model ensures a smooth, continuous stream of audio and highlighting.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! If you have ideas for new features, bug fixes, or improvements, please feel free to:\n1.  **Fork** the repository.\n2.  Create a new **branch** (`git checkout -b feature/YourAmazingFeature`).\n3.  **Commit** your changes (`git commit -m 'Add some AmazingFeature'`).\n4.  **Push** to the branch (`git push origin feature/YourAmazingFeature`).\n5.  Open a **Pull Request**.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\nThis project would not be possible without the incredible open-source libraries it's built upon:\n- [PyQt6](https://riverbankcomputing.com/software/pyqt/)\n- [kokoro-tts](https://github.com/TaylorAI/kokoro-tts)\n- [ebooklib](https://github.com/aerkalov/ebooklib)\n- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/)\n- [NumPy](https://numpy.org/)\n- [SoundDevice](https://python-sounddevice.readthedocs.io/)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frudra-mondal%2Faperture-epub-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frudra-mondal%2Faperture-epub-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frudra-mondal%2Faperture-epub-reader/lists"}