Storm Dragon
250 lines
8.5 KiB
Markdown
250 lines
8.5 KiB
Markdown
# Reading Books with BookStorm
|
|
|
|
BookStorm is a fully accessible book reader designed for blind and visually impaired users. It supports both electronic books (DAISY, EPUB, PDF, TXT) and audiobooks (M4B, M4A, MP3) with full text-to-speech and keyboard control.
|
|
|
|
## Starting BookStorm
|
|
|
|
1. Navigate to the **Media** menu in the main game launcher
|
|
2. Select **BookStorm**
|
|
3. The application will launch and resume your last book automatically
|
|
4. If this is your first time, you'll be in the library browser
|
|
|
|
## Supported Book Formats
|
|
|
|
### Text Books (Read with Text-to-Speech)
|
|
- **DAISY 2.02 and DAISY 3**: Full accessible format with chapter navigation
|
|
- **EPUB**: Standard ebook format (EPUB 2 and 3)
|
|
- **PDF**: Text extraction (quality varies by PDF)
|
|
- **TXT**: Plain text files
|
|
|
|
### Audiobooks (Native Audio Playback)
|
|
- **M4B/M4A**: Audiobook format with chapter markers
|
|
- **MP3**: Audio files with optional chapter markers
|
|
|
|
**Note**: M4B and M4A files are automatically converted for playback on first load. Subsequent plays use the cached version for instant playback.
|
|
|
|
## Keyboard Controls
|
|
|
|
### Basic Playback
|
|
- **SPACE**: Start, pause, or resume reading
|
|
- **n**: Next paragraph (text books) or next chapter (audiobooks)
|
|
- **p**: Previous paragraph (text books) or previous chapter (audiobooks)
|
|
- **SHIFT+N**: Skip to next chapter (works during playback)
|
|
- **SHIFT+P**: Go to previous chapter (works during playback)
|
|
- **Page Up/Down**: Adjust speech rate by 10%
|
|
|
|
### Navigation and Bookmarks
|
|
- **s**: Save a bookmark at your current position
|
|
- **k**: Open bookmarks menu (view, jump to, or delete bookmarks)
|
|
- **r**: Recent books menu (shows your 10 most recent books)
|
|
- **b**: Browse your book library
|
|
- **a**: Browse Audiobookshelf server (if configured)
|
|
|
|
### Settings and Help
|
|
- **o**: Options menu (change voice, speech settings, display options)
|
|
- **t**: Time remaining (if sleep timer is active)
|
|
- **h**: Help (displays all keyboard shortcuts)
|
|
- **q or ESC**: Quit (or open sleep timer menu if reading)
|
|
|
|
## Adding Books to Your Library
|
|
|
|
### Using the Upload Server
|
|
|
|
The easiest way to add books is through the upload server:
|
|
|
|
1. Start the Upload Server from the Media menu
|
|
2. Note the IP address and port announced
|
|
3. Open a web browser on another device
|
|
4. Navigate to the announced address
|
|
5. Select the appropriate category:
|
|
- **Audiobook**: For M4B, M4A, or MP3 audiobooks
|
|
- **Other Files**: For DAISY (.zip), EPUB, PDF, or TXT books
|
|
6. Upload your book files
|
|
7. Books are automatically placed in ~/Library (Audiobooks) or ~/Downloads (Other Files)
|
|
|
|
**On the Stormux Gaming Image**, ~/Library is set as your default library directory, so:
|
|
- Audiobooks uploaded go directly to ~/Library and appear immediately when you press **b**
|
|
- Other book formats go to ~/Downloads and you can browse to them with **b**
|
|
- You can move books from ~/Downloads to ~/Library for better organization
|
|
|
|
### Organizing Your Books
|
|
|
|
**On the Stormux Gaming Image**, ~/Library is already set as your default library directory. When you press **b**, you'll start in this location.
|
|
|
|
BookStorm can work with books anywhere on your system. You can organize them however you like:
|
|
|
|
**Example structure:**
|
|
```
|
|
~/Library/
|
|
├── DAISY/
|
|
│ ├── Book1.zip
|
|
│ └── Book2.zip
|
|
├── EPUB/
|
|
│ ├── Novel1.epub
|
|
│ └── Novel2.epub
|
|
└── Audiobooks/
|
|
├── Audiobook1.m4b
|
|
└── Audiobook2.m4b
|
|
```
|
|
|
|
**To change your default library location:**
|
|
1. Press **b** to open the book browser
|
|
2. Navigate to your preferred directory
|
|
3. Press **L** to set it as your default library
|
|
4. BookStorm will remember this location
|
|
|
|
## Using Bookmarks
|
|
|
|
### Auto-Save Bookmarks
|
|
BookStorm automatically saves your position when you:
|
|
- Press **s** to save
|
|
- Quit the application with **q**
|
|
- Switch to a different book
|
|
|
|
When you reopen a book, it automatically resumes where you left off.
|
|
|
|
### Named Bookmarks
|
|
Press **k** to open the bookmarks menu where you can:
|
|
- Create bookmarks with custom names (e.g., "Chapter 5 - Important Scene")
|
|
- Jump to any saved bookmark
|
|
- Delete bookmarks you no longer need
|
|
- View all bookmarks for the current book
|
|
|
|
## Sleep Timer
|
|
|
|
Perfect for bedtime reading, the sleep timer will automatically stop playback after a set time:
|
|
|
|
1. Press **q** or **ESC** while reading
|
|
2. Select a duration (5 to 60 minutes)
|
|
3. BookStorm will continue reading and stop at the chosen time
|
|
4. Your position is automatically saved
|
|
|
|
Press **t** at any time to hear how much time remains.
|
|
|
|
## Voice and Speech Settings
|
|
|
|
Press **o** to access the options menu where you can:
|
|
|
|
### Change TTS Engine
|
|
- **Piper-TTS**: High-quality voices (default, slower to start)
|
|
- **Speech-Dispatcher**: System voices (faster, uses same voices as menu)
|
|
|
|
### Select Voice
|
|
Browse available voices and test them before selecting. The voice selector reads sample text so you can hear each voice.
|
|
|
|
### Adjust Speech Rate
|
|
Change reading speed from -100 (very slow) to +100 (very fast). Default is 0.
|
|
|
|
### Display Settings
|
|
Toggle the large print display on or off. When enabled, shows 72-point text in a 1600x900 window for low vision users.
|
|
|
|
## Book Browser Controls
|
|
|
|
When browsing your library (press **b**):
|
|
|
|
- **UP/DOWN**: Navigate through books and folders
|
|
- **ENTER**: Open a book or enter a directory
|
|
- **BACKSPACE/LEFT**: Go to parent directory
|
|
- **L**: Set current directory as default library location
|
|
- **ESC**: Cancel and return to reading
|
|
|
|
The browser announces each item as you navigate, including file types and sizes.
|
|
|
|
## Audiobookshelf Integration
|
|
|
|
If you use an [Audiobookshelf](https://www.audiobookshelf.org/) server, BookStorm can connect to browse, stream, and download audiobooks.
|
|
|
|
### Setup
|
|
|
|
1. Press **o** to open options menu
|
|
2. Navigate to "Configure Audiobookshelf Server"
|
|
3. Enter your server URL (e.g., https://abs.example.com)
|
|
4. Enter your username and password
|
|
5. Settings are saved automatically
|
|
|
|
### Browsing Your Server
|
|
|
|
1. Press **a** to open the Audiobookshelf browser
|
|
2. Navigate through libraries, series, and collections
|
|
3. Select a book to choose stream or download
|
|
|
|
### Stream vs Download
|
|
|
|
**Stream**: Play directly from the server
|
|
- Requires active internet connection
|
|
- No disk space used
|
|
- Progress syncs to server
|
|
|
|
**Download**: Save to your library
|
|
- Works offline after download
|
|
- Takes up disk space
|
|
- Progress still syncs to server
|
|
- Faster playback (no buffering)
|
|
|
|
**Progress Sync**: Your reading progress automatically syncs between BookStorm and Audiobookshelf, so you can switch between devices seamlessly.
|
|
|
|
## Tips and Best Practices
|
|
|
|
### DAISY Books
|
|
- DAISY books must be in ZIP format (don't extract them)
|
|
- Full chapter navigation and structure is supported
|
|
- Best format for accessibility
|
|
|
|
### EPUB Books
|
|
- Standard ebook format, widely available
|
|
- Chapter detection is automatic
|
|
- Some complex formatting may be simplified
|
|
|
|
### PDF Books
|
|
- Text extraction quality depends on the PDF
|
|
- Best for text-based PDFs (not scanned images)
|
|
- May have formatting issues with complex layouts
|
|
|
|
### Audiobooks
|
|
- First playback may take a moment while converting
|
|
- Cached files play instantly on subsequent opens
|
|
- Chapter markers are preserved when present
|
|
- To clear cache: Delete ~/.cache/bookstorm/audio/
|
|
|
|
### Organization
|
|
- Keep DAISY books as .zip files in one location
|
|
- Group books by format or genre for easy browsing
|
|
- Use the **r** key for quick access to recent books
|
|
- Set a library directory with **L** in the browser
|
|
|
|
## Troubleshooting
|
|
|
|
### Book Won't Open
|
|
- DAISY books must be .zip files, not extracted folders
|
|
- Verify the file format is supported
|
|
- Check that the file isn't corrupted
|
|
|
|
### No Sound
|
|
- Check system volume with **9** and **0** keys
|
|
- Verify speech-dispatcher is running
|
|
- Try changing TTS engine in options menu
|
|
|
|
### Playback is Slow to Start
|
|
- Piper-TTS takes a moment to load voice models
|
|
- First paragraph is slower, subsequent ones are faster
|
|
- Switch to Speech-Dispatcher engine for instant start
|
|
|
|
### M4B/M4A Won't Play
|
|
- This is normal - first playback converts the file
|
|
- Requires ffmpeg (already installed on Stormux Gaming Image)
|
|
- Subsequent playbacks use cached version (instant)
|
|
|
|
### Can't Find Uploaded Books
|
|
- Audiobooks go to ~/Library (the default library directory)
|
|
- Other book formats go to ~/Downloads
|
|
- Press **b** to browse your library or navigate to ~/Downloads
|
|
- Consider organizing books into folders within ~/Library
|
|
|
|
## Getting Help
|
|
|
|
For additional support:
|
|
- Press **h** while reading to hear all keyboard shortcuts
|
|
- Visit IRC at irc.stormux.org, channels #stormux and #a11y
|
|
- Check the mailing list at https://groups.io/g/stormux
|
|
- Report issues at https://git.stormux.org/storm/bookstorm
|