audiobook-pipeline

The problem

A folder of loose MP3s becomes one tagged, chaptered M4B filed where Plex and Audiobookshelf expect it, with title, author, narrator, series, cover and ASIN matched by title and confirmed against the audio's real duration.

How it works

A uv-managed Python 3.13 app that uses ffmpeg for audio work. The pipeline is resumable: completed stages are recorded in data/work/pipeline.db and skipped on re-run. Modes (convert, enrich, metadata, organize) and policy levels (simple, normal, ai, full) are independent, and layered JSON config plus AUDIOBOOK_ env vars select paths and profiles. Optional OpenAI-compatible AI resolution is opt-in.

Features

• audiobook-convert, audiobook-audit and audiobook-watch commands
• Duration guard against matching a wrong edition
• Resumable stages and a DEBUG log on every run
• Read-only library audit and source-to-library diff
• Worked profile examples for Plex, Audiobookshelf, a watch-folder daemon and AI matching
• .author-override marker for franchise folders

How it was built

Work began on 2026-02-20 to turn folders of badly named MP3s into one tagged, chaptered M4B filed where a media server will match it.

The first version was Bash. After three days it worked but was hard to test, so it was rewritten in Python with typed models, resumable state and a real test suite.

Every phase started with a written plan and ended with a verification report. Archiving the source is gated on validating the M4B, and later releases copy and verify instead of moving.

A model is asked only to choose between ambiguous catalogue candidates, and remote chapter data that disagrees with the audio length is rejected.

Claude Opus wrote most commits as a pair programmer, with separate agent reviewers catching defects during the build. A later release added embedded catalogue ids after a media server's bulk match rewrote 646 items with wrong editions.