# 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
- ๐ฃ๏ธ **Chinese Pronunciation Corrections** - Optional pronunciation correction system
## ๐ 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]
```
## ๏ฟฝ๏ธ Desktop Integration
SpeakUB automatically creates a desktop entry on first run, allowing you to:
- Right-click EPUB files and select "Open with SpeakUB"
- Double-click EPUB files to open them directly
The desktop entry uses `speakub %f` command, which automatically detects and launches in your preferred terminal emulator.
## ๏ฟฝ๐ 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 (with adaptive cache)
โ โ โโโ chapter_manager.py # Chapter navigation
โ โ โโโ progress_tracker.py # Reading progress
โ โโโ tts/ # Text-to-Speech
โ โ โโโ engine.py # TTS abstraction
โ โ โโโ edge_tts_provider.py # Edge-TTS with state machine
โ โ โโโ ui/runners.py # TTS workers (English comments)
โ โ โโโ audio_player.py # Audio playback
โ โโโ ui/ # User interfaces
โ โ โโโ widgets/ # Reusable components
โ โโโ utils/ # Utility functions
โ โ โโโ performance_monitor.py # Performance monitoring
โ โ โโโ text_utils.py # Text processing utilities
โ โโโ cli.py # Command-line interface
โ โโโ desktop.py # Desktop integration
โโโ tests/ # Test suite
โ โโโ test_performance_benchmarks.py # Performance benchmarks
โ โโโ test_tts_state_machine.py # TTS state machine tests
โโโ 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)
- **Adaptive Renderer Cache**: Caches HTML-to-text renderers by width with TTL and statistics
#### Adaptive Cache Features
The new adaptive cache system provides:
- **TTL (Time-To-Live)**: Automatically expires cached items after 5 minutes to prevent memory leaks
- **LRU Eviction**: Removes least recently used items when cache is full
- **Performance Statistics**: Tracks hit rates, cache size, and access patterns
- **Memory-Aware Sizing**: Automatically adjusts cache size based on system memory
### Performance Monitoring
SpeakUB includes built-in performance monitoring to track system health:
```bash
# Run performance benchmarks
python tests/test_performance_benchmarks.py
# Monitor cache statistics in real-time
from speakub.core.content_renderer import ContentRenderer
renderer = ContentRenderer()
stats = renderer.get_cache_stats()
print(f"Cache hit rate: {stats['hit_rate']:.1%}")
```
#### Performance Metrics
- **Cache Hit Rate**: Percentage of cache requests that hit
- **Memory Usage**: Current and peak memory consumption
- **TTS State Changes**: Number of TTS state transitions
- **Render Time**: Time spent rendering content
To clear all caches, delete the progress file:
```bash
rm ~/.speakub_progress.json
```
## ๐ฃ๏ธ Chinese Pronunciation Corrections
SpeakUB supports optional pronunciation corrections for Chinese text. This feature allows you to customize how specific Chinese characters or words are pronounced by the TTS system.
### Setting Up Corrections
1. **Automatic Setup**: The first time you run SpeakUB, it will create a corrections file at `~/.config/speakub/corrections.json` with instructions and examples.
2. **Manual Setup**: You can also create the file manually:
```bash
mkdir -p ~/.config/speakub
touch ~/.config/speakub/corrections.json
```
### Corrections File Format
The corrections file is a JSON object where each key is the original text and the value is the corrected pronunciation:
```json
{
"_comment": "Chinese Pronunciation Corrections Configuration",
"_instructions": "Add your correction rules below in format: 'original': 'corrected'",
"_examples": {
"็้ท": "็ๆ",
"้ท": "ๅธธ"
},
"็้ท": "็ๆ",
"้ท": "ๅธธ",
"้ถ่ก": "yรญnhรกng",
"็ปไบ": "jวyว"
}
```
### How It Works
- **Keys starting with `_`**: These are treated as comments and instructions, not correction rules
- **Regular keys**: These are the actual correction mappings
- **Automatic filtering**: The system automatically filters out instruction keys when loading corrections
- **Optional feature**: If the corrections file doesn't exist, SpeakUB works normally without corrections
### Common Use Cases
- **Polyphonic characters**: Characters that can be pronounced differently in different contexts
- **Proper nouns**: Names, places, or terms that need specific pronunciation
- **Technical terms**: Specialized vocabulary that needs consistent pronunciation
- **Regional variations**: Different pronunciation preferences
### Examples
```json
{
"่ก": "xรญng", // ่ก่ตฐ (walking)
"้ถ่ก": "yรญnhรกng", // ้ถ่ก (bank)
"้ถ่กๅฎถ": "yรญnhรกngjiฤ", // ้ถ่กๅฎถ (banker)
"้ฟ": "chรกng", // ้ฟๅบฆ (length)
"้ฟๆฑ": "chรกngjiฤng" // ้ฟๆฑ (Yangtze River)
}
```
### Tips
- Use Pinyin with tone marks for best results
- Test corrections with short text first
- The corrections are applied before TTS processing
- You can have multiple corrections for the same character in different contexts
## ๐ Version History
### Version 1.1.0 (Latest)
- โจ **New Feature**: Added Chinese pronunciation corrections system
- ๐ง **Enhancement**: Improved content widget with better text processing
- ๐ **Bug Fix**: Fixed Flake8 linting issues
- ๐ **Documentation**: Updated README with corrections usage guide
- ๐๏ธ **Build**: Updated build system and version management
### Version 1.0.0
- ๐ Initial release with full EPUB reading capabilities
- ๐ Text-to-Speech support with Microsoft Edge-TTS
- ๐จ Rich terminal UI with Textual framework
- ๐ Smart table of contents navigation
- ๐พ Automatic progress tracking
- ๐๏ธ Comprehensive TTS controls
## ๐ง 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": null,
"platform": null,
"description": "\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- \ud83d\udde3\ufe0f **Chinese Pronunciation Corrections** - Optional pronunciation correction system\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## \ufffd\ufe0f Desktop Integration\n\nSpeakUB automatically creates a desktop entry on first run, allowing you to:\n- Right-click EPUB files and select \"Open with SpeakUB\"\n- Double-click EPUB files to open them directly\n\nThe desktop entry uses `speakub %f` command, which automatically detects and launches in your preferred terminal emulator.\n\n## \ufffd\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 (with adaptive cache)\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 with state machine\n\u2502 \u2502 \u251c\u2500\u2500 ui/runners.py # TTS workers (English comments)\n\u2502 \u2502 \u2514\u2500\u2500 audio_player.py # Audio playback\n\u2502 \u251c\u2500\u2500 ui/ # User interfaces\n\u2502 \u2502 \u2514\u2500\u2500 widgets/ # Reusable components\n\u2502 \u251c\u2500\u2500 utils/ # Utility functions\n\u2502 \u2502 \u251c\u2500\u2500 performance_monitor.py # Performance monitoring\n\u2502 \u2502 \u2514\u2500\u2500 text_utils.py # Text processing utilities\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 desktop.py # Desktop integration\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 test_performance_benchmarks.py # Performance benchmarks\n\u2502 \u2514\u2500\u2500 test_tts_state_machine.py # TTS state machine tests\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- **Adaptive Renderer Cache**: Caches HTML-to-text renderers by width with TTL and statistics\n\n#### Adaptive Cache Features\n\nThe new adaptive cache system provides:\n\n- **TTL (Time-To-Live)**: Automatically expires cached items after 5 minutes to prevent memory leaks\n- **LRU Eviction**: Removes least recently used items when cache is full\n- **Performance Statistics**: Tracks hit rates, cache size, and access patterns\n- **Memory-Aware Sizing**: Automatically adjusts cache size based on system memory\n\n### Performance Monitoring\n\nSpeakUB includes built-in performance monitoring to track system health:\n\n```bash\n# Run performance benchmarks\npython tests/test_performance_benchmarks.py\n\n# Monitor cache statistics in real-time\nfrom speakub.core.content_renderer import ContentRenderer\nrenderer = ContentRenderer()\nstats = renderer.get_cache_stats()\nprint(f\"Cache hit rate: {stats['hit_rate']:.1%}\")\n```\n\n#### Performance Metrics\n\n- **Cache Hit Rate**: Percentage of cache requests that hit\n- **Memory Usage**: Current and peak memory consumption\n- **TTS State Changes**: Number of TTS state transitions\n- **Render Time**: Time spent rendering content\n\nTo clear all caches, delete the progress file:\n```bash\nrm ~/.speakub_progress.json\n```\n\n## \ud83d\udde3\ufe0f Chinese Pronunciation Corrections\n\nSpeakUB supports optional pronunciation corrections for Chinese text. This feature allows you to customize how specific Chinese characters or words are pronounced by the TTS system.\n\n### Setting Up Corrections\n\n1. **Automatic Setup**: The first time you run SpeakUB, it will create a corrections file at `~/.config/speakub/corrections.json` with instructions and examples.\n\n2. **Manual Setup**: You can also create the file manually:\n```bash\nmkdir -p ~/.config/speakub\ntouch ~/.config/speakub/corrections.json\n```\n\n### Corrections File Format\n\nThe corrections file is a JSON object where each key is the original text and the value is the corrected pronunciation:\n\n```json\n{\n \"_comment\": \"Chinese Pronunciation Corrections Configuration\",\n \"_instructions\": \"Add your correction rules below in format: 'original': 'corrected'\",\n \"_examples\": {\n \"\u751f\u9577\": \"\u751f\u638c\",\n \"\u9577\": \"\u5e38\"\n },\n \"\u751f\u9577\": \"\u751f\u638c\",\n \"\u9577\": \"\u5e38\",\n \"\u94f6\u884c\": \"y\u00ednh\u00e1ng\",\n \"\u7ed9\u4e88\": \"j\u01d0y\u01d4\"\n}\n```\n\n### How It Works\n\n- **Keys starting with `_`**: These are treated as comments and instructions, not correction rules\n- **Regular keys**: These are the actual correction mappings\n- **Automatic filtering**: The system automatically filters out instruction keys when loading corrections\n- **Optional feature**: If the corrections file doesn't exist, SpeakUB works normally without corrections\n\n### Common Use Cases\n\n- **Polyphonic characters**: Characters that can be pronounced differently in different contexts\n- **Proper nouns**: Names, places, or terms that need specific pronunciation\n- **Technical terms**: Specialized vocabulary that needs consistent pronunciation\n- **Regional variations**: Different pronunciation preferences\n\n### Examples\n\n```json\n{\n \"\u884c\": \"x\u00edng\", // \u884c\u8d70 (walking)\n \"\u94f6\u884c\": \"y\u00ednh\u00e1ng\", // \u94f6\u884c (bank)\n \"\u94f6\u884c\u5bb6\": \"y\u00ednh\u00e1ngji\u0101\", // \u94f6\u884c\u5bb6 (banker)\n \"\u957f\": \"ch\u00e1ng\", // \u957f\u5ea6 (length)\n \"\u957f\u6c5f\": \"ch\u00e1ngji\u0101ng\" // \u957f\u6c5f (Yangtze River)\n}\n```\n\n### Tips\n\n- Use Pinyin with tone marks for best results\n- Test corrections with short text first\n- The corrections are applied before TTS processing\n- You can have multiple corrections for the same character in different contexts\n\n## \ud83d\udccb Version History\n\n### Version 1.1.0 (Latest)\n- \u2728 **New Feature**: Added Chinese pronunciation corrections system\n- \ud83d\udd27 **Enhancement**: Improved content widget with better text processing\n- \ud83d\udc1b **Bug Fix**: Fixed Flake8 linting issues\n- \ud83d\udcda **Documentation**: Updated README with corrections usage guide\n- \ud83c\udfd7\ufe0f **Build**: Updated build system and version management\n\n### Version 1.0.0\n- \ud83c\udf89 Initial release with full EPUB reading capabilities\n- \ud83d\udd0a Text-to-Speech support with Microsoft Edge-TTS\n- \ud83c\udfa8 Rich terminal UI with Textual framework\n- \ud83d\udcd1 Smart table of contents navigation\n- \ud83d\udcbe Automatic progress tracking\n- \ud83c\udf9b\ufe0f Comprehensive TTS controls\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.37",
"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": "eec96bb5b39ad95a5e3c789316d786bd366474945ff3491ac73d712f85167290",
"md5": "9ca0f4a19efde53b749ba7dd62ba8aba",
"sha256": "0d45f09e6334fe9662d3193ad20e21c738db3a69a701db0baa84984724e9a892"
},
"downloads": -1,
"filename": "speakub-1.1.37-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ca0f4a19efde53b749ba7dd62ba8aba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 141483,
"upload_time": "2025-10-22T00:01:24",
"upload_time_iso_8601": "2025-10-22T00:01:24.515696Z",
"url": "https://files.pythonhosted.org/packages/ee/c9/6bb5b39ad95a5e3c789316d786bd366474945ff3491ac73d712f85167290/speakub-1.1.37-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 00:01:24",
"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
