m4b-audiobook

name	m4b-audiobook
description	Assemble m4b audiobook from audio files with chapters, metadata, and cover art.
argument-hint	[directory]
allowed-tools	Bash, Read, Glob, Grep, Write, AskUserQuestion

Assemble a single .m4b audiobook from a directory of audio files. Adds chapter markers, metadata, and cover art.

Prerequisites

• ffmpeg and ffprobe must be installed

Arguments

• directory — path to the directory with audio files. If omitted, use the current working directory.

Process

1. Inventory

List all audio files in the directory. Supported formats: .m4a, .mp3, .aac, .ogg, .opus, .flac, .wav.

Also look for a cover image: .jpg, .jpeg, .png files with names suggesting cover art (e.g., cover, folder, front, or any single image file present).

2. Determine file order

Analyze filenames to determine the correct playback order. Common patterns:

• Numeric prefixes: 01 - Title.m4a, 1.1. Title.m4a
• Chapter/part indicators: Chapter 1, Part 1, Глава 1, Часть 1
• Structured names: Week 1. 1.1. Title, Неделя 1. 1.1. Title

Sort rules:

• Group by logical sections (introduction, parts/chapters/weeks, ending/epilogue)
• Within each group, sort by numeric indicators
• Files without clear numbering: sort alphabetically within their group

Present the proposed order to the user. Ask for confirmation before proceeding.

3. Determine metadata

Try to extract metadata from:

• Directory name
• Existing tags in audio files (ffprobe output)
• File naming patterns

Required metadata fields:

• title — book title
• artist / album_artist — author name
• album — same as title (convention for audiobooks)
• genre — set to Audiobook
• date — year if determinable from file metadata
• language — detected from content/filenames (e.g., rus, eng)

Present proposed metadata to user. Ask for confirmation or corrections.

4. Probe audio formats

Run ffprobe on each file to determine:

• Codec (aac, mp3, flac, etc.)
• Sample rate
• Channels
• Bitrate

If all files share the same codec and parameters: use -c:a copy (no re-encoding — fast and lossless).

If formats differ: re-encode to AAC-LC. Choose parameters:

• Sample rate: use the most common value across files
• Bitrate: 64k for mono, 128k for stereo (or match source if higher)
• Channels: preserve original (mono/stereo)

5. Generate chapter names

Create clean chapter titles from filenames:

• Strip file extensions
• Strip leading numeric prefixes (e.g., 01 - , 1.1. )
• Keep meaningful structure (e.g., Неделя 1. prefix for week-based books)
• Fix obvious truncation from long filenames (e.g., Задани → Задания if context is clear)
• Use em-dash — instead of hyphen - in Russian text where appropriate

6. Build concat list

Create filelist.txt for ffmpeg concat demuxer:

file '/path/to/first file.m4a'
file '/path/to/second file.m4a'

Escape single quotes in filenames: replace ' with '\''.

7. Build chapter metadata

Get exact duration of each file in milliseconds:

ffprobe -v quiet -show_entries format=duration -of csv=p=0 "file.m4a"

Generate chapters.txt in FFMETADATA1 format:

;FFMETADATA1
title=Book Title
artist=Author Name
album=Book Title
album_artist=Author Name
genre=Audiobook
date=2024
language=eng

[CHAPTER]
TIMEBASE=1/1000
START=0
END=473590
title=Chapter Title

[CHAPTER]
TIMEBASE=1/1000
START=473590
END=960000
title=Next Chapter

Each chapter START equals the previous chapter END. Calculate from cumulative durations.

8. Assemble m4b

Run ffmpeg:

ffmpeg -y \
  -f concat -safe 0 -i filelist.txt \
  -i chapters.txt \
  -i cover.jpg \
  -map 0:a -map 2:v \
  -c:a copy \
  -c:v copy \
  -disposition:v:0 attached_pic \
  -map_metadata 1 \
  -map_chapters 1 \
  -movflags +faststart \
  "Author - Title.m4b"

Adjust flags:

• If re-encoding needed: replace -c:a copy with -c:a aac -b:a 128k (or appropriate bitrate)
• If no cover image: remove -i cover.jpg, -map 2:v, -c:v copy, -disposition:v:0 attached_pic
• Output filename: Author - Title.m4b (from metadata)

9. Verify

After assembly, verify the output:

ffprobe -v quiet -show_format -show_chapters output.m4b

Confirm:

• All chapters present with correct titles
• Metadata fields populated
• Cover art stream present (if provided)
• Total duration matches sum of source files

Report results to user: filename, size, duration, chapter count.

10. Cleanup

Remove temporary files (filelist.txt, chapters.txt).

Error handling

• If ffmpeg is not installed: suggest brew install ffmpeg
• If no audio files found: report and stop
• If ffmpeg fails: show the error output, suggest possible fixes
• If concat produces audio glitches (different sample rates): fall back to re-encoding