# SpeakUB 📚
A modern, feature-rich terminal EPUB reader with **Text-to-Speech** support, built with Rich/Textual for a beautiful CLI experience.
## ✨ Features
- 🎨 **Rich Terminal UI** - Beautiful interface with Rich and Textual
- 📖 **Full EPUB Support** - Handles EPUB 2 and EPUB 3 formats
- 🔊 **Text-to-Speech** - Built-in TTS using Microsoft Edge-TTS
- 📑 **Smart Navigation** - Table of contents with hierarchical chapters
- 💾 **Progress Tracking** - Automatically saves your reading position
- 🎯 **Seamless Reading** - Navigate between chapters without interruption
- 🖼️ **Image Support** - View embedded images (optional)
- ⌨️ **Keyboard Shortcuts** - Efficient navigation with familiar keys
- 🎛️ **TTS Controls** - Play, Pause, Stop with speed/volume control
## 🚀 Installation
### Quick Install
```bash
pip install speakub
```
### Development Install
```bash
git clone https://github.com/eyes1971/SpeakUB.git
cd SpeakUB
pip install -e .
```
### With TTS Support
```bash
pip install speakub[tts]
```
### With All Features
```bash
pip install speakub[all]
```
## 📋 Requirements
- Python 3.8+
- Terminal with Unicode support
### Optional Dependencies
- **TTS**: `edge-tts` and `pygame` for text-to-speech
- **Images**: `fabulous` and `Pillow` for image display
## 🎮 Usage
### Basic Usage
```bash
speakub book.epub
```
### Dump to Text
```bash
speakub book.epub --dump --cols 80
```
## ⌨️ Keyboard Shortcuts
### Global Controls
| Key | Action |
|-----|---------|
| `Esc` / `q` | Quit application |
| `Tab` | Switch focus between panels |
| `F1` | Toggle table of contents |
| `F2` | Toggle TTS panel |
### Table of Contents (TOC)
| Key | Action |
|-----|---------|
| `↑` / `↓` | Navigate chapters |
| `PgUp` / `PgDn` | Page up/down |
| `Enter` / `→` | Open chapter or expand group |
| `←` | Collapse group |
### Content Reading
| Key | Action |
|-----|---------|
| `↑` / `↓` | Scroll content (seamless across chapters) |
| `PgUp` / `PgDn` | Page up/down |
| `Home` / `End` | Go to start/end of chapter |
| `i` | Open images in browser (if available) |
### TTS Controls
| Key | Action |
|-----|---------|
| `Space` / `p` | Play/Pause |
| `s` | Stop |
| `+` / `=` | Increase volume |
| `-` | Decrease volume |
| `[` | Decrease speed |
| `]` | Increase speed |
| `←` / `→` | Navigate TTS controls |
## 🏗️ Architecture
```
speakub/
├── speakub/ # Main package
│ ├── core/ # Core functionality
│ │ ├── epub_parser.py # EPUB parsing
│ │ ├── content_renderer.py # HTML to text conversion
│ │ ├── chapter_manager.py # Chapter navigation
│ │ └── progress_tracker.py # Reading progress
│ ├── tts/ # Text-to-Speech
│ │ ├── engine.py # TTS abstraction
│ │ ├── edge_tts_provider.py # Edge-TTS implementation
│ │ └── audio_player.py # Audio playback
│ ├── ui/ # User interfaces
│ │ ├── ui_components.py # Rich/Textual UI components
│ │ └── widgets/ # Reusable components
│ ├── cli.py # Command-line interface
│ └── utils/ # Utility functions
├── tests/ # Test suite
├── tools/ # Development tools and scripts
└── docs/ # Documentation
```
## 🔊 Text-to-Speech Features
The TTS system provides:
- **Multiple Voices** - Support for various languages and voices
- **Speed Control** - Adjust playback speed (0.5x - 2.0x)
- **Volume Control** - Fine-tune audio levels
- **Chapter Navigation** - Skip to previous/next chapters
- **Progress Tracking** - Visual progress bar with time display
- **Background Processing** - Non-blocking audio synthesis
### TTS Panel Controls
```
┌──────────────────────────────────────────┐
│ TTS: PLAYING (Smooth) | 23% | Vol: 100% | Speed: +30% | Pitch: +0Hz │
└──────────────────────────────────────────┘
```
## 🛠️ Configuration
### Automatic Configuration
The reader automatically saves:
- Reading progress for each book
- Last position in each chapter
- TTS settings (volume, speed)
Progress is stored in `~/.speakub_progress.json`
### Manual Configuration
You can customize the reader's behavior through environment variables:
#### Display Settings
```bash
# Set default content width (default: 80)
export SPEAKUB_WIDTH=100
# Enable/disable trace logging
export SPEAKUB_TRACE=1
# Set maximum cache size for content rendering
export SPEAKUB_CACHE_SIZE=100
```
#### TTS Configuration
```bash
# Set default TTS voice
export SPEAKUB_VOICE="en-US-AriaRUS"
# Set default TTS speed (0.5-2.0)
export SPEAKUB_TTS_SPEED=1.2
# Set default TTS volume (0-100)
export SPEAKUB_TTS_VOLUME=80
```
#### Performance Tuning
```bash
# Set chapter cache size (default: 50)
export SPEAKUB_CHAPTER_CACHE=100
# Enable/disable background processing
export SPEAKUB_BACKGROUND=1
# Set polling frequency for UI updates (milliseconds)
export SPEAKUB_POLL_INTERVAL=100
```
### Configuration File
Create a configuration file at `~/.speakub_config.json`:
```json
{
"display": {
"width": 100,
"trace": false,
"cache_size": 100
},
"tts": {
"default_voice": "en-US-AriaRUS",
"speed": 1.2,
"volume": 80
},
"performance": {
"chapter_cache": 100,
"background_processing": true,
"poll_interval": 100
}
}
```
### Cache Management
The reader implements intelligent caching to improve performance:
- **Chapter Content Cache**: Stores parsed chapter content (LRU with 50 entries)
- **Width Calculation Cache**: Caches display width calculations (LRU with 100 entries)
- **Renderer Cache**: Caches HTML-to-text renderers by width
To clear all caches, delete the progress file:
```bash
rm ~/.speakub_progress.json
```
## 🔧 Development
### Setup Development Environment
```bash
git clone https://github.com/eyes1971/SpeakUB.git
cd SpeakUB
pip install -e .[dev]
pre-commit install
```
### Development Tools
The `tools/` directory contains helpful scripts for development and debugging:
```bash
# Check available TTS voices
python tools/check_voices.py
# Debug voice data structures
python tools/debug_voices.py
# Test TTS provider functionality
python tools/simple_test.py
# Interactive voice selector demo
python tools/voice_selector_demo.py
# Verify UI layout changes
python tools/simple_layout_check.py
```
See [tools/README.md](tools/README.md) for detailed information about each tool.
### Run Tests
```bash
pytest
```
### Code Formatting
```bash
black speakub/
isort speakub/
flake8 speakub/
```
### Type Checking
```bash
mypy speakub/
```
## 🤝 Contributing
Contributions are welcome! Please:
1. Fork the repository at [https://github.com/eyes1971/SpeakUB](https://github.com/eyes1971/SpeakUB)
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📧 Contact
- **Author**: Sam Weng
- **Email**: eyes1971@gmail.com
- **GitHub**: [https://github.com/eyes1971/SpeakUB](https://github.com/eyes1971/SpeakUB)
## 🙏 Acknowledgments
- **Rich** - For the beautiful terminal UI framework
- **Textual** - For the modern TUI components
- **BeautifulSoup** - For robust HTML parsing
- **Edge-TTS** - For high-quality text-to-speech
- **html2text** - For HTML to text conversion
## 🐛 Known Issues
- Image display requires `fabulous` and may not work in all terminals
- TTS seeking is not supported with the pygame audio backend
- Very large EPUB files may consume significant memory
## 📚 Similar Projects
- [epr](https://github.com/wustho/epr) - CLI EPUB reader
- [epub](https://github.com/rupa/epub) - Simple EPUB reader
---
**Happy Reading!** 📖✨
For more information, visit our [documentation](https://speakub.readthedocs.io/) or [report issues](https://github.com/eyes1971/SpeakUB/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "speakub",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "epub, ebook, reader, terminal, tts, text-to-speech",
"author": null,
"author_email": "Sam Weng <eyes1971@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/97/3f/89c465925dc97654743ea193fbb7980e51e52e102dd7b42917c24857277a/speakub-1.1.0.tar.gz",
"platform": null,
"description": "\n\n\n# SpeakUB \ud83d\udcda\n\nA modern, feature-rich terminal EPUB reader with **Text-to-Speech** support, built with Rich/Textual for a beautiful CLI experience.\n\n## \u2728 Features\n\n- \ud83c\udfa8 **Rich Terminal UI** - Beautiful interface with Rich and Textual\n- \ud83d\udcd6 **Full EPUB Support** - Handles EPUB 2 and EPUB 3 formats\n- \ud83d\udd0a **Text-to-Speech** - Built-in TTS using Microsoft Edge-TTS\n- \ud83d\udcd1 **Smart Navigation** - Table of contents with hierarchical chapters\n- \ud83d\udcbe **Progress Tracking** - Automatically saves your reading position\n- \ud83c\udfaf **Seamless Reading** - Navigate between chapters without interruption\n- \ud83d\uddbc\ufe0f **Image Support** - View embedded images (optional)\n- \u2328\ufe0f **Keyboard Shortcuts** - Efficient navigation with familiar keys\n- \ud83c\udf9b\ufe0f **TTS Controls** - Play, Pause, Stop with speed/volume control\n\n## \ud83d\ude80 Installation\n\n### Quick Install\n```bash\npip install speakub\n```\n\n### Development Install\n```bash\ngit clone https://github.com/eyes1971/SpeakUB.git\ncd SpeakUB\npip install -e .\n```\n\n### With TTS Support\n```bash\npip install speakub[tts]\n```\n\n### With All Features\n```bash\npip install speakub[all]\n```\n\n## \ud83d\udccb Requirements\n\n- Python 3.8+\n- Terminal with Unicode support\n\n### Optional Dependencies\n\n- **TTS**: `edge-tts` and `pygame` for text-to-speech\n- **Images**: `fabulous` and `Pillow` for image display\n\n## \ud83c\udfae Usage\n\n### Basic Usage\n```bash\nspeakub book.epub\n```\n\n### Dump to Text\n```bash\nspeakub book.epub --dump --cols 80\n```\n\n## \u2328\ufe0f Keyboard Shortcuts\n\n### Global Controls\n| Key | Action |\n|-----|---------|\n| `Esc` / `q` | Quit application |\n| `Tab` | Switch focus between panels |\n| `F1` | Toggle table of contents |\n| `F2` | Toggle TTS panel |\n\n### Table of Contents (TOC)\n| Key | Action |\n|-----|---------|\n| `\u2191` / `\u2193` | Navigate chapters |\n| `PgUp` / `PgDn` | Page up/down |\n| `Enter` / `\u2192` | Open chapter or expand group |\n| `\u2190` | Collapse group |\n\n### Content Reading\n| Key | Action |\n|-----|---------|\n| `\u2191` / `\u2193` | Scroll content (seamless across chapters) |\n| `PgUp` / `PgDn` | Page up/down |\n| `Home` / `End` | Go to start/end of chapter |\n| `i` | Open images in browser (if available) |\n\n### TTS Controls\n| Key | Action |\n|-----|---------|\n| `Space` / `p` | Play/Pause |\n| `s` | Stop |\n| `+` / `=` | Increase volume |\n| `-` | Decrease volume |\n| `[` | Decrease speed |\n| `]` | Increase speed |\n| `\u2190` / `\u2192` | Navigate TTS controls |\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\nspeakub/\n\u251c\u2500\u2500 speakub/ # Main package\n\u2502 \u251c\u2500\u2500 core/ # Core functionality\n\u2502 \u2502 \u251c\u2500\u2500 epub_parser.py # EPUB parsing\n\u2502 \u2502 \u251c\u2500\u2500 content_renderer.py # HTML to text conversion\n\u2502 \u2502 \u251c\u2500\u2500 chapter_manager.py # Chapter navigation\n\u2502 \u2502 \u2514\u2500\u2500 progress_tracker.py # Reading progress\n\u2502 \u251c\u2500\u2500 tts/ # Text-to-Speech\n\u2502 \u2502 \u251c\u2500\u2500 engine.py # TTS abstraction\n\u2502 \u2502 \u251c\u2500\u2500 edge_tts_provider.py # Edge-TTS implementation\n\u2502 \u2502 \u2514\u2500\u2500 audio_player.py # Audio playback\n\u2502 \u251c\u2500\u2500 ui/ # User interfaces\n\u2502 \u2502 \u251c\u2500\u2500 ui_components.py # Rich/Textual UI components\n\u2502 \u2502 \u2514\u2500\u2500 widgets/ # Reusable components\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 utils/ # Utility functions\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 tools/ # Development tools and scripts\n\u2514\u2500\u2500 docs/ # Documentation\n```\n\n## \ud83d\udd0a Text-to-Speech Features\n\nThe TTS system provides:\n\n- **Multiple Voices** - Support for various languages and voices\n- **Speed Control** - Adjust playback speed (0.5x - 2.0x)\n- **Volume Control** - Fine-tune audio levels\n- **Chapter Navigation** - Skip to previous/next chapters\n- **Progress Tracking** - Visual progress bar with time display\n- **Background Processing** - Non-blocking audio synthesis\n\n### TTS Panel Controls\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 TTS: PLAYING (Smooth) | 23% | Vol: 100% | Speed: +30% | Pitch: +0Hz \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## \ud83d\udee0\ufe0f Configuration\n\n### Automatic Configuration\n\nThe reader automatically saves:\n- Reading progress for each book\n- Last position in each chapter\n- TTS settings (volume, speed)\n\nProgress is stored in `~/.speakub_progress.json`\n\n### Manual Configuration\n\nYou can customize the reader's behavior through environment variables:\n\n#### Display Settings\n```bash\n# Set default content width (default: 80)\nexport SPEAKUB_WIDTH=100\n\n# Enable/disable trace logging\nexport SPEAKUB_TRACE=1\n\n# Set maximum cache size for content rendering\nexport SPEAKUB_CACHE_SIZE=100\n```\n\n#### TTS Configuration\n```bash\n# Set default TTS voice\nexport SPEAKUB_VOICE=\"en-US-AriaRUS\"\n\n# Set default TTS speed (0.5-2.0)\nexport SPEAKUB_TTS_SPEED=1.2\n\n# Set default TTS volume (0-100)\nexport SPEAKUB_TTS_VOLUME=80\n```\n\n#### Performance Tuning\n```bash\n# Set chapter cache size (default: 50)\nexport SPEAKUB_CHAPTER_CACHE=100\n\n# Enable/disable background processing\nexport SPEAKUB_BACKGROUND=1\n\n# Set polling frequency for UI updates (milliseconds)\nexport SPEAKUB_POLL_INTERVAL=100\n```\n\n### Configuration File\n\nCreate a configuration file at `~/.speakub_config.json`:\n\n```json\n{\n \"display\": {\n \"width\": 100,\n \"trace\": false,\n \"cache_size\": 100\n },\n \"tts\": {\n \"default_voice\": \"en-US-AriaRUS\",\n \"speed\": 1.2,\n \"volume\": 80\n },\n \"performance\": {\n \"chapter_cache\": 100,\n \"background_processing\": true,\n \"poll_interval\": 100\n }\n}\n```\n\n### Cache Management\n\nThe reader implements intelligent caching to improve performance:\n\n- **Chapter Content Cache**: Stores parsed chapter content (LRU with 50 entries)\n- **Width Calculation Cache**: Caches display width calculations (LRU with 100 entries)\n- **Renderer Cache**: Caches HTML-to-text renderers by width\n\nTo clear all caches, delete the progress file:\n```bash\nrm ~/.speakub_progress.json\n```\n\n## \ud83d\udd27 Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/eyes1971/SpeakUB.git\ncd SpeakUB\npip install -e .[dev]\npre-commit install\n```\n\n### Development Tools\nThe `tools/` directory contains helpful scripts for development and debugging:\n\n```bash\n# Check available TTS voices\npython tools/check_voices.py\n\n# Debug voice data structures\npython tools/debug_voices.py\n\n# Test TTS provider functionality\npython tools/simple_test.py\n\n# Interactive voice selector demo\npython tools/voice_selector_demo.py\n\n# Verify UI layout changes\npython tools/simple_layout_check.py\n```\n\nSee [tools/README.md](tools/README.md) for detailed information about each tool.\n\n### Run Tests\n```bash\npytest\n```\n\n### Code Formatting\n```bash\nblack speakub/\nisort speakub/\nflake8 speakub/\n```\n\n### Type Checking\n```bash\nmypy speakub/\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository at [https://github.com/eyes1971/SpeakUB](https://github.com/eyes1971/SpeakUB)\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udce7 Contact\n\n- **Author**: Sam Weng\n- **Email**: eyes1971@gmail.com\n- **GitHub**: [https://github.com/eyes1971/SpeakUB](https://github.com/eyes1971/SpeakUB)\n\n## \ud83d\ude4f Acknowledgments\n\n- **Rich** - For the beautiful terminal UI framework\n- **Textual** - For the modern TUI components \n- **BeautifulSoup** - For robust HTML parsing\n- **Edge-TTS** - For high-quality text-to-speech\n- **html2text** - For HTML to text conversion\n\n## \ud83d\udc1b Known Issues\n\n- Image display requires `fabulous` and may not work in all terminals\n- TTS seeking is not supported with the pygame audio backend\n- Very large EPUB files may consume significant memory\n\n## \ud83d\udcda Similar Projects\n\n- [epr](https://github.com/wustho/epr) - CLI EPUB reader\n- [epub](https://github.com/rupa/epub) - Simple EPUB reader\n\n---\n\n**Happy Reading!** \ud83d\udcd6\u2728\n\nFor more information, visit our [documentation](https://speakub.readthedocs.io/) or [report issues](https://github.com/eyes1971/SpeakUB/issues).\n",
"bugtrack_url": null,
"license": null,
"summary": "A rich terminal EPUB reader with TTS support",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/eyes1971/SpeakUB/issues",
"Documentation": "https://speakub.readthedocs.io/",
"Homepage": "https://github.com/eyes1971/SpeakUB",
"Repository": "https://github.com/eyes1971/SpeakUB.git"
},
"split_keywords": [
"epub",
" ebook",
" reader",
" terminal",
" tts",
" text-to-speech"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "124301797630c1e6c2fc23bea76afd0431523555b31a6bb49b9a0c79c0c71bfc",
"md5": "ca74859c55fc067776feb6ee3ef1c13f",
"sha256": "4330b242e67ba5bcdb7b6c91d9116a3bd2eda5fbc9fa245dc26b7234c23fae8a"
},
"downloads": -1,
"filename": "speakub-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca74859c55fc067776feb6ee3ef1c13f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 71710,
"upload_time": "2025-09-06T09:20:51",
"upload_time_iso_8601": "2025-09-06T09:20:51.640534Z",
"url": "https://files.pythonhosted.org/packages/12/43/01797630c1e6c2fc23bea76afd0431523555b31a6bb49b9a0c79c0c71bfc/speakub-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "973f89c465925dc97654743ea193fbb7980e51e52e102dd7b42917c24857277a",
"md5": "95c88e8dca677be11914c07e02b28cfe",
"sha256": "b7807e81d4f50a1e9b1ae524187534a8a51c2536e5878f581f3d8eab660acd21"
},
"downloads": -1,
"filename": "speakub-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "95c88e8dca677be11914c07e02b28cfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 85292,
"upload_time": "2025-09-06T09:20:53",
"upload_time_iso_8601": "2025-09-06T09:20:53.060447Z",
"url": "https://files.pythonhosted.org/packages/97/3f/89c465925dc97654743ea193fbb7980e51e52e102dd7b42917c24857277a/speakub-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 09:20:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eyes1971",
"github_project": "SpeakUB",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.9.0"
]
]
},
{
"name": "wcwidth",
"specs": [
[
">=",
"0.2.0"
]
]
},
{
"name": "html2text",
"specs": [
[
">=",
"2020.1.16"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "textual",
"specs": [
[
">=",
"0.40.0"
]
]
},
{
"name": "edge-tts",
"specs": [
[
">=",
"6.1.0"
]
]
},
{
"name": "pygame",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "fabulous",
"specs": []
},
{
"name": "Pillow",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "black",
"specs": []
},
{
"name": "flake8",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "pre-commit",
"specs": []
}
],
"lcname": "speakub"
}
JSON
