Skip to content

feat(mux)!: adopt mp4-atom's counted trun samples - #7043

Closed
kixelated wants to merge 6 commits into
mainfrom
quest/m1/cut-audit/fmp4-sample-resolver
Closed

kixelated wants to merge 6 commits into
mainfrom
quest/m1/cut-audit/fmp4-sample-resolver

Conversation

@kixelated

@kixelated kixelated commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Parsing a moof no longer allocates per sample for trun runs that carry no per-sample field. The counted representation lands in kixelated/mp4-atom#254, and this PR adopts it in moq-mux.

  • mp4-atom (kixelated/mp4-atom#254): Trun.entries: Vec<TrunEntry> becomes Trun.samples: TrunSamples, an enum of Inherited { count, first_flags } (a field-less run, including the first-sample-flags-only run) and Explicit(Vec<TrunEntry>). TrunSamples::iter() yields TrunEntry values in either form without allocating. An Explicit run's capacity is bounded by the bytes left in the box, which replaces the 4096-entry cap. The AV1, BBB, and ESDS fixtures still decode.
  • moq-mux:
    • sample::Resolver::resolve, the segment-start keyframe scan, and the per-track fragment/kept rewrite now read trun.samples. The resolver counts its remaining samples in u64, so 1000 runs of u32::MAX can't overflow a 32-bit usize.
    • The segment-start keyframe scan stops after as many samples as the mdat has bytes. Every sample takes at least one byte, and the resolver refuses any past the mdat, so a forged run of u32::MAX non-sync samples can't spin it. Test fieldless_runs_do_not_stall_the_segment_scan covers this and hangs without the bound.
    • The trun literals in tests and the containers benchmark use samples: entries.into().
    • New test fieldless_runs_do_not_amplify: a moof of 1000 runs, each claiming u32::MAX samples, encodes under 16 KB. It decodes to 1000 counts, and the resolver stops at the first sample past the 6-byte mdat.
  • Updates the Opus surround and VR fields quests for 0.17 carrying dOps.
  • Deletes the quest and its link in the cut-audit epic.

Public API: breaking for mp4_atom::Trun through moq-mux's mp4_atom re-export (CHANGELOG entry added). MoQ wire: none.

Decisions needed

  1. Release mp4-atom 0.17.0. kixelated/mp4-atom#254 and #246 are merged. This PR pins moq-mux to mp4-atom main (3e150f9) as a git dependency and allows kixelated/mp4-atom in deny.toml's allow-git. A git dependency can't be published to crates.io, so this PR stays a draft until release PR kixelated/mp4-atom#247 merges. After the release, replace the pin with mp4-atom = { version = "0.17.0", ... }, revert the allow-git entry, and mark this PR ready.
  2. Release timing vs. Opus surround: settled 2026-10-28. kixelated/mp4-atom#246 ships in 0.17.0 too, and the m2 quests are updated to match. Since mp4-atom now decodes a nonzero dOps family, the fMP4 importer refuses it explicitly (UnsupportedMappingFamily) until that quest adds the import. The refusal test now builds a valid family 1 dOps.
  3. Close fix!: refuse nonempty field-less sample runs kixelated/mp4-atom#248: closed.
  4. The TrunSamples API shape is a proposal (see the mp4-atom PR body). Rename on Bump thiserror from 1.0.69 to 2.0.3 #254 if you prefer something else; moq-mux only uses iter(), len(), From<Vec<TrunEntry>>, the Inherited variant, and TrunSamplesIter::default().

Choices made without asking

  • Kept Defaults::resolve(&Tfhd, &TrunEntry)'s signature. Callers pass &entry now that the iterator yields TrunEntry by value (it is Copy in mp4-atom).
  • In fragment, the duration == Some(0) scrub only touches Explicit runs. An inherited run takes its duration from the tfhd, whose zero default is already cleared just above.
  • Test trun literals use vec![..].into() (an Explicit run) even when field-less. They encode to the same bytes as Inherited.

Testing

  • mp4-atom: cargo test --all-features (384 unit + 3 doc), cargo clippy --all-targets --all-features -D warnings, cargo fmt --check: all pass.
  • moq: cargo clippy -p moq-mux --all-targets --all-features -D warnings passes. cargo test -p moq-mux --all-features: 1809 passed, 0 failed. cargo deny check sources bans passes.
  • cargo bench -p moq-mux --bench containers -- cmaf-interleaved (1-byte and 4096-byte samples, 1/16 runs, 1/4 tracks), against a baseline from main. There is no consistent change: results swung both ways (−43% to +45%) with wide intervals on a host at load ~30–60. The bench's runs carry explicit fields, so they take the same Explicit path as before.
  • The full workspace just check and the JS side were not run; JS has no trun consumer.

Suggested follow-ups

  • None new. Once 0.17.0 is out, the release-swap step above finishes this PR.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

Pin moq-mux to kixelated/mp4-atom#254, which stores a field-less trun
run as a count, so a moof of many such runs decodes without one entry
per sample. Migrate the sample resolver, the segment-start scan, and
the per-track fragment rewrite to `Trun.samples`, and test that a moof
of 1000 u32::MAX-sample runs decodes and resolves only up to the mdat.

Swap the git pin for mp4-atom 0.17.0 once it is published.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Counted field-less trun entries feat(mux)!: adopt mp4-atom's counted trun samples Oct 28, 2026
kixelated and others added 3 commits October 28, 2026 12:26
An inherited trun run can claim u32::MAX samples in four bytes, so
walking every sample for a sync flag before the resolver bounds them
would trade the old per-sample allocation for a multi-billion step loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mp4-atom now decodes a nonzero dOps family instead of refusing it, so the
fMP4 importer refuses the table itself until surround Opus lands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Closing as superseded by moq-dev/moq#7308, as the maintainer decided on 2026-10-30.

#7308 merges this branch whole: the counted trun samples, the segment keyframe scan bound, and the deletion of quest/m1/cut-audit/fmp4-sample-resolver.md. It also swaps the git pin for the released mp4-atom 0.17.0, which was the only step left here, and reverts the deny.toml allow-git. On top of that, its review fixed one more bug: the keyframe scan's mdat budget reset per traf, and it now spans the whole moof. Nothing on this branch is lost when #7308 lands.

(Written by Claude Opus 5.5)

@kixelated kixelated closed this Oct 30, 2026
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