bookbot-cli 0.3.0

A cross-platform TUI audiobook renamer and organizer

BookBot

Declarative audiobook command center for collectors who care about clean metadata.

BookBot is a Textual powered terminal app and command line toolkit for taming large audiobook libraries. It discovers tracks, reconciles metadata across multiple providers, proposes safe rename plans, and can optionally retag, convert, and de-DRM your collection end to end.

Highlights

• Safety first workflow with dry-runs, atomic file operations, transaction history, and undo support.
• Fast metadata discovery that combines local heuristics with Open Library plus optional Google Books, LibriVox, and Audible lookups.
• Modern TUI for interactive review plus full CLI coverage for scripting and automation.
• Configurable templates and profiles so folders, file names, covers, and tags match the way your players expect them.
• Optional M4B conversion pipeline with FFmpeg stream copy, loudness normalization, and chapter generation.
• Audible authentication, DRM detection, and removal helpers for supported formats (AAX, AAXC, M4B, and more).

Installation

Docker is the fastest way to run BookBot with every dependency pre-baked. It keeps FFmpeg, optional DRM tooling, and Python libraries in one container so your host stays clean.

Docker (recommended)

docker run -it --rm \
  -v "/path/to/audiobooks:/data" \
  -v "$HOME/.config/bookbot:/root/.config/bookbot" \
  ghcr.io/itsbryanman/bookbot:latest tui /data

Mount your library into /data (or any path you prefer) and persist configuration under ~/.config/bookbot. Swap tui /data for other commands like scan /data or convert /book --profile conversion.

You can also add a convenience alias:

alias bookbot-docker='docker run -it --rm -v "$HOME/.config/bookbot:/root/.config/bookbot" -v "$PWD:/data" ghcr.io/itsbryanman/bookbot:latest'

Then run bookbot-docker tui /data from any library directory.

pipx (alternative)

pipx install bookbot

pipx keeps BookBot isolated and ensures the bookbot command lands on your PATH. If the executable is not found after install, add $HOME/.local/bin to your shell profile.

pip / virtualenv (alternative)

python -m pip install bookbot
python -m pip install "bookbot[conversion]"

You still need a system FFmpeg binary for audio conversion and DRM extraction.

From source

git clone https://github.com/itsbryanman/BookBot.git
cd BookBot
python -m pip install -e .[dev]

The editable install gives you live reload while iterating on the app.

Quick start

# 1. Inspect a library without touching files
bookbot scan /path/to/audiobooks

# 2. Launch the Textual TUI to review matches and approve changes
bookbot tui /path/to/audiobooks

#    Stay offline by reusing existing sidecar metadata
bookbot tui /path/to/audiobooks --metadata-from-files

# 3. Convert a finished book to a single tagged M4B
bookbot convert /path/to/book -o /path/to/output --normalize --chapters auto

# 4. Authenticate with Audible once, then import books by ASIN
bookbot audible auth
bookbot audible import B01234567X --remove-drm

Prefer a desktop entry point? bookbot gui launches the same Textual application and falls back to the CLI if GUI dependencies are missing.

Core workflows

Organize safely

• Every scan is a dry-run. Use the TUI preview to inspect proposed renames, covers, tags, and conversions.
• Confirmed changes are recorded as transactions so you can bookbot history and bookbot undo <id> at any time.

Tailor metadata

• Activate opinionated profiles (safe, full, plex, conversion) with bookbot config list and bookbot config show plex.
• Customize naming templates in ~/.config/bookbot/templates or swap templates at runtime with --template flags.

Bring your own providers

• Open Library is always on. Add Google Books, LibriVox, or Audible enrichment with:

  bookbot provider set-key googlebooks YOUR_API_KEY
  bookbot provider enable librivox
  bookbot provider enable audible
  bookbot provider list
  

• Audible marketplace defaults to US; switch with bookbot provider set-marketplace UK.

Convert and normalize

• Install FFmpeg, then enable the conversion profile or pass --profile conversion.
• Stream copy AAC sources when possible, or set bitrate/VBR/normalization flags per run.
• Chapters can come from tags, track order, or custom names depending on your config.

DRM tooling

• Detect protection on folders of files with bookbot drm detect ./library --recursive.
• Store activation bytes once using bookbot drm set-activation-bytes DEADBEAF.
• Remove DRM in place or to a clean output location using bookbot drm remove book.aax -o ./clean.

CLI cheat sheet

Command	Purpose
bookbot scan DIR	Inspect directories, infer series/disc structure, and surface warnings without touching files.
bookbot tui DIR...	Launch the interactive Textual interface to match metadata, approve rename plans, and start conversions. Add --metadata-from-files to reuse local NFO/JSON sidecars instead of online providers.
bookbot convert DIR -o OUT	Build single-file, chaptered M4B releases with optional normalization and artwork.
bookbot history --days 7	Review completed transactions and identify undo candidates.
bookbot undo ID	Roll back an operation safely using its transaction identifier.
bookbot provider ...	Enable, disable, and configure metadata providers and API keys.
bookbot config ...	Manage global config, reset defaults, and inspect profile settings stored under ~/.config/bookbot.
bookbot audible ...	Authenticate, list your library, and download titles directly from Audible.
bookbot drm ...	Detect DRM, save activation bytes, and convert protected files.
bookbot completions SHELL	Generate shell completions (bash, zsh, fish, or all).

Use --help on any command or subgroup for the full option set.

Configuration directory layout

Location	Purpose
~/.config/bookbot/config.toml	Primary configuration file persisted by the TUI and CLI.
~/.config/bookbot/profiles/*.toml	Saved profiles, including the bundled safe, full, plex, and conversion presets.
~/.cache/bookbot/	Cached metadata, cover art, and conversion plans. Delete to force fresh lookups.
~/.local/share/bookbot/transactions.json	Transaction history used for undo and audit logs.

Config files use TOML; edit by hand or via bookbot config commands.

Metadata providers

Provider	Notes
Open Library	Default, always enabled, free. Core search source for titles and authors.
Google Books	Requires an API key; adds richer descriptions and ISBN data.
LibriVox	Public domain library; great for narrator and language hints.
Audible	Requires authentication; unlocks commercial metadata and download tooling.

Provider priorities and fallback logic are configurable through the ConfigManager. Combine multiple providers for higher confidence matches.

Conversion pipeline

The conversion subsystem lives in bookbot.convert and wraps FFmpeg (through ffmpeg-python) to build high quality, chaptered M4B files. Highlights:

• Auto-detects when stream copy is safe to avoid re-encoding AAC tracks.
• Supports bitrate or VBR quality targets with optional EBU R128 loudness normalization.
• Generates chapter markers from track segmentation or existing tags.
• Embeds cover art and metadata pulled from the selected provider record.
• Writes conversion plans to disk so you can dry-run before touching anything (bookbot convert --dry-run).

DRM and Audible helpers

BookBot includes a focused DRM toolkit backed by ffmpeg and the audible Python package.

1. Authenticate once with bookbot audible auth; credentials are stored securely via keyring.
2. List your library (bookbot audible list --limit 50) or import specific titles by ASIN.
3. Use bookbot drm detect to map protected files and bookbot drm remove to produce DRM-free audio. Activation bytes can be supplied per run or cached via bookbot drm set-activation-bytes.

Retrieving Activation Bytes

For DRM removal of Audible files, you'll need your account's activation bytes. BookBot can retrieve these for you.

Dependencies:

This feature requires selenium and chromedriver. If you are not using the Docker image, you will need to install them:

pip install selenium
# Make sure chromedriver is in your PATH

Usage:

Run the following command and follow the prompts to enter your Audible username and password:

bookbot audible get-activation-bytes

This will securely save your activation bytes for future use. After this one-time setup, you can remove DRM from your books without needing to provide the activation bytes every time.

These features depend on optional packages (audible, cryptography, keyring, selenium) that are already declared in pyproject.toml. Ensure FFmpeg is compiled with the modules required for Audible AAX/AAXC processing.

Development

make install-dev   # install dev dependencies
make lint          # ruff + mypy
make format        # black
make test          # pytest
make pre-commit    # run the full formatting and lint bundle

Textual ships with a live reload server: run textual run --dev bookbot.tui.app:BookBotApp while editing the TUI.

Contributing

We welcome issues and pull requests. Please:

1. Fork the repo and create a feature branch.
2. Add or update tests under tests/ for any new functionality.
3. Run make pre-commit before submitting to keep style and typing checks green.
4. Document user-facing changes in this README or the changelog if applicable.

License

BookBot is released under the MIT License. See LICENSE for the full text.