Pi Audiobook

Offline voice-controlled audiobook player intended for use with Raspberry Pi, but works with any Linux system. Intended to imitate the experience of an audiobook service provided by a personal assistant like Alexa or Google Assistant, but running entirely locally without internet access.

Overview

The system uses offline voice recognition via Vosk and a custom wake word model. It allows playback control of locally stored audiobooks using simple spoken commands. Audio playback and metadata management are handled internally, with playback state periodically saved to a local SQLite database.

Core functionality includes:

• Wake word activation (e.g. "Hey Jarvis")
• Speech-to-text parsing and fuzzy matching of commands
• Local playback control (play, pause, resume, seek, restart)
• Metadata management with position tracking across sessions
• Support for M4B audiobook format
• Modular design with separate components for audio, speech recognition, command handling, and metadata
• Configurable models and paths in common.py

Installation

1. Clone repository and create a virtual environment:

   git clone https://github.com/Eatkin/PiAudiobook.git
   cd PiAudiobook
   python -m venv venv
   source venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Install the mpv media player:

   sudo apt install mpv

4. Configure paths and models in common.py to match your environment (see below).

5. (Optional) Install the repository as a package to enable piaudiobook, build_library and validate_library commands:

   pip install -e .
   piaudiobook # starts the player
   build_library # scans WORKDIR for audiobooks and builds library.db
   validate_library # checks library.db for missing files

6. Prepare your audiobook library:

• Place your audiobooks in the directory specified by WORKDIR in common.py. Supported formats include M4B only (currently).
• Run build_library to scan the directory and create/update library.db.
• Alternatively, run python -m piaudiobook.build_library if not installed as a package.

Configuration

Paths and models are configured in common.py. These must be updated to match the local environment.

# Directory containing audiobooks
WORKDIR = pathlib.Path("/media/mint/Audiobooks").resolve()
LIBRARY_DB = WORKDIR / "library.db"
PROJECT_ROOT = pathlib.Path(__file__).parent.parent.parent.resolve()
# Model paths
MODEL_DIR = PROJECT_ROOT / "models"
DEFAULT_MODEL = MODEL_DIR / "vosk-model-small-en-us-0.15"
JARVIS_MODEL = PROJECT_ROOT / "models" / "hey_jarvis_v0.1.onnx"

Models

The repository does not include speech recognition or wake word models due to size. Users must download or train their own and place them in the models/ directory, updating DEFAULT_MODEL and JARVIS_MODEL accordingly.

Example:

• Speech model: Vosk Small English Model
• Wake word model: Custom ONNX wake word detector (available in OpenWakeWord Repository)

Command System

Spoken input is mapped to canonical command actions through a fuzzy matching resolver. Commands support short, natural phrasing. Examples include:

• Play / start / read — Begin playback of a book.
• Pause — Pause playback and store current position.
• Resume / continue — Resume playback.
• Stop — Halt playback and save position.
• Restart — Restart the current book from the beginning.
• Forward / go forward — Seek forward by a specified time.
• Backward / go back — Seek backward by a specified time.
• Cancel / never mind / forget it — Cancel the current operation.
• Set a minute/hour sleep timer — Set a sleep timer to stop playback after the specified duration.
• Quit / exit / close — Exit the program cleanly.

Time-based commands such as "go forward ten minutes" or "rewind half an hour" are parsed by a dedicated time parser supporting both numeric and word-based expressions.

Certain specific commands may be used to trigger actions, for example:

• Read My Book — Plays the most recently listened to book.

Playback and Metadata

Each playback action updates metadata in library.db, maintaining position tracking across sessions. If playback begins near the end of a book (within ~30 seconds), the position automatically resets to zero for the next session.

Future Work

• User choice for when fuzzy matching resolves multiple strong candidates for a book or command.
• Volume control commands.
• Playback speed adjustment commands.

Status

Active development.