Files

T

Storm Dragon 205f50affa Media related items moved to dedicated Media menu. Documentation updated.

2025-10-12 15:34:50 -04:00

8.5 KiB

Raw Permalink Blame History

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

Navigate to the Media menu in the main game launcher
Select BookStorm
The application will launch and resume your last book automatically
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%

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:

Start the Upload Server from the Media menu
Note the IP address and port announced
Open a web browser on another device
Navigate to the announced address
Select the appropriate category:
- Audiobook: For M4B, M4A, or MP3 audiobooks
- Other Files: For DAISY (.zip), EPUB, PDF, or TXT books
Upload your book files
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:

Press b to open the book browser
Navigate to your preferred directory
Press L to set it as your default library
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:

Press q or ESC while reading
Select a duration (5 to 60 minutes)
BookStorm will continue reading and stop at the chosen time
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 server, BookStorm can connect to browse, stream, and download audiobooks.

Setup

Press o to open options menu
Navigate to "Configure Audiobookshelf Server"
Enter your server URL (e.g., https://abs.example.com)
Enter your username and password
Settings are saved automatically

Browsing Your Server

Press a to open the Audiobookshelf browser
Navigate through libraries, series, and collections
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

8.5 KiB Raw Permalink Blame History