Expose flags on Tkhd

[iameli]

Ran into this while working on the MUXL spec; I think having track_in_movie set is probably a sensible default. Now we can do that!

From Claude:

The tkhd box has three flag bits: track_enabled (bit 0), track_in_movie (bit 1), and track_in_preview (bit 2). Previously only track_enabled was exposed as a public field. The other two were decoded but discarded, and always written as false on encode.

Add in_movie and in_preview fields to Tkhd so callers can read and write all three flags. Update all test expectations to match the actual flag values in their respective fixtures.

[coderabbitai]

Walkthrough

The Tkhd struct in src/moov/trak/tkhd.rs was extended with two boolean fields: in_movie and size_is_aspect_ratio. TkhdExt flag mapping was updated and decode/encode logic now reads/writes these flags (track_in_movie and track_size_is_aspect_ratio; track_in_preview is written mirrored from in_movie and ignored on read). Unit tests for Tkhd (32/64) and many codec-specific test fixtures were updated to initialize the new in_movie field.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Expose flags on Tkhd' directly and clearly describes the main change: making previously internal flags publicly accessible on the Tkhd structure.
Description check	✅ Passed	The description explains the motivation and what was changed: exposing track_in_movie and track_in_preview flags on Tkhd structure that were previously decoded but discarded.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/moov/trak/tkhd.rs (1)

198-199: Consider adding a direct serialized-flags assertion in unit tests.

Current tests are round-trip based; adding one direct assertion on the version+flags word would make bit-position regressions easier to catch.

Suggested test hardening

 #[test]
 fn test_tkhd32() {
     let expected = Tkhd {
         creation_time: 100,
         modification_time: 200,
         track_id: 1,
         duration: 634634,
         layer: 0,
         alternate_group: 0,
         volume: 1.into(),
         matrix: Matrix::default(),
         width: 512.into(),
         height: 288.into(),
         enabled: true,
         in_movie: true,
         in_preview: false,
     };
     let mut buf = Vec::new();
     expected.encode(&mut buf).unwrap();
+    // size(4) + kind(4) + version/flags(4)
+    assert_eq!(&buf[8..12], &[0x01, 0x00, 0x00, 0x03]);

     let mut buf = buf.as_ref();
     let decoded = Tkhd::decode(&mut buf).unwrap();
     assert_eq!(decoded, expected);
 }

Also applies to: 223-224

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/moov/trak/tkhd.rs` around lines 198 - 199, Tests currently only
round-trip the TrackHeaderBox; add a direct assertion that the packed
version+flags 32-bit word matches the expected literal to catch bit-position
regressions. In the unit test for TrackHeaderBox (the case that sets in_movie:
true and in_preview: false) call the serializer used (e.g.,
TrackHeaderBox::to_bytes / write_box / serialize) and extract the first 4 bytes
(version+flags) or use the helper that builds the version_and_flags word, then
assert equality against the expected u32 constant (computed from version and the
flag bits). Reference the fields in_movie and in_preview and the TrackHeaderBox
serialization path so the test fails if flag bit positions change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/moov/trak/tkhd.rs`:
- Around line 198-199: Tests currently only round-trip the TrackHeaderBox; add a
direct assertion that the packed version+flags 32-bit word matches the expected
literal to catch bit-position regressions. In the unit test for TrackHeaderBox
(the case that sets in_movie: true and in_preview: false) call the serializer
used (e.g., TrackHeaderBox::to_bytes / write_box / serialize) and extract the
first 4 bytes (version+flags) or use the helper that builds the
version_and_flags word, then assert equality against the expected u32 constant
(computed from version and the flag bits). Reference the fields in_movie and
in_preview and the TrackHeaderBox serialization path so the test fails if flag
bit positions change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 790684be-dab9-4ba2-ac19-d75021888af0

📥 Commits

Reviewing files that changed from the base of the PR and between 3073b3e and 622ca7d.

📒 Files selected for processing (11)

• src/moov/mod.rs
• src/moov/trak/tkhd.rs
• src/test/av1.rs
• src/test/bbb.rs
• src/test/esds.rs
• src/test/flac.rs
• src/test/h264.rs
• src/test/hevc.rs
• src/test/libavif_anim.rs
• src/test/uncompressed.rs
• src/test/vp9.rs

[bradh]

LGTM.

A round-trip test would be nice, but I can try to find some time for that later.

[bradh]

Ran into this while working on the MUXL spec; I think having track_in_movie set is probably a sensible default. Now we can do that!

From Claude:

The tkhd box has three flag bits: track_enabled (bit 0), track_in_movie (bit 1), and track_in_preview (bit 2). Previously only track_enabled was exposed as a public field. The other two were decoded but discarded, and always written as false on encode.

Claude is wrong. There are four flags.

Add in_movie and in_preview fields to Tkhd so callers can read and write all three flags. Update all test expectations to match the actual flag values in their respective fixtures.

What do you need track_in_preview for, given the wording in ISO/IEC 14496-12:2022 Section 8.3.2.3? And why is this not being set the same as track_in_movie by default?

[iameli]

@bradh Right on, working on tweaks. You're right that track_in_preview seems to be kind of pointless. Would you prefer not exposing the field at all, automatically setting it to the same as track_in_movie, something else?

[bradh]

@bradh Right on, working on tweaks. You're right that track_in_preview seems to be kind of pointless. Would you prefer not exposing the field at all, automatically setting it to the same as track_in_movie, something else?

The spec says:

track_in_preview: Flag mask is 0x000004. This flag currently has no assigned meaning, and the
value should be ignored by readers. In the absence of further guidance (e.g. from derived
specifications), the same value as for track_in_movie should be written.

So on write, that bit position should match track_in_movie. Ignore it on read, so there is nothing to expose.

[iameli]

@bradh Done and rebased per your guidance. track_in_preview is ignored on read and written as a mirror of track_in_movie. Exposed the track_size_is_aspect_ratio field that the robot and I missed the first time around.

[coderabbitai]

🧹 Nitpick comments (1)

src/moov/trak/tkhd.rs (1)

24-24: ⚡ Quick win

Consider adding a doc comment for in_movie.

The size_is_aspect_ratio field has a helpful doc comment explaining its purpose and citing the spec. Adding a similar comment for in_movie would improve API documentation consistency and help users understand when to set this flag.

📝 Suggested documentation

     pub enabled: bool,
+    /// When set, the track is used in the movie presentation (ISO/IEC 14496-12:2022 §8.3.2.3).
     pub in_movie: bool,

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/moov/trak/tkhd.rs` at line 24, Add a doc comment for the in_movie field
(the pub in_movie: bool in the tkhd.rs struct) similar to the existing
size_is_aspect_ratio comment: describe what the flag means (e.g., when true the
track is used in the movie vs. only in other contexts), when callers should set
it, and, if applicable, cite the relevant spec section or behavior; update the
struct field comment above in_movie to match the style and detail of
size_is_aspect_ratio for consistent API docs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/moov/trak/tkhd.rs`:
- Line 24: Add a doc comment for the in_movie field (the pub in_movie: bool in
the tkhd.rs struct) similar to the existing size_is_aspect_ratio comment:
describe what the flag means (e.g., when true the track is used in the movie vs.
only in other contexts), when callers should set it, and, if applicable, cite
the relevant spec section or behavior; update the struct field comment above
in_movie to match the style and detail of size_is_aspect_ratio for consistent
API docs.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e6550a8f-2be0-48c0-be6a-5e21a293a3fb

📥 Commits

Reviewing files that changed from the base of the PR and between 622ca7d and 1540386.

📒 Files selected for processing (11)

• src/moov/mod.rs
• src/moov/trak/tkhd.rs
• src/test/av1.rs
• src/test/bbb.rs
• src/test/esds.rs
• src/test/flac.rs
• src/test/h264.rs
• src/test/hevc.rs
• src/test/libavif_anim.rs
• src/test/uncompressed.rs
• src/test/vp9.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• src/test/h264.rs
• src/test/bbb.rs

[bradh]

LGTM. Thanks for the work on this.