Metadata-Version: 2.4
Name: speakub
Version: 1.1.0
Summary: A rich terminal EPUB reader with TTS support
Author-email: Sam Weng <eyes1971@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/eyes1971/SpeakUB
Project-URL: Repository, https://github.com/eyes1971/SpeakUB.git
Project-URL: Documentation, https://speakub.readthedocs.io/
Project-URL: Bug Tracker, https://github.com/eyes1971/SpeakUB/issues
Keywords: epub,ebook,reader,terminal,tts,text-to-speech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.9.0
Requires-Dist: wcwidth>=0.2.0
Requires-Dist: html2text>=2020.1.16
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.40.0
Provides-Extra: tts
Requires-Dist: edge-tts>=6.1.0; extra == "tts"
Requires-Dist: pygame>=2.0.0; extra == "tts"
Provides-Extra: images
Requires-Dist: fabulous; extra == "images"
Requires-Dist: Pillow>=8.0.0; extra == "images"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: all
Requires-Dist: speakub[dev,images,tts]; extra == "all"
Dynamic: license-file




# 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).
