Repository navigation
Enhancement: Support for MP4 Chapters #2803
Description
Use case description
I'm working on improving Voice, an audio book player app. A common use case is to store audio books as a single m4a file (an mp4 container without video) with all metadata. This metadata includes chapters to be able to navigate within the book. Quite often the .m4b extension is used to mark the file as book.
There are two different standards for storing chapters, from which one is mostly preferred - but often both are contained in the file, since they are not exclusive:
- QuickTime chapters format (preferred)
- Nero chapters format (simpler, but more prone to errors)
Here is a short and good overview of how these formats are structured and how they can be parsed. Unfortunately androidx/media does not provide support for any of these formats and there isn't even an alternative mp4 library which is well maintained and ready to use. This forces most App developers to write a custom format parser to extract the chapters themselves, which leads to slower / redundant file parsing and less robust solutions, sometimes even uncaught exceptions / App crashes.
There was already an attempt for a PR to solve this problem (#1851), but it did not receive a response.
Proposed solution
Since media3 already contains a solution for MP3 / ID3v2 chapters, the proposed solution would be to use the existing data structures to store a mapping of the mp4 chapters, similar to the other metadata and to the PR mentioned above.
See these commits:
If two chapter formats (QuickTime + Nero) exist in parallel, the QuickTime variant is to be preferred - even if they might contain different data. The reason for this is that damaged or incomplete files most of the time also contain a damaged set of Nero chapters, that can't be parsed - while the QuickTime set stays intact most of the time due to more robust data structure.
Alternatives considered
As an alternative it might be less effort to first integrate only the Nero format using #1851 as a base implementation and later extend this solution to also support QuickTime in a separate task.
Activity
rohitjoins commentedon Sep 26, 2025
Hi @sandreas,
Sorry that PR #1851 was closed by the bot. I'll keep this issue open to track this enhancement.
sandreas commentedon Sep 26, 2025
Oh, there is no need to apologize :-) I just thought that A LOT of Apps would benefit from this and remind the maintainers.
If you need a way to prevent bots to close an issue or PR, you could try to add an exclusive label to leave specific tasks open:
Then label the issue with
work-in-progress. See https://github.com/actions/stale?tab=readme-ov-file#exempt-issue-labelsLet me know if I can help you with something, e.g. testing changes.
EDIT:
@rohitjoins Just for clarification: Are you planning to work on this anytime soon or is this just something that might happen or not in the future?
PylotLight commentedon Oct 6, 2025
I was working on something similar for audiobook support on wearos and have been running into similar chapter extraction issues.
Any chance we can get some action on this one, as all the 3rd party libs I found haven't been updated in years which seems to suggest we need to parse this manually until this gets native support?
Actually I might go with bundled ffprobe for now as simple but bloated option. That seems to handle the files relatively easily.
Add support for parsing QuickTime chapters from MP4 files
rohitjoins commentedon Mar 17, 2026
Hi @sandreas,
Thank you for opening this issue and providing detailed overview of the chapters formats!
We have added support for extracting both Nero and QuickTime chapters from MP4 files. To keep it format agnostic, we introduced a new
Chapterinterface.Additionally, just as you suggested, if an MP4 file contains both Nero and QuickTime chapters, the QuickTime chapters are preferred.
sandreas commentedon Mar 17, 2026
@rohitjoins
Awesome thank you!
Add support for parsing QuickTime chapters from MP4 files