M4B Audiobook Builder

Overview

Build a single player-friendly M4B from many audio parts or merge existing M4B parts while preserving metadata, normalizing text to UTF-8, and generating chapters. Keep details in references/guide.md and use the helper script for repeatable inputs.

Workflow

1. Confirm the scenario (mixed audio files vs existing M4B parts) and collect target metadata (title, author, performer/narrator, cover art) from the source files metadata, folder names, and file names. Cover art may be embedded in the metadata of the source audio files or provided separately as file cover.jpg or same.
2. Determine actual playback order; do not assume lexical filename order for multi-part M4B sets.
3. Choose the best merge order, metadata source, and cover image source yourself using metadata and sidecar/embedded art, then draft a single action plan that proposes those choices.
4. Normalize filenames and tags to UTF-8, assuming Russian for any non-UTF-8 text.
5. Show all the metadata and the order to the user and ask them to confirm the action plan (or adjust it) once before merging. Batch order, metadata, and cover questions into this one confirmation. After confirmation, do not ask follow-ups; proceed to merge/recode and apply the confirmed metadata.
6. Minimize model queries: batch related checks by combining multiple console commands and present consolidated outputs.
7. Generate concat lists and chapters:
   • For mixed audio files, run the helper script to emit files.txt and meta.txt.
   • For existing M4B parts, generate only files.txt and follow the reference for chapter merging.
   • If per-file chapters are too fine-grained compared to the real book chapters, prefer per-directory chapters or a curated chapter list.
8. Build the output M4B with ffmpeg:
   • Re-encode heterogeneous inputs.
   • If a source codec is exotic or poorly supported, re-encode to a well-supported codec (AAC for M4B is the default).
   • Use multi-threaded modes where supported (e.g., ffmpeg -threads) to speed up transcoding.
   • If the merge is long-running, set a sufficiently long command timeout in your runner up front (e.g., Codex CLI timeout_ms) to avoid re-runs.
   • If inputs may contain embedded cover art (common in MP3), map audio only (e.g., -map 0:a:0 -vn) to avoid accidental video streams.
   • Use -c copy only when M4B parts share compatible codecs.
9. Apply audiobook metadata and cover art. Treat author and performer as distinct fields (author for albumArtist, performer/narrator for artist) and format person names as Last First. If cover art found, embed it in the final M4B.
10. Validate with mediainfo, mp4info, and a target player.

Helper Script

Run:

python3 scripts/build_m4b_inputs.py --root . --recursive --chapter-mode dir --files-out files.txt --meta-out meta.txt --ffmpeg-out ffmpeg.sh --output-m4b book.m4b

Use this to create:

• files.txt for ffmpeg concat input
• meta.txt for ffmpeg chapter metadata
• ffmpeg.sh with a ready-to-run ffmpeg command line (use --no-ffmpeg-out to skip)
• atomicparsley.sh with a ready-to-run metadata command (use --no-atomicparsley-out to skip)

To generate a safe output filename like Author - Title.m4b, supply --output-author and --output-title (invalid filesystem characters are replaced). The script reorders author names to Last First by default when building the filename (use --name-order keep to preserve input). If omitted and --output-m4b is left at book.m4b, the script derives author/title from the first input's tags and falls back to the folder name. If --output-m4b lacks the extension, .m4b is appended.

python3 scripts/build_m4b_inputs.py --root . --chapter-mode file --files-out files.txt --meta-out meta.txt --output-author "Author" --output-title "Title"

Use --chapter-mode file for per-file chapters, or --chapter-mode none to generate only files.txt. For file chapters, the script prefers embedded track titles when present and falls back to filenames. Use --chapter-mode file only when file boundaries match real chapters; otherwise prefer dir or a curated chapter list.

For multi-part M4B sets, propose a merge order before any concat work:

python3 scripts/propose_m4b_order.py --root . --files-out files.txt

Use the proposed order and metadata/cover suggestions to build an action plan and ask the user to confirm before merging.

Extract and embed cover art (sidecar image or embedded metadata):

python3 scripts/cover_art.py --root . --recursive --output cover.jpg --embed book.m4b

References

Use references/guide.md for detailed commands, chapter formats, and scenario-specific procedures.