Initial readme added.
This commit is contained in:
Storm Dragon
322
README.md
Normal file
322
README.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# BookStorm - Accessible Book Reader
|
||||
|
||||
BookStorm is a fully accessible book reader for electronic books and audiobooks, designed specifically for blind and visually impaired users. It provides seamless text-to-speech reading for text formats and native playback for audio formats, with real-time keyboard control and optional large print display.
|
||||
|
||||
## Features
|
||||
|
||||
- **Multiple Book Formats**: DAISY 2.02, DAISY 3, EPUB, PDF, TXT, and audio formats (M4B, M4A, MP3)
|
||||
- **Text-to-Speech**: High-quality narration using piper-tts or system voices via speech-dispatcher
|
||||
- **Audio Book Playback**: Native playback with chapter navigation and bookmarks
|
||||
- **Audiobookshelf Integration**: Browse, stream, and download audiobooks from your Audiobookshelf server
|
||||
- **Full Keyboard Control**: No mouse required - navigate with simple keyboard shortcuts
|
||||
- **Bookmark System**: Auto-save progress and create named bookmarks with optional server sync
|
||||
- **Large Print Display**: Optional 72-point text display for low vision users (1600x900 window)
|
||||
- **Sleep Timer**: Automatic shutdown after 5-60 minutes for bedtime reading
|
||||
- **Library Browser**: Browse your book collection with configurable library directory
|
||||
- **Recent Books**: Quick access to your 10 most recently read books
|
||||
- **WAV Export**: Convert text books to audio files split by chapter
|
||||
- **Screen Reader Friendly**: All feedback provided via speech-dispatcher for full accessibility
|
||||
|
||||
## Installation
|
||||
|
||||
### System Dependencies
|
||||
|
||||
**Arch Linux:**
|
||||
```bash
|
||||
yay -S --needed ffmpeg mpv python-mpv piper-tts-bin piper-voices-en-us python-beautifulsoup4 python-lxml python-mutagen python-pypdf python-pygame speech-dispatcher
|
||||
```
|
||||
|
||||
**Debian/Ubuntu:**
|
||||
```bash
|
||||
sudo apt install --no-install-recommends ffmpeg mpv python3 python3-pip python3-beautifulsoup4 python3-lxml python3-mutagen python3-pygame python3-speechd speech-dispatcher
|
||||
```
|
||||
|
||||
**Note:** Piper-TTS and voice packages may need to be installed manually on Debian/Ubuntu. Voice models should be organized by language:
|
||||
|
||||
```
|
||||
/usr/share/piper-voices/
|
||||
└── en/
|
||||
└── en_US/
|
||||
├── hfc_male/
|
||||
│ └── medium/
|
||||
│ ├── en_US-hfc_male-medium.onnx
|
||||
│ └── en_US-hfc_male-medium.onnx.json
|
||||
└── hfc_female/
|
||||
└── medium/
|
||||
├── en_US-hfc_female-medium.onnx
|
||||
└── en_US-hfc_female-medium.onnx.json
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Interactive Reading
|
||||
|
||||
```bash
|
||||
# Resume last book
|
||||
python bookstorm.py
|
||||
|
||||
# Open a specific book
|
||||
python bookstorm.py mybook.zip # DAISY book
|
||||
python bookstorm.py mybook.epub # EPUB book
|
||||
python bookstorm.py audiobook.m4b # Audio book
|
||||
```
|
||||
|
||||
### Export to Audio Files (Text Books Only)
|
||||
|
||||
```bash
|
||||
# Export to WAV files (one per chapter)
|
||||
python bookstorm.py mybook.zip --wav
|
||||
|
||||
# Custom output directory
|
||||
python bookstorm.py mybook.epub --wav --output-dir ./audiobooks
|
||||
```
|
||||
|
||||
## Keyboard Controls
|
||||
|
||||
### Playback Control
|
||||
|
||||
- **SPACE** - Start/pause/resume playback
|
||||
- **n** - Next paragraph (text books) / Next chapter (audio books)
|
||||
- **p** - Previous paragraph (text books) / Previous chapter (audio books)
|
||||
- **SHIFT+N** - Next chapter (works during playback)
|
||||
- **SHIFT+P** - Previous chapter (works during playback)
|
||||
- **Page Up/Down** - Adjust speech rate (±10%)
|
||||
|
||||
### Navigation & Bookmarks
|
||||
|
||||
- **s** - Save bookmark at current position
|
||||
- **k** - Bookmarks menu (view, jump to, or delete named bookmarks)
|
||||
- **r** - Recent books menu (10 most recently accessed)
|
||||
- **b** - Browse books (opens library directory if set)
|
||||
- **a** - Audiobookshelf browser (if server configured)
|
||||
|
||||
### Menus & Settings
|
||||
|
||||
- **o** - Options menu (TTS engine, voice selection, display settings)
|
||||
- **t** - Time remaining (if sleep timer active)
|
||||
- **h** - Help (displays keyboard shortcuts)
|
||||
- **q or ESC** - Quit / Sleep timer menu
|
||||
|
||||
### Book Browser Controls
|
||||
|
||||
- **UP/DOWN** - Navigate items
|
||||
- **ENTER** - Select book or enter directory
|
||||
- **BACKSPACE/LEFT** - Go to parent directory
|
||||
- **L** - Set current directory as default library location
|
||||
- **ESC** - Cancel and return
|
||||
|
||||
## Audiobookshelf Integration
|
||||
|
||||
BookStorm can connect to an [Audiobookshelf](https://www.audiobookshelf.org/) server to browse, stream, and download audiobooks with full accessibility.
|
||||
|
||||
### Setup
|
||||
|
||||
1. Press **o** to open the options menu
|
||||
2. Navigate to "Configure Audiobookshelf Server"
|
||||
3. Enter your server URL, username, and password
|
||||
4. Press **a** during reading to browse your Audiobookshelf library
|
||||
|
||||
### Features
|
||||
|
||||
- **Browse Libraries**: Navigate multiple libraries, series, and collections
|
||||
- **Stream or Download**: Choose to stream directly or download for offline use
|
||||
- **Progress Sync**: Your reading progress syncs between BookStorm and Audiobookshelf
|
||||
- **Bookmark Sync**: Named bookmarks sync to the server (when enabled)
|
||||
- **Local-First**: If you already have a book locally, BookStorm uses it automatically
|
||||
|
||||
### Stream vs Download
|
||||
|
||||
When you select a book from Audiobookshelf:
|
||||
|
||||
- **Stream**: Play directly from the server (requires internet, no disk space used)
|
||||
- **Download**: Save to your library directory (works offline, syncs progress to server)
|
||||
|
||||
Books downloaded from Audiobookshelf are tagged with server metadata and automatically sync progress back to the server.
|
||||
|
||||
## Configuration
|
||||
|
||||
Settings are stored in `~/.config/stormux/bookstorm/settings.ini` and can be modified through the options menu (press **o**).
|
||||
|
||||
### TTS Settings
|
||||
|
||||
```ini
|
||||
[TTS]
|
||||
voice_model = /usr/share/piper-voices/en/en_US/hfc_male/medium/en_US-hfc_male-medium.onnx
|
||||
voice_dir = /usr/share/piper-voices/en/en_US
|
||||
reader_engine = piper # or 'speechd'
|
||||
speechd_voice = # speech-dispatcher voice name
|
||||
speechd_output_module = # e.g., espeak-ng
|
||||
speech_rate = 0 # -100 to 100
|
||||
```
|
||||
|
||||
### Reading Settings
|
||||
|
||||
```ini
|
||||
[Reading]
|
||||
auto_advance = true # Auto-advance to next paragraph
|
||||
auto_save_bookmark = true # Save position automatically
|
||||
```
|
||||
|
||||
### Display Settings
|
||||
|
||||
```ini
|
||||
[Display]
|
||||
show_text = true # Show large print text display (72pt)
|
||||
```
|
||||
|
||||
### Paths
|
||||
|
||||
```ini
|
||||
[Paths]
|
||||
last_book = /path/to/last/book.zip
|
||||
books_directory = /home/user
|
||||
library_directory = /home/user/library # Default for book browser
|
||||
```
|
||||
|
||||
### Audiobookshelf Settings
|
||||
|
||||
```ini
|
||||
[Audiobookshelf]
|
||||
server_url = https://abs.example.com
|
||||
username = myuser
|
||||
auto_sync = true # Auto-sync progress to server
|
||||
sync_interval = 30 # Seconds between progress syncs
|
||||
```
|
||||
|
||||
## Bookmarks
|
||||
|
||||
Bookmarks are stored in `~/.bookstorm/bookmarks.db` (SQLite database).
|
||||
|
||||
### Auto-Save Bookmarks
|
||||
|
||||
BookStorm automatically saves your position when you press **s** or quit the application. When you reopen a book, it resumes from where you left off.
|
||||
|
||||
### Named Bookmarks
|
||||
|
||||
Press **k** to open the bookmarks menu where you can:
|
||||
- Create named bookmarks with custom labels
|
||||
- Jump to any saved bookmark
|
||||
- Delete bookmarks you no longer need
|
||||
- View all bookmarks for the current book
|
||||
|
||||
Named bookmarks sync to Audiobookshelf if the book is linked to a server (downloaded or manually linked).
|
||||
|
||||
## Supported Formats
|
||||
|
||||
### Text Formats
|
||||
|
||||
- **DAISY 2.02**: NCC.html-based navigation with full structure
|
||||
- **DAISY 3**: NCX + DTBook XML format
|
||||
- **EPUB**: EPUB 2 and 3 with chapter detection
|
||||
- **PDF**: Text extraction (quality depends on PDF structure)
|
||||
- **TXT**: Plain text files with paragraph detection
|
||||
|
||||
### Audio Formats
|
||||
|
||||
- **MP3**: Natively supported (with ID3 CHAP chapter markers)
|
||||
- **M4B/M4A**: Auto-transcoded with ffmpeg if needed
|
||||
- **Any format ffmpeg supports**: Automatically transcoded to OGG on first load
|
||||
|
||||
**Note**: Transcoded files are cached in `~/.cache/bookstorm/audio/` for instant playback on subsequent loads.
|
||||
|
||||
### Chapter Markers
|
||||
|
||||
BookStorm extracts chapter markers from:
|
||||
- **M4B/M4A**: MP4 metadata chapters
|
||||
- **MP3**: ID3 CHAP frames (if present)
|
||||
- **Fallback**: Treats entire file as single chapter if no markers found
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Audio Book Won't Play (M4B/M4A)
|
||||
|
||||
This is normal - most pygame builds don't include AAC codec support. BookStorm will automatically transcode using ffmpeg:
|
||||
|
||||
1. Make sure ffmpeg is installed: `sudo pacman -S ffmpeg` (Arch) or `sudo apt install ffmpeg` (Ubuntu)
|
||||
2. First playback will transcode (may take a moment)
|
||||
3. Subsequent playbacks use the cached file (instant)
|
||||
|
||||
To clear the cache: `rm -rf ~/.cache/bookstorm/audio/`
|
||||
|
||||
### No Piper Voices Found
|
||||
|
||||
Install piper-tts and download voice models to `/usr/share/piper-voices/en/en_US/`. You can also select a different voice directory in the options menu.
|
||||
|
||||
### Book Has 0 Chapters
|
||||
|
||||
- Verify it's a valid DAISY format (should contain `.ncx` or `ncc.html`)
|
||||
- DAISY books must be in ZIP format (not extracted folders)
|
||||
- Check console output for parsing errors
|
||||
|
||||
### "No module named" Errors
|
||||
|
||||
```bash
|
||||
# Install missing Python packages
|
||||
pip install pygame beautifulsoup4 lxml python-speechd mutagen
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
BookStorm uses a dual TTS system for text books:
|
||||
|
||||
- **UI Feedback**: speech-dispatcher (instant feedback for all actions)
|
||||
- **Book Reading (Piper-TTS mode)**: piper-tts → WAV → pygame.mixer (high quality)
|
||||
- **Book Reading (Speech-Dispatcher mode)**: Separate speech-dispatcher session (faster, system voices)
|
||||
|
||||
Audio books use pygame.mixer.music for streaming playback with chapter-based navigation.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
bookstorm/
|
||||
├── bookstorm.py # Main entry point
|
||||
├── README.md # This file
|
||||
├── CLAUDE.md # Developer documentation
|
||||
├── check_naming.py # Code style validator
|
||||
└── src/
|
||||
├── daisy_parser.py # DAISY 2.02 & 3 parser
|
||||
├── epub_parser.py # EPUB parser
|
||||
├── pdf_parser.py # PDF text extractor
|
||||
├── txt_parser.py # Plain text parser
|
||||
├── audio_parser.py # Audio book parser
|
||||
├── bookmark_manager.py # SQLite bookmark storage
|
||||
├── speech_engine.py # Speech-dispatcher wrapper
|
||||
├── tts_engine.py # Piper-TTS wrapper
|
||||
├── pygame_player.py # Audio playback engine
|
||||
├── config_manager.py # Settings management
|
||||
├── options_menu.py # Interactive menu system
|
||||
├── voice_selector.py # Voice browsing/testing
|
||||
├── book_selector.py # File browser
|
||||
├── recent_books_menu.py # Recent books menu
|
||||
├── sleep_timer_menu.py # Sleep timer
|
||||
├── audiobookshelf_client.py # Audiobookshelf API client
|
||||
├── audiobookshelf_menu.py # Server browser interface
|
||||
├── server_sync.py # Progress synchronization
|
||||
└── bookmark_sync.py # Bookmark synchronization
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
BookStorm follows specific naming conventions:
|
||||
- **Variables & Parameters**: camelCase
|
||||
- **Functions & Methods**: snake_case
|
||||
- **Classes**: PascalCase
|
||||
|
||||
Before committing changes, run the naming validator:
|
||||
```bash
|
||||
python check_naming.py
|
||||
```
|
||||
|
||||
See `CLAUDE.md` for detailed developer documentation.
|
||||
|
||||
## License
|
||||
|
||||
[Add your license information here]
|
||||
|
||||
## Credits
|
||||
|
||||
BookStorm was created for the blind and visually impaired community, with a focus on accessibility-first design.
|
||||
|
||||
## Support
|
||||
|
||||
For issues and feature requests, please visit https://git.stormux.org/storm/bookstorm
|
||||
Reference in New Issue
Block a user