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:

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:

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

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

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

[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

[Reading]
auto_advance = true                 # Auto-advance to next paragraph
auto_save_bookmark = true           # Save position automatically

Display Settings

[Display]
show_text = true                    # Show large print text display (72pt)

Paths

[Paths]
last_book = /path/to/last/book.zip
books_directory = /home/user
library_directory = /home/user/library  # Default for book browser

Audiobookshelf Settings

[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

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

For issues and feature requests, please visit https://git.stormux.org/storm/bookstorm