Skip to content

feat(mux)!: a finished MP4 carries chapters - #9284

Draft
kixelated wants to merge 2 commits into
mainfrom
quest/m1/mp4-chapters
Draft

kixelated wants to merge 2 commits into
mainfrom
quest/m1/mp4-chapters

Conversation

@kixelated

@kixelated kixelated commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Completes quest/m1/mp4-chapters.md.

Summary

container::mp4's Export::finish and repair take a list of Chapter { time: Timestamp, title: String } and write them into the finished moov in both forms the quest decided on:

  • Nero's chpl box in the moov's udta.
  • A QuickTime chapter text track (hdlr text, a tx3g sample entry, nmhd), linked from the first track (the video track when there is one) by tref chap. Each sample is a 16-bit length, the UTF-8 title, and an encd atom as ffmpeg writes it. A chapter lasts until the next starts, the last until the movie ends, and a first chapter after the movie's start sits behind an empty edit. The track is not enabled, so a player lists it instead of drawing it.

The text lies in an mdat between the media and the moov, so a finish still ends with the moov and repair stops at that mdat as it does at the moov. Finish::moov became tail (the text mdat if any, then the moov), so a repair compares the whole trailer and a file finished with other chapters is finished again.

Each chapter's time maps onto the movie's time through the earliest track start, which only moq-mux knows; a chapter before the first sample or at or after the movie's end is dropped, not clamped. Chapters are sorted by start (stable). Moq-cli passes none.

Impact

Breaking, Rust only (no wire or JS counterpart: moq-mux MP4 export has none).

  • container::mp4::Export::finish(self) is now finish(self, chapters: &[Chapter]).
  • container::mp4::repair(file) is now repair(file, chapters: &[Chapter]).
  • New container::mp4::Chapter, and fmp4::Error::{TooManyChapters, ChapterTitleTooLong}.

Migration: pass &[] to keep today's output byte for byte.

Validation

  • cargo test -p moq-mux --lib container:: (1431 passed) and cargo clippy -p moq-mux -p moq-cli --all-targets clean.
  • New tests: both forms list the same chapters in order; placement on the broadcast timeline for a movie starting at 1 s (before and after dropped); no in-range chapter gives the finish a recording without chapters; the 255 limits; repair with other chapters; and the existing crash-at-every-write test repeated with chapters (every crash state plays and repairs to the same finish).
  • Real surface: finished and repaired files from a scratch test (not committed) with audio, video starting at 2 s and a chapter before the start, run through ffprobe 9.0.2. Both files list Intro 0.0-0.9 s and Café 🎬 0.9-2.97 s, and the files are byte-identical. With chpl renamed away, or with tref chap renamed away, ffprobe still lists both chapters, so each form works alone. The unfinished file lists none.
  • Not run: Apple's players (kixtop was offline). Follow-up below.

Decisions

Recommendations taken for review to undo:

  • Chapter.time is a moq_net::Timestamp (the clock frames use) and finish/repair take a slice, since markers are only known when the recording ends. No builder method.
  • More than 255 chapters or a title over 255 bytes (the chpl box's one-byte counts) fails the finish with an error instead of truncating or dropping, per fail loud. A caller can finish again without them, or repair.
  • The text track uses a tx3g sample entry under a text handler, because mp4-atom cannot encode QuickTime's text entry. ffmpeg reads it; Apple's reader is the follow-up.
  • Two chapters in the same movie tick keep both, in the order given, so the text track gets a zero-length sample.
  • The text track's timescale is the movie's, so chapters are exact to the movie's tick, and chpl is derived from the same ticks.
  • The chapter text goes in a second mdat before the moov rather than after the moov, so the moov stays last and its chunk offset needs no second pass.

Follow-ups

Models

Size: S
Implementer: Claude, claude-sonnet-5-5, high effort (arm B)

(Written by Claude Sonnet 5.5 with high effort)

🤖 Generated with Claude Code

Review

Rewritten by quest review after each round.

  • Head: 12b1ead, named in full once no reviewer reports a finding

  • Base: origin/main at 3728b96

  • Risk: high, Changing the public Rust finish and repair signatures breaks downstream callers, and changing exported MP4 structure can affect players consuming recordings; reverting restores the code but does not undo files already written.

  • Classified: high by Codex, gpt-6.1-sol, low effort, session 01a1fc0a-fc64-7c52-b49a-6ba8a7413141

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1fc0b-1492-79f2-9db6-7b0a8043baad, round 1

  • Score: 7/10, The chapter track needs an independent, lower timescale so valid long recordings can finish and repair successfully.

  • Rounds: 1; first round 1 (medium 1); findings 1 (medium 1): fixed 0, refuted 0, open 1

  • Findings, open until the next round settles them:

    • Medium, rs/moq-mux/src/container/mp4.rs:766: Give chapter samples an independent, lower timescale
  • Reviewer: Codex, gpt-6.1-sol, low effort, shadow

  • Session: 01a1fc0b-14a5-7e81-a500-f5588db989ab, round 1

  • Score: 7/10, The chapter export is largely coherent, but repair must preserve existing chapter metadata before landing.

  • Rounds: 1; first round 1 (high 1); findings 1 (high 1): fixed 0, refuted 0, open 1

  • Findings, open until the next round settles them:

    • High, rs/moq-cli/src/repair.rs:61: Preserve existing chapters when repairing from the CLI

kixelated and others added 2 commits November 20, 2026 18:09
Quest-Claim: 45a3c691cf93d56c
Export::finish and repair take a list of chapters and write them into the finished moov as a chpl box and a QuickTime chapter text track.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title A finished MP4 carries chapters feat(mux)!: a finished MP4 carries chapters Nov 21, 2026

This branch has not been deployed

No deployments
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