Repository navigation
fix: an M4B with a cover keeps every chapter when it is tagged or merged - #529
Merged
Merged
Conversation
…ged (#511) FFmpeg 9 sets the mp4 movie timescale to the LCM of every stream's time base. With a cover next to 22.05 or 44.1 kHz audio that is 4,410,000, so a chapter over 487 s no longer fits the chapter track and ffmpeg drops or clamps it while still exiting 0. Both MP4 writers (tagging remux, chapter merge) now pass -movie_timescale 1000, the value ffmpeg 8 used, when the mp4 muxer lists the option (probed once per process). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… chapter track New fixture kind m4b-cover-chapters (cover, 22.05 kHz silence, chapters 100/600/600 s, tags that are not the book's) and scenario chapters-cover. The spec checks the library file's chapter table, its chapter track's sample count and time base, cover, tags, the guard warning and the Audiobookshelf chapters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d spec Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An intact file tagged by v1.2.4-v1.2.12 can show a chapter-track time base other than 1/1000, so the docs name the frame count as the check. Test comment reworded. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #511
Summary
FFmpeg 9 picks the MP4 movie timescale from all streams (the LCM of their time bases, FFmpeg commit 51f5f60443, in every 9.0.x and still on master). The chapter track uses that timescale. With a cover image (1/90000) next to 22.05 or 44.1 kHz audio it is 4,410,000 units per second, so a chapter longer than 487 s no longer fits: ffmpeg drops or clamps it and still exits 0. That is how tagging damaged M4B chapters since v1.2.4. RMAB now sets the timescale to 1000, the value ffmpeg 8 and earlier used.
There is a second pattern the #524 guard can't see. When only the trailing chapters are long, ffprobe still shows the full chapter table (it is rebuilt from the Nero
chpllist), but the chapter track has lost samples (one of three in the test file), so players that read the track show fewer chapters. The fix covers both.Books already damaged aren't repaired: delete the book's file from the library, then import it again.
Changes
src/lib/utils/mp4-movie-timescale.ts:movieTimescaleArgs()returns['-movie_timescale', '1000']whenffmpeg -hide_banner -h muxer=mp4lists the option, otherwise[]. The probe runs once per process (shared by concurrent callers). A failed probe gives[], is logged once at debug level, and runs again on the next call. The option exists from FFmpeg 5.0. An older build would reject it and fail every MP4 tag and merge, and it already writes 1000, so it gets no flag.metadata-tagger.ts: the MP4 tagging argv passes it before-movflags +faststart. MP3 and FLAC argv are unchanged.chapter-merger.ts: the merge argv (copy and re-encode) passes it too. A merged chapter over 12.4 h at 48 kHz (13.5 h at 44.1 kHz) broke the same way. The ffmetadata is already 1/1000, so chapter times don't change.chapter-guard.ts: header comment corrected (the cause is the timescale). The guard stays as the safety net.phase3/file-organization.md(new MP4 Movie Timescale section with the limits table and a check for a placed file, the guard section, Implementation, Requirements, Fixed Issues Improve system logs page design and functionality #17),features/chapter-merging.md,deployment/unified.md(run the chapter tests on any ffmpeg bump),testing/e2e-harness.md,TABLEOFCONTENTS.md.m4b-cover-chapters(martian-m4b-cover: cover, 22.05 kHz silence, chapters 100/600/600 s, tags that aren't the book's, about 0.2 MB), scenariochapters-cover, specregressions/511-chapters-cover.spec.ts.Tests
tests/utils/mp4-movie-timescale.test.ts(13): the probe (listed, not listed, once per process with concurrent callers, failure logged once and retried), the tagger argv for .m4b/.m4a/.mp4 with and without the option listed, MP3 and FLAC never probe or get the flag, the merger argv for copy and re-encode with and without it. Withmain's tagger and merger: 5 of 13 fail (the five argv-with-flag cases).tests/utils/metadata-tagger.chapters.integration.test.ts(2, real ffmpeg, skips without it): a generated M4B with a cover tagged the way the organizer does it (ffmpeg remux, then the freeform step). Cases: chapters 100/600/600 s, and six mixed chapters (20 s to 1513 s, non-ASCII titles), both 22.05 kHz. Each checks the ffprobe chapter table, that the chapter track has one sample per chapter at time base 1/1000, the cover and the audio packets. With ffmpeg 9.0.2 (the CI pin) both fail onmain: 1 of 3 samples at 1/4410000 with the table intact, and 4 of 6 samples at 1/4410000 with the table damaged. Both pass on this branch.511-chapters-cover: torrent download, organize with tagging on and merging off, real Audiobookshelf scan. It checks the library file's chapter table, its chapter track (sample count and time base), the cover, the book's title and author (not the fixture's),media_type, the ASIN tag, no guard warning, no "imported without metadata tags" message, and the Audiobookshelf chapters.Evidence
-movie_timescale ... (default 0), 8.1.2 lists it with(default 1000).main2 failed, 15 passed of 17 (the new file plus the existing tagger integration file); this branch 17 passed.main's image (d2f81af):511-chapters-coverfails on one check only, the chapter track: 1 sample of 3 at time base 1/4410000. The chapter table, the Audiobookshelf chapters, cover and tags all read fine, and the fix: an M4B whose chapters tagging would break is imported untagged, with its chapters #524 guard logged nothing. On this branch's image: passes (3 samples at 1/1000).smokepasses on both images.Checks
vitest relatedon the changedsrcfiles plus the new tests: 1683 passed, 1 skipped. Two Goodreads RSS tests timed out under load in that run and pass when run alone (14 of 14).tsc --noEmitclean. ESLint: nothing new in the changed files (the two findings are onmaintoo).dockerfile.unifiedbuilds.Risk and rollback
mvhd,tkhd, edit list) go back to milliseconds, as in ffmpeg 8 and RMAB up to v1.2.3. Audio packets, cover and stream durations are unchanged (checked in the real-binary test). Chapter times round by at most 0.5 ms.ffmpeg -h muxer=mp4call per process, before the first MP4 remux.Release note
🤖 Generated with Claude Code