From 57e4dceabf1063d2c16901218351971c4ebc0b19 Mon Sep 17 00:00:00 2001 From: Storm Dragon Date: Sun, 12 Oct 2025 14:37:15 -0400 Subject: [PATCH] Initial readme added. --- README.md | 322 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..723d929 --- /dev/null +++ b/README.md @@ -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