Skip to main content

rff_core/
video.rs

1//! Video stream metadata that containers carry beside the bitstream: colour
2//! description, HDR mastering and light levels, pixel aspect, clean aperture
3//! and start timecode.
4//!
5//! These are *labels*, not conversions. A container that drops them still
6//! decodes, but the picture is shown with the wrong colours, the wrong shape
7//! or the wrong time, so every container that has a slot for one reads it and
8//! writes it back.
9
10/// Colour description as ITU-T H.273 (ISO/IEC 23091-2) code points: the values
11/// QuickTime `nclc`, ISO `nclx`, Matroska `Colour`, VP9 `vpcC` and the codecs'
12/// own VUI all use. `2` means unspecified in each field.
13///
14/// The range (limited / full) is [`ColorRange`](crate::ColorRange), which
15/// predates this type and sits beside it on the stream.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17pub struct ColorInfo {
18    /// `colour_primaries` (1 = BT.709, 9 = BT.2020, 12 = P3-D65, ...).
19    pub primaries: u16,
20    /// `transfer_characteristics` (1 = BT.709, 16 = PQ, 18 = HLG, ...).
21    pub transfer: u16,
22    /// `matrix_coefficients` (1 = BT.709, 9 = BT.2020 NCL, 0 = identity/RGB, ...).
23    pub matrix: u16,
24}
25
26impl ColorInfo {
27    /// The H.273 "unspecified" code point.
28    pub const UNSPECIFIED_CODE: u16 = 2;
29
30    /// All three fields unspecified.
31    pub const UNSPECIFIED: ColorInfo = ColorInfo {
32        primaries: 2,
33        transfer: 2,
34        matrix: 2,
35    };
36
37    /// True when no field carries information (all are 2), so a container
38    /// has nothing to write.
39    pub fn is_unspecified(&self) -> bool {
40        *self == ColorInfo::UNSPECIFIED
41    }
42}
43
44impl Default for ColorInfo {
45    fn default() -> ColorInfo {
46        ColorInfo::UNSPECIFIED
47    }
48}
49
50/// SMPTE ST 2086 mastering display colour volume, in the units MP4 `mdcv` and
51/// the HEVC/AV1 metadata store it: chromaticity coordinates in 0.00002
52/// steps, luminance in 0.0001 cd/m² steps.
53#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
54pub struct MasteringDisplay {
55    /// Red primary (x, y).
56    pub red: (u16, u16),
57    /// Green primary (x, y).
58    pub green: (u16, u16),
59    /// Blue primary (x, y).
60    pub blue: (u16, u16),
61    /// White point (x, y).
62    pub white_point: (u16, u16),
63    /// Maximum display luminance, 0.0001 cd/m² units.
64    pub max_luminance: u32,
65    /// Minimum display luminance, 0.0001 cd/m² units.
66    pub min_luminance: u32,
67}
68
69impl MasteringDisplay {
70    /// One chromaticity step, as a fraction.
71    pub const CHROMA_UNIT: f64 = 0.00002;
72    /// One luminance step, in cd/m².
73    pub const LUMA_UNIT: f64 = 0.0001;
74
75    /// The coordinate in [`CHROMA_UNIT`](Self::CHROMA_UNIT) steps for a
76    /// fractional chromaticity (Matroska stores floats), clamped to range.
77    pub fn chroma_from_f64(v: f64) -> u16 {
78        (v / Self::CHROMA_UNIT).round().clamp(0.0, u16::MAX as f64) as u16
79    }
80
81    /// The luminance in [`LUMA_UNIT`](Self::LUMA_UNIT) steps for cd/m².
82    pub fn luma_from_f64(v: f64) -> u32 {
83        (v / Self::LUMA_UNIT).round().clamp(0.0, u32::MAX as f64) as u32
84    }
85}
86
87/// CTA-861.3 content light level (MP4 `clli`, Matroska `MaxCLL`/`MaxFALL`),
88/// in cd/m². `0` means unknown in either field.
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
90pub struct ContentLightLevel {
91    /// Maximum content light level.
92    pub max_cll: u16,
93    /// Maximum frame-average light level.
94    pub max_fall: u16,
95}
96
97/// Clean aperture (MP4/QuickTime `clap`): the picture region meant for
98/// display, as exact rationals `(numerator, denominator)`. The offsets are of
99/// the aperture's centre from the picture's centre, so `(0, 1)` is centred.
100#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
101pub struct CleanAperture {
102    pub width: (u32, u32),
103    pub height: (u32, u32),
104    pub horiz_offset: (i32, u32),
105    pub vert_offset: (i32, u32),
106}
107
108/// A start timecode, as a QuickTime timecode track (`tmcd`) carries it: the
109/// frame number of the first frame, counted at the nominal rate.
110///
111/// The frame number is the source of truth; [`fmt::Display`](std::fmt::Display)
112/// renders it as `HH:MM:SS:FF`, with `;` before the frames when drop-frame.
113#[derive(Debug, Clone, PartialEq, Eq, Hash)]
114pub struct Timecode {
115    /// Frame number of the first frame.
116    pub start_frame: u32,
117    /// Nominal frames per second (30 for 29.97, 24 for 23.976).
118    pub frames_per_second: u8,
119    /// Drop-frame counting (29.97 / 59.94 NTSC).
120    pub drop_frame: bool,
121    /// The exact frame rate as `timescale / frame_duration` (30000/1001,
122    /// 25/1, ...). A timecode track stores both.
123    pub timescale: u32,
124    pub frame_duration: u32,
125    /// Other QuickTime `tmcd` flag bits (0x2 24-hour max, 0x4 negative times
126    /// OK, 0x8 counter); drop-frame is [`drop_frame`](Self::drop_frame).
127    pub flags: u32,
128    /// The source reel name (`tmcd`'s `name` box), when recorded.
129    pub reel_name: Option<String>,
130}
131
132impl Timecode {
133    /// A non-drop timecode at an integer rate starting at `start_frame`.
134    pub fn new(start_frame: u32, frames_per_second: u8) -> Timecode {
135        let fps = u32::from(frames_per_second.max(1));
136        Timecode {
137            start_frame,
138            frames_per_second: frames_per_second.max(1),
139            drop_frame: false,
140            timescale: fps,
141            frame_duration: 1,
142            flags: 0,
143            reel_name: None,
144        }
145    }
146
147    /// Parse `HH:MM:SS:FF` (or `HH:MM:SS;FF` for drop-frame) at the given
148    /// nominal rate. Drop-frame needs a rate that is a multiple of 30.
149    pub fn parse(text: &str, frames_per_second: u8) -> Option<Timecode> {
150        let drop = text.contains(';');
151        let parts: Vec<u32> = text
152            .split([':', ';', '.'])
153            .map(|p| p.trim().parse().ok())
154            .collect::<Option<Vec<u32>>>()?;
155        let [h, m, s, f] = parts[..] else { return None };
156        let fps = u32::from(frames_per_second.max(1));
157        if m > 59 || s > 59 || f >= fps || (drop && fps % 30 != 0) {
158            return None;
159        }
160        let mut frame = ((h * 60 + m) * 60 + s) * fps + f;
161        if drop {
162            let per_min = 2 * (fps / 30);
163            let minutes = h * 60 + m;
164            frame -= per_min * (minutes - minutes / 10);
165        }
166        let mut tc = Timecode::new(frame, frames_per_second);
167        tc.drop_frame = drop;
168        if drop {
169            tc.timescale = fps * 1000;
170            tc.frame_duration = 1001;
171        }
172        Some(tc)
173    }
174
175    /// `(hours, minutes, seconds, frames)` of [`start_frame`](Self::start_frame).
176    pub fn components(&self) -> (u32, u32, u32, u32) {
177        let fps = u64::from(self.frames_per_second.max(1));
178        let mut f = u64::from(self.start_frame);
179        if self.drop_frame && fps % 30 == 0 {
180            // SMPTE 12M: drop `d` frame numbers each minute except every tenth.
181            let d = 2 * (fps / 30);
182            let per_10min = fps * 600 - 9 * d;
183            let per_min = fps * 60 - d;
184            let tens = f / per_10min;
185            let rem = f % per_10min;
186            f += 9 * d * tens
187                + if rem > d {
188                    d * ((rem - d) / per_min)
189                } else {
190                    0
191                };
192        }
193        let frames = f % fps;
194        let secs = f / fps;
195        (
196            (secs / 3600 % 24) as u32,
197            (secs / 60 % 60) as u32,
198            (secs % 60) as u32,
199            frames as u32,
200        )
201    }
202}
203
204impl std::fmt::Display for Timecode {
205    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
206        let (h, m, s, fr) = self.components();
207        let sep = if self.drop_frame { ';' } else { ':' };
208        write!(f, "{h:02}:{m:02}:{s:02}{sep}{fr:02}")
209    }
210}
211
212#[cfg(test)]
213mod tests {
214    use super::*;
215
216    #[test]
217    fn non_drop_timecode_round_trips_through_text() {
218        let tc = Timecode::parse("01:00:00:00", 25).unwrap();
219        assert_eq!(tc.start_frame, 90_000);
220        assert_eq!(tc.to_string(), "01:00:00:00");
221        let tc = Timecode::parse("10:59:59:23", 24).unwrap();
222        assert_eq!(tc.to_string(), "10:59:59:23");
223    }
224
225    #[test]
226    fn drop_frame_skips_two_numbers_a_minute_except_every_tenth() {
227        // 00:01:00;02 is the first label after the skip at minute 1.
228        let tc = Timecode::parse("00:01:00;02", 30).unwrap();
229        assert_eq!(tc.start_frame, 1800);
230        assert_eq!(tc.to_string(), "00:01:00;02");
231        // Minute 10 keeps its ;00 and ;01.
232        let tc = Timecode::parse("00:10:00;00", 30).unwrap();
233        assert_eq!(tc.start_frame, 17_982);
234        assert_eq!(tc.to_string(), "00:10:00;00");
235        // One hour of 29.97 drop-frame is 107,892 frames.
236        assert_eq!(
237            Timecode::parse("01:00:00;00", 30).unwrap().start_frame,
238            107_892
239        );
240        for frame in [
241            0u32, 1799, 1800, 17_981, 17_982, 107_891, 107_892, 1_000_003,
242        ] {
243            let mut tc = Timecode::new(frame, 30);
244            tc.drop_frame = true;
245            let back = Timecode::parse(&tc.to_string(), 30).unwrap();
246            assert_eq!(back.start_frame, frame, "{tc}");
247        }
248    }
249
250    #[test]
251    fn invalid_timecodes_are_refused() {
252        assert!(Timecode::parse("00:00:00:25", 25).is_none());
253        assert!(Timecode::parse("00:60:00:00", 25).is_none());
254        assert!(Timecode::parse("00:00:00;00", 25).is_none());
255        assert!(Timecode::parse("00:00:00", 25).is_none());
256    }
257
258    #[test]
259    fn colour_defaults_to_unspecified() {
260        assert!(ColorInfo::default().is_unspecified());
261        assert_eq!(MasteringDisplay::chroma_from_f64(0.3127), 15_635);
262        assert_eq!(MasteringDisplay::luma_from_f64(1000.0), 10_000_000);
263    }
264}