Skip to content

fix: an M4B with a cover keeps every chapter when it is tagged or merged - #529

Merged
kikootwo merged 4 commits into
mainfrom
fix/511-movie-timescale
Nov 2, 2026
Merged

kikootwo merged 4 commits into
mainfrom
fix/511-movie-timescale

Conversation

@kikootwo

@kikootwo kikootwo commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

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 chpl list), 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

  • New src/lib/utils/mp4-movie-timescale.ts: movieTimescaleArgs() returns ['-movie_timescale', '1000'] when ffmpeg -hide_banner -h muxer=mp4 lists 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.
  • Docs: 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.
  • E2E: fixture kind 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), scenario chapters-cover, spec regressions/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. With main'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 on main: 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.
  • E2E 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

  • Probe: 9.0.2 lists -movie_timescale ... (default 0), 8.1.2 lists it with (default 1000).
  • Real binary, ffmpeg 9.0.2 (the e2e unit image, same static build as CI): main 2 failed, 15 passed of 17 (the new file plus the existing tagger integration file); this branch 17 passed.
  • E2E on main's image (d2f81af): 511-chapters-cover fails 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). smoke passes on both images.

Checks

  • vitest related on the changed src files 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 --noEmit clean. ESLint: nothing new in the changed files (the two findings are on main too).
  • Image build: dockerfile.unified builds.
  • Full unit suite: PR Tests (CI).

Risk and rollback

  • Movie-level durations (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.
  • One extra ffmpeg -h muxer=mp4 call per process, before the first MP4 remux.
  • If a future ffmpeg drops the option, the probe stops listing it and RMAB passes nothing. The real-binary tests and the e2e spec would then show whether chapters still survive.
  • Rollback: revert this PR. The fix: an M4B whose chapters tagging would break is imported untagged, with its chapters #524 guard stays, so the worst case is back to the build before this fix: a file whose chapter table changes is imported untagged, and a file whose chapter track loses trailing samples is placed as it is.

Release note

  • Metadata tagging keeps the chapters of M4B files with an embedded cover again, and the files are tagged as before (Bug: Metadata tagging corrupts existing M4B chapter markers #511). Books imported with broken chapters since v1.2.4 aren't repaired: delete the book's file from the library and import it again. To check a file, ffprobe -v error -select_streams d -show_entries stream=nb_frames -of csv=p=0 book.m4b should print the book's chapter count.

🤖 Generated with Claude Code

kikootwo and others added 4 commits November 2, 2026 09:44
…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>
@kikootwo
kikootwo marked this pull request as ready for review November 2, 2026 15:37
@kikootwo
kikootwo merged commit aa3841f into main Nov 2, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/511-movie-timescale branch November 2, 2026 15:41
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.

Bug: Metadata tagging corrupts existing M4B chapter markers

1 participant