Skip to content

feat: play .m4b audiobooks with embedded chapters - #74

Merged
BasilSkyWalk merged 2 commits into
BasilSkyWalk:mainfrom
micdudk:feature/m4b-audiobooks-w-chapters
Nov 11, 2026
Merged

BasilSkyWalk merged 2 commits into
BasilSkyWalk:mainfrom
micdudk:feature/m4b-audiobooks-w-chapters

Conversation

@micdudk

@micdudk micdudk commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

What

Adds .m4b files and the chapters embedded in them (the Nero chpl atom, written by m4b-tool, mp4v2 and ffmpeg).

![Choosing a chapter](ATTACH chapters.gif HERE)

  • .m4b is scanned, fingerprinted and decoded like .m4a, on the device, in the simulator and in tools/library_index.py.
  • The scanner and the PC indexer count a file's chapters into the track record's last u16. At most 255 are counted. 0 means none, unreadable, out of order, or a 64-bit atom size.
  • Now Playing shows "Chapter N of M" in place of the queue place.
  • The Up Next screen becomes the chapter list while a book with chapters plays. Rows are "Chapter N of M" with the start time, the current chapter is selected, and picking one seeks to it.
  • A single-file book keeps its chapter in its bookmark. Its shelf row shows "N chapters" or "Chapter N of M".
  • New string STR_MENU_CHAPTERS, translated in every language.

Vol+/Vol- still jump 30 s / 15 s, and nothing else in the player's behaviour changes. Chapter titles are not read or shown.

Library format

The track record's last u16 was reserved, and it now holds chapters. The format stays version 3. A library built before this change reads 0 there, so books show no chapters until the next rescan. docs/library-format.md is updated, and tests/fixtures/tags_library.db and two_drives.db are regenerated.

Memory

  • The player keeps the chapter starts of the current book as uint16 gaps in whole seconds: 160 chapters in about 330 bytes. A first version with 255 uint32 starts pushed static RAM over the audit budget by about 600 bytes.
  • A book with more than 160 chapters is counted in the library but shows no chapters in the player. A chapter longer than 18 hours is refused.
  • Starts are rounded down to the second, so a jump to a chapter can land up to a second early.
  • Code window: 6,396 bytes free in release (150,896 of 157,292), 4,428 free in the device preset.

Not included

  • Chapter titles.
  • QuickTime text-track chapters.
  • Chapters of a multi-file book folder (it keeps one entry per file).
  • Files with a 64-bit atom size (over 4 GB).

These are listed in docs/known-issues.md.

Tests

New test_mp4_chapters (parser, damaged and truncated files, failing source, more than 160 chapters, backwards starts), a chaptered fixture (tests/fixtures/tags/chapters.m4b) in the scan, builder and PC indexer comparisons (the reference builder and random library generator carry the field), and tests for the shelves, Now Playing, the chapter list and the language packs.

All tests pass in the dev preset except fonts_up_to_date, which fails on my machine for a reason unrelated to this change.

Tested on a real device with a chaptered book, on the final build (rebased on 0.11.1, with the reduced chapter table): Now Playing, the chapter list, jumping to a chapter and resuming from the bookmark all work.
chapters

Reads the Nero chapter list (moov.udta.chpl) of an .m4b or .m4a file.
Chapter titles are not kept.

- The scanner and the PC indexer count a file's chapters into the track
  record's last u16 (up to 255). The library format stays version 3, and
  a library built earlier reads 0 there.
- .m4b is scanned, fingerprinted and decoded like .m4a.
- The player loads the chapter starts of a spoken track with chapters
  (the first 160, as whole-second gaps in 330 bytes) and reports the
  chapter count and the current chapter.
- Now Playing shows "Chapter N of M" in place of the queue place. The
  Up Next screen becomes the chapter list, and picking a chapter seeks
  to it. Vol+/- still jump 30 s / 15 s.
- A single-file book keeps its chapter in its bookmark, and its shelf
  row shows "N chapters" or "Chapter N of M".
- New string STR_MENU_CHAPTERS, translated in every language.
- Tests for the parser, the scanner, the builder, the shelves and both
  screens; a chaptered fixture; docs.
Regenerates the Polish pack and the tags and two-drive library fixtures.
@BasilSkyWalk
BasilSkyWalk merged commit c69270f into BasilSkyWalk:main Nov 11, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants