Skip to content

fix: an M4B whose chapters tagging would break is imported untagged, with its chapters - #524

Merged
kikootwo merged 1 commit into
mainfrom
fix/511-chapter-guard
Nov 2, 2026
Merged

kikootwo merged 1 commit into
mainfrom
fix/511-chapter-guard

Conversation

@kikootwo

@kikootwo kikootwo commented Nov 2, 2026

Copy link
Copy Markdown
Owner

Refs #511

What changed

  • New chapter guard (src/lib/utils/chapter-guard.ts). Before each tagged copy is placed in the library, the organizer (organize() in src/lib/utils/file-organizer.ts) compares the copy's chapter table with the source's: same number of chapters, the same titles in the same order, and each start and end within 0.1 s. The tables are read with ffprobe -show_chapters (argv list, no shell, 60 s timeout).
  • The check runs on the final tagged file, after the MP4 freeform (ASIN) step, right before placement.
  • On a mismatch the tagged copy is discarded and the original is imported exactly as with tagging off. The .tmp copy is removed as before. The job log gets one warning per file: Tagging changed the chapter table of <file> (N chapters before, M after, first change at chapter K), so it was imported without tags. The request shows the file was imported without metadata tags (tagging changed the chapter table), like the existing duration check.
  • If ffprobe cannot read the tagged copy, that counts as a mismatch. If it cannot read the source, the tagged copy is used as before and the failure is logged. A source with no chapters skips the check.
  • Every import that tags goes through organize(): download imports (torrent and usenet), Manual Import, Bulk Import, request retries and the failed-import retry job. Ebook imports and chapter merging do not tag, so they are unchanged. A merged M4B that gets tagged is checked against the merged file.
  • Docs: documentation/phase3/file-organization.md (new Chapter Guard section, the request message table, Fixed Issues Improve system logs page design and functionality #17) and documentation/TABLEOFCONTENTS.md.

Why

Since v1.2.4 the image ships ffmpeg 9.0.2. Its MP4 muxer writes zero-length chapters when the tagging remux (-codec copy ... -movflags +faststart -f mp4) copies an embedded cover next to the chapter track it rebuilds. ffmpeg exits 0, so RMAB placed the damaged copy, reported success, and cleanup later removed the good original. Tagging is on by default.

This change is a guard only. Affected files (an MP4 or M4B with an embedded cover and chapters) are now imported untagged, with their chapters intact, until a follow-up fix makes the tagging remux keep the chapters.

Evidence

  • Real binary: RMAB's tagging argv run with the released image's ffmpeg 9.0.2 (ghcr.io/kikootwo/readmeabook:1.2.11) on a 3000 s M4B with a cover and 4 chapters. The output has zero-length chapters 2 to 4 (ffmpeg warns Application provided duration ... is invalid, exit 0). The branch's checkTaggedChapters on the host reports changed for it (4 chapters before, 4 after, first change at chapter 2) and kept for the same remux of the source without a cover.
  • tests/utils/file-organizer.chapter-guard.test.ts runs the real organize() on temp folders with scripted ffprobe chapter tables: zero-length, missing, reordered and renamed chapters and a start moved by more than 0.1 s all import the original with the warning and leave no .tmp; matching tables (drift within 0.1 s) keep the tagged copy; a source with no chapters skips the check; an ffprobe failure on the tagged copy falls back; one on the source keeps the tagged copy and logs it; the check runs after the freeform step.
  • With main's src (abf3639): 9 of its 10 tests fail on an assertion (the tagged copy is placed, no warning, no chapter probe). The matching-tables test passes, as it should.
  • tests/utils/chapter-guard.test.ts covers the comparison (tolerance edge, titles, order, count, missing times) and the ffprobe argv.

Checks

  • Unit tests for the changed code (vitest related on the two changed src files, plus the two new test files): PASS
  • Type check and lint: PASS (tsc --noEmit clean; ESLint reports nothing new in the touched files compared with main)
  • No image build or E2E run: no change under src/app, the Dockerfile or the ffmpeg pin
  • Full unit suite: PR Tests (CI)

Risk and rollback

  • Two ffprobe -show_chapters reads per tagged file (the moov only, no packet walk). The duration check that already runs walks every packet twice, so the added time is small.
  • A tagged file whose chapter table changes for any reason, in any format, is now imported untagged. Files whose tagging keeps the chapters are unchanged.
  • Rollback: revert this PR. Nothing stored is rewritten.

Release note

  • Metadata tagging no longer damages the chapters of M4B files with an embedded cover. Until tagging is fixed for these files, they are imported without RMAB's metadata tags, with their original chapters, and the import log says so. Books already imported with broken chapters aren't repaired by this: delete the book's file from the library and import it again (Bug: Metadata tagging corrupts existing M4B chapter markers #511).

🤖 Generated with Claude Code

…e original imported untagged

ffmpeg 9.0.2 (pinned since v1.2.4) writes zero-length chapters when the
tagging remux copies an embedded cover next to the chapter track, and
exits 0. Before placement the organizer now compares the final tagged
copy's chapters with the source's (count, titles in order, start and end
within 0.1 s, via ffprobe -show_chapters). On a mismatch, or when the
tagged copy cannot be probed, the original is placed exactly as with
tagging off, the .tmp is removed, a warning is logged and the request
says the file was imported without tags. A source without chapters
skips the check; a source ffprobe cannot read keeps today's behaviour.

Refs #511.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo merged commit d2f81af into main Nov 2, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/511-chapter-guard branch November 2, 2026 14:06
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.

1 participant