Parse colr box CICP data for video tracks

Add parsing of the ISO BMFF `colr` box (ISO 14496-12:2020 §12.1.5) in
`read_video_sample_entry`, storing the result in a new `colour_info` field
on `VideoSampleEntry`. Expose the nclx CICP values through the C API via
four new fields on `Mp4parseTrackVideoSampleInfo`: `has_colour_info`,
`colour_primaries`, `transfer_characteristics`, `matrix_coefficients`, and
`full_range_flag`.

This enables Firefox's MP4 demuxer to set `mVideoInfo.mTransferFunction`
for fMP4 content (Netflix, Prime Video, DRM), fixing HDR10/HLG video
appearing near-black on Windows HDR displays.

- `read_video_sample_entry` now takes `strictness` (consistent with
  `read_audio_sample_entry`) and passes it to `read_colr`.
- Duplicate `colr` boxes in a sample entry violate ISO 14496-12:2020
  §12.1.5; we warn and keep the first rather than failing playback.
- `has_colour_info: bool` is the canonical "present" flag; avoids
  misinterpreting MC=0 (Identity/GBR) as "absent".
- `NclxColourInformation` fields made public for Rust callers.
- Seven integration tests added. Test MP4 files were generated with ffmpeg
  using `-movflags +write_colr` and `-x264-params colorprim/transfer/colormatrix`:
  HDR10 (cp=9,tc=16,mc=9), HLG (tc=18), HDR10 full-range, HLG full-range,
  RGB/Identity (mc=0, exercises has_colour_info), and no-colr variants.

Author: alastor0325

mp4parse/src/lib.rs

@@ -1175,6 +1175,7 @@ pub struct VideoSampleEntry {
     pub codec_specific: VideoCodecSpecific,
     pub protection_info: TryVec<ProtectionSchemeInfoBox>,
     pub pixel_aspect_ratio: Option<f32>,
+    pub colour_info: Option<ColourInformation>,
 }
 
 /// Represent a Video Partition Codec Configuration 'vpcC' box (aka vp9). The meaning of each
@@ -3722,10 +3723,10 @@ fn read_pixi<T: Read>(src: &mut BMFFBox<T>) -> Result<PixelInformation> {
 #[repr(C)]
 #[derive(Debug)]
 pub struct NclxColourInformation {
-    colour_primaries: u8,
-    transfer_characteristics: u8,
-    matrix_coefficients: u8,
-    full_range_flag: bool,
+    pub colour_primaries: u8,
+    pub transfer_characteristics: u8,
+    pub matrix_coefficients: u8,
+    pub full_range_flag: bool,
 }
 
 /// The raw bytes of the ICC profile
@@ -5533,7 +5534,10 @@ fn read_hdlr<T: Read>(src: &mut BMFFBox<T>, strictness: ParseStrictness) -> Resu
 }
 
 /// Parse an video description inside an stsd box.
-fn read_video_sample_entry<T: Read>(src: &mut BMFFBox<T>) -> Result<SampleEntry> {
+fn read_video_sample_entry<T: Read>(
+    src: &mut BMFFBox<T>,
+    strictness: ParseStrictness,
+) -> Result<SampleEntry> {
     let name = src.get_header().name;
     let codec_type = match name {
         BoxType::AVCSampleEntry | BoxType::AVC3SampleEntry => CodecType::H264,
@@ -5567,6 +5571,7 @@ fn read_video_sample_entry<T: Read>(src: &mut BMFFBox<T>) -> Result<SampleEntry>
     // Skip clap/pasp/etc. for now.
     let mut codec_specific = None;
     let mut pixel_aspect_ratio = None;
+    let mut colour_info = None;
     let mut protection_info = TryVec::new();
     let mut iter = src.box_iter();
     while let Some(mut b) = iter.next_box()? {
@@ -5683,6 +5688,19 @@ fn read_video_sample_entry<T: Read>(src: &mut BMFFBox<T>) -> Result<SampleEntry>
                 }
                 debug!("Parsed pasp box: {pasp:?}, PAR {pixel_aspect_ratio:?}");
             }
+            BoxType::ColourInformationBox => {
+                if colour_info.is_some() {
+                    // ISO 14496-12:2020 §12.1.5 requires at most one ColourInformationBox
+                    // per sample entry. Duplicates are a spec violation, but we tolerate
+                    // them to avoid breaking playback of malformed content.
+                    warn!("Multiple colr boxes in video sample entry, keeping first");
+                    skip_box_content(&mut b)?;
+                } else {
+                    let colr = read_colr(&mut b, strictness)?;
+                    debug!("Parsed colr box: {colr:?}");
+                    colour_info = Some(colr);
+                }
+            }
             _ => {
                 debug!("Unsupported video codec, box {:?} found", b.head.name);
                 skip_box_content(&mut b)?;
@@ -5701,6 +5719,7 @@ fn read_video_sample_entry<T: Read>(src: &mut BMFFBox<T>) -> Result<SampleEntry>
                 codec_specific,
                 protection_info,
                 pixel_aspect_ratio,
+                colour_info,
             })
         }),
     )
@@ -5908,9 +5927,9 @@ fn read_stsd<T: Read>(
     while descriptions.len() < description_count {
         if let Some(mut b) = iter.next_box()? {
             let description = match track.track_type {
-                TrackType::Video => read_video_sample_entry(&mut b),
-                TrackType::Picture => read_video_sample_entry(&mut b),
-                TrackType::AuxiliaryVideo => read_video_sample_entry(&mut b),
+                TrackType::Video => read_video_sample_entry(&mut b, strictness),
+                TrackType::Picture => read_video_sample_entry(&mut b, strictness),
+                TrackType::AuxiliaryVideo => read_video_sample_entry(&mut b, strictness),
                 TrackType::Audio => read_audio_sample_entry(&mut b, strictness),
                 TrackType::Metadata => Err(Error::Unsupported("metadata track")),
                 TrackType::Unknown => Err(Error::Unsupported("unknown track type")),

mp4parse/src/tests.rs

@@ -1145,7 +1145,8 @@ fn read_stsd_mp4v() {
     let mut iter = super::BoxIter::new(&mut stream);
     let mut stream = iter.next_box().unwrap().unwrap();
 
-    let sample_entry = super::read_video_sample_entry(&mut stream).unwrap();
+    let sample_entry =
+        super::read_video_sample_entry(&mut stream, super::ParseStrictness::Normal).unwrap();
 
     match sample_entry {
         super::SampleEntry::Video(v) => {
@@ -1245,7 +1246,7 @@ fn unknown_video_sample_entry() {
     });
     let mut iter = super::BoxIter::new(&mut stream);
     let mut stream = iter.next_box().unwrap().unwrap();
-    match super::read_video_sample_entry(&mut stream) {
+    match super::read_video_sample_entry(&mut stream, super::ParseStrictness::Normal) {
         Ok(super::SampleEntry::Unknown) => (),
         _ => panic!("expected a different error result"),
     }

mp4parse_capi/src/lib.rs

@@ -264,6 +264,18 @@ pub struct Mp4parseTrackVideoSampleInfo {
     pub image_height: u16,
     pub extra_data: Mp4parseByteData,
     pub protected_data: Mp4parseSinfInfo,
+    /// True when a `colr` box with `colour_type = 'nclx'` was present. When false,
+    /// the CICP fields below are all zero and must not be interpreted.
+    pub has_colour_info: bool,
+    /// CICP colour primaries (ISO 23091-2 § 8.1). Valid only when `has_colour_info`.
+    pub colour_primaries: u8,
+    /// CICP transfer characteristics (ISO 23091-2 § 8.2). Valid only when `has_colour_info`.
+    pub transfer_characteristics: u8,
+    /// CICP matrix coefficients (ISO 23091-2 § 8.3). Valid only when `has_colour_info`.
+    /// Note: value 0 is a valid CICP value (Identity/GBR), not an absence indicator.
+    pub matrix_coefficients: u8,
+    /// Full range flag from the colr nclx box. Valid only when `has_colour_info`.
+    pub full_range_flag: bool,
 }
 
 #[repr(C)]
@@ -1120,6 +1132,14 @@ fn mp4parse_get_track_video_info_safe(
                 };
             }
         }
+        if let Some(mp4parse::ColourInformation::Nclx(ref nclx)) = video.colour_info {
+            sample_info.has_colour_info = true;
+            sample_info.colour_primaries = nclx.colour_primaries;
+            sample_info.transfer_characteristics = nclx.transfer_characteristics;
+            sample_info.matrix_coefficients = nclx.matrix_coefficients;
+            sample_info.full_range_flag = nclx.full_range_flag;
+        }
+
         video_sample_infos.push(sample_info)?;
     }
 

mp4parse_capi/tests/test_colour_info.rs

@@ -0,0 +1,158 @@
+use mp4parse_capi::*;
+use std::io::Read;
+
+extern "C" fn buf_read(buf: *mut u8, size: usize, userdata: *mut std::os::raw::c_void) -> isize {
+    let input: &mut std::fs::File = unsafe { &mut *(userdata as *mut _) };
+    let buf = unsafe { std::slice::from_raw_parts_mut(buf, size) };
+    match input.read(buf) {
+        Ok(n) => n as isize,
+        Err(_) => -1,
+    }
+}
+
+unsafe fn open_parser(path: &str) -> *mut Mp4parseParser {
+    let mut file = std::fs::File::open(path).expect("file not found");
+    let io = Mp4parseIo {
+        read: Some(buf_read),
+        userdata: &mut file as *mut _ as *mut std::os::raw::c_void,
+    };
+    let mut parser = std::ptr::null_mut();
+    let rv = mp4parse_new(&io, &mut parser);
+    assert_eq!(rv, Mp4parseStatus::Ok);
+    assert!(!parser.is_null());
+    parser
+}
+
+/// HDR10 (PQ): colour_primaries=9, transfer=16, matrix=9, full_range=false
+#[test]
+fn video_colr_nclx_hdr10() {
+    unsafe {
+        let parser = open_parser("tests/video_colr_nclx_hdr10.mp4");
+
+        let mut video = Mp4parseTrackVideoInfo::default();
+        let rv = mp4parse_get_track_video_info(parser, 0, &mut video);
+        assert_eq!(rv, Mp4parseStatus::Ok);
+
+        assert_eq!(video.sample_info_count, 1);
+        let sample = &*video.sample_info;
+        assert!(sample.has_colour_info);
+        assert_eq!(sample.colour_primaries, 9);
+        assert_eq!(sample.transfer_characteristics, 16);
+        assert_eq!(sample.matrix_coefficients, 9);
+        assert!(!sample.full_range_flag);
+
+        mp4parse_free(parser);
+    }
+}
+
+/// HDR10 full-range: colour_primaries=9, transfer=16, matrix=9, full_range=true
+#[test]
+fn video_colr_nclx_hdr10_full_range() {
+    unsafe {
+        let parser = open_parser("tests/video_colr_nclx_hdr10_full_range.mp4");
+
+        let mut video = Mp4parseTrackVideoInfo::default();
+        let rv = mp4parse_get_track_video_info(parser, 0, &mut video);
+        assert_eq!(rv, Mp4parseStatus::Ok);
+
+        assert_eq!(video.sample_info_count, 1);
+        let sample = &*video.sample_info;
+        assert!(sample.has_colour_info);
+        assert_eq!(sample.colour_primaries, 9);
+        assert_eq!(sample.transfer_characteristics, 16);
+        assert_eq!(sample.matrix_coefficients, 9);
+        assert!(sample.full_range_flag);
+
+        mp4parse_free(parser);
+    }
+}
+
+/// HLG: colour_primaries=9, transfer=18, matrix=9, full_range=false
+#[test]
+fn video_colr_nclx_hlg() {
+    unsafe {
+        let parser = open_parser("tests/video_colr_nclx_hlg.mp4");
+
+        let mut video = Mp4parseTrackVideoInfo::default();
+        let rv = mp4parse_get_track_video_info(parser, 0, &mut video);
+        assert_eq!(rv, Mp4parseStatus::Ok);
+
+        assert_eq!(video.sample_info_count, 1);
+        let sample = &*video.sample_info;
+        assert!(sample.has_colour_info);
+        assert_eq!(sample.colour_primaries, 9);
+        assert_eq!(sample.transfer_characteristics, 18);
+        assert_eq!(sample.matrix_coefficients, 9);
+        assert!(!sample.full_range_flag);
+
+        mp4parse_free(parser);
+    }
+}
+
+/// HLG full-range: colour_primaries=9, transfer=18, matrix=9, full_range=true
+#[test]
+fn video_colr_nclx_hlg_full_range() {
+    unsafe {
+        let parser = open_parser("tests/video_colr_nclx_hlg_full_range.mp4");
+
+        let mut video = Mp4parseTrackVideoInfo::default();
+        let rv = mp4parse_get_track_video_info(parser, 0, &mut video);
+        assert_eq!(rv, Mp4parseStatus::Ok);
+
+        assert_eq!(video.sample_info_count, 1);
+        let sample = &*video.sample_info;
+        assert!(sample.has_colour_info);
+        assert_eq!(sample.colour_primaries, 9);
+        assert_eq!(sample.transfer_characteristics, 18);
+        assert_eq!(sample.matrix_coefficients, 9);
+        assert!(sample.full_range_flag);
+
+        mp4parse_free(parser);
+    }
+}
+
+/// RGB (Identity matrix, MC=0): has_colour_info=true but matrix_coefficients=0.
+/// Validates that has_colour_info correctly distinguishes "colr box present with MC=0"
+/// from "no colr box" (where matrix_coefficients is also 0).
+#[test]
+fn video_colr_nclx_rgb_identity_matrix() {
+    unsafe {
+        let parser = open_parser("tests/video_colr_nclx_rgb.mp4");
+
+        let mut video = Mp4parseTrackVideoInfo::default();
+        let rv = mp4parse_get_track_video_info(parser, 0, &mut video);
+        assert_eq!(rv, Mp4parseStatus::Ok);
+
+        assert_eq!(video.sample_info_count, 1);
+        let sample = &*video.sample_info;
+        assert!(sample.has_colour_info);
+        assert_eq!(sample.colour_primaries, 1);
+        assert_eq!(sample.transfer_characteristics, 1);
+        assert_eq!(sample.matrix_coefficients, 0); // Identity/GBR — valid CICP value, not "absent"
+        assert!(!sample.full_range_flag);
+
+        mp4parse_free(parser);
+    }
+}
+
+/// No colr box: has_colour_info=false, CICP fields are zero
+#[test]
+fn video_no_colr_box() {
+    unsafe {
+        let parser = open_parser("tests/white.mp4");
+
+        let mut video = Mp4parseTrackVideoInfo::default();
+        let rv = mp4parse_get_track_video_info(parser, 0, &mut video);
+        assert_eq!(rv, Mp4parseStatus::Ok);
+
+        assert_eq!(video.sample_info_count, 1);
+        let sample = &*video.sample_info;
+        assert!(!sample.has_colour_info);
+        assert_eq!(sample.colour_primaries, 0);
+        assert_eq!(sample.transfer_characteristics, 0);
+        assert_eq!(sample.matrix_coefficients, 0);
+        assert!(!sample.full_range_flag);
+
+        mp4parse_free(parser);
+    }
+}