kylemmkay/dustjacket repository overview

A tool for tagging and organizing audiobook files. Searches Audible and Hardcover for metadata, writes tags into m4b and mp3 files, and moves everything into a consistent folder structure.

⁠Key features

• Multiple interfaces: CLI⁠-first, with a full Web UI⁠ and TUI⁠ layered on top lets you use whichever fits your workflow
• Metadata search & matching: queries Audible and Hardcover APIs with automatic regional TLD detection from embedded ASINs; Hardcover returns consolidated + per-edition candidates with hint-aware edition ranking; confidence-scores candidates against audio duration, filename hints, and fingerprint; manual override always available.
• Tag writing: Create's ABS compatible metadata.json file and can (optionally) write ID3/MP4 tags directly into m4b and mp3 files; configurable import mode (replace all, replace present, fill missing, or per-field custom)
  • (Optional exclusion of metadata.json planned)
• Library reorganization: renames and moves files into a consistent Author / Year - Title [Series] / filename layout; dry-run preview before committing and reversal afterwards
  • ABS-safe: when Audiobookshelf API is configured, reorganization triggers an ABS backup first and waits for a library rescan before proceeding, preventing listening history loss from complex path changes.
• Background jobs: scheduled inbox scanning, confidence pre-scoring, thumbnail generation, and file enrichment (duration, bitrate, hash) allow for a cleaner library
• Import queue: non-interactive batch import via dj queue run; jobs survive restarts and can be monitored from the web UI job board

⁠Installation

git clone <repo>
cd audiobook-organizer
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Or with Docker:

docker compose up -d

Set PUID/PGID to match your media directory ownership. Full environment variable reference: docs/environment-variables.md⁠.

⁠Web UI

dj serve --host 0.0.0.0 --port 8000

FastAPI + HTMX web UI. Provides a library browser, import pipeline, metadata search, background jobs, and config editor.

More screenshots in docs/screenshots/⁠. Full reference: docs/web.md⁠.

⁠Terminal TUI

dj

Textual TUI with tabs for library overview, manual import, and metadata search. Confirm screen shows a metadata diff with per-field toggles and inline editing.

Full reference: docs/tui.md⁠.

⁠CLI

dj process ~/Downloads/my-book.m4b   # import a file
dj search "Dungeon Crawler Carl"      # metadata search
dj queue run --watch                  # drain the import queue
dj config init                        # first-time setup

dj process and dj search detect whether they're on a TTY: interactive runs open the TUI; --yes or piped runs are fully non-interactive.

Full command reference, config options, and output structure: docs/cli.md⁠.