chapterize — turn flat audiobooks into chaptered, open-format files

A flat .mp3 audiobook is one long track. No chapter list, no "resume at chapter 12", no skip-to-next in the car. Most tools that "add chapters" either guess at boundaries with silence detection or split the file into equal chunks — both of which are wrong the moment a chapter runs long or a narrator pauses for effect.

chapterize does neither. It pulls the publisher's actual chapter markers — the exact titles and timestamps shipped on Audible — and writes them into an open-format file. It's a thin, dependency-free Python wrapper around ffmpeg/ffprobe, runs on macOS and Linux, and ships with both a CLI and a small GUI.

Repo: github.com/cwfrazier1/chapterize

Why Opus-in-Matroska

The default output is **Opus audio inside a Matroska (.mka) container**. Both the Opus codec and the Matroska container are open and royalty-free, and — unlike Ogg/Opus — ffmpeg writes real chapter markers into Matroska reliably. Opus at 64k mono is transparent for speech and shrinks a typical audiobook by more than half. If you need broader player support, m4b (AAC, for Apple Books) and opus (Ogg) are one flag away.

Install

git clone https://github.com/cwfrazier1/chapterize.git
cd chapterize
./install.sh          # installs ffmpeg if missing, then the app into ~/.local

chapterize needs ffmpeg and ffprobe on your PATH. On macOS that's brew install ffmpeg; on Debian/Ubuntu, apt install ffmpeg python3-tk.

CLI

The only chapter source is Audible's official markers. Point it at a file and give it the ASIN:

# Chapter a flat file with the publisher's real markers
chapterize convert book.mp3 --asin B0D7WF35B4

# Don't know the ASIN? Let it search Audible by title/author
chapterize convert book.mp3 --title "Dead Med" --author "Freida McFadden"

# Preview the chapters without encoding anything
chapterize convert book.mp3 --asin B0D7WF35B4 --dry-run

# Just look up a book's official chapters
chapterize audible "Project Hail Mary" --search   # list editions + ASINs
chapterize audible --asin B0D7WF35B4               # one exact edition

# Inspect a file and any chapters it already has
chapterize probe audiobook.mp3

The one catch: edition runtime has to match

Audiobooks that were re-recorded or re-released — different narrator, revised edition — have different timestamps. If the Audible edition's runtime doesn't match your file, the markers won't line up. chapterize warns loudly when the runtimes drift, so pick the ASIN whose length matches your audio (chapterize audible … --search compares editions side by side).

Output formats

| Format | Container | Codec | Notes | |--------|-----------|-------|------------------------------------------------| | mka | Matroska | Opus | Default. Fully open, reliable chapters. | | opus | Ogg | Opus | Chapters via VorbisComment (less widely read). | | m4b | MP4 | AAC | Best player compatibility (Apple Books, etc). |

Pick one with -f, e.g. chapterize convert book.mp3 --asin B0… -f m4b.

GUI

chapterize-gui

Pick an input file, give the ASIN (or a title/author to look up), set title, author and cover, hit Preview chapters to sanity-check the markers, then Convert.

macOS note: the GUI needs Tk 8.6+. The /usr/bin/python3 that ships with macOS bundles Apple's deprecated Tk 8.5, which renders Tk windows blank. Run the GUI under a python.org build, a Homebrew python-tk, or any standalone CPython — all bundle Tk 8.6+. chapterize detects Tk 8.5 and warns. The CLI has no such limitation.

Cover art, the right way

One subtlety worth calling out: Matroska cover art has to be a container attachment, not a video stream carrying an attached_pic disposition. Embed it the wrong way and players like Audiobookshelf, Jellyfin and VLC silently ignore it. chapterize attaches the cover as cover.jpg with the proper mimetype/filename metadata so it actually shows up.

That's the whole thing — flat file in, real chapters out, in a format that'll still open in ten years.