Skip to main content

smpte_timecode/timecode/
rate.rs

1use super::{Ratio, TimecodeError};
2
3/// A timecode frame rate: a nominal frame count, whether frames run 1000/1001 slower (the NTSC
4/// family), and whether labels use drop-frame counting.
5///
6/// Only the 19 combinations in [`FrameRate::ALL`] exist. Drop-frame counting needs a nominal rate
7/// of 30, 60 or 120 and skips 2, 4 or 8 labels at the start of every minute not divisible by ten.
8/// 29.97 DF and 59.94 DF follow SMPTE ST 12-1. 30 DF, 60 DF, 120 DF and 119.88 DF follow the same
9/// rule as Pro Tools labels them.
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
11pub struct FrameRate {
12    nominal: u8,
13    ntsc: bool,
14    drop_frame: bool,
15}
16
17impl FrameRate {
18    /// 24000/1001 frames per second, counted as 24.
19    pub const FPS_23_976: Self = Self::known(24, true, false);
20    /// 24 frames per second.
21    pub const FPS_24: Self = Self::known(24, false, false);
22    /// 25 frames per second.
23    pub const FPS_25: Self = Self::known(25, false, false);
24    /// 30000/1001 frames per second, counted as 30 without dropping labels.
25    pub const FPS_29_97: Self = Self::known(30, true, false);
26    /// 30000/1001 frames per second with drop-frame labels.
27    pub const FPS_29_97_DF: Self = Self::known(30, true, true);
28    /// 30 frames per second.
29    pub const FPS_30: Self = Self::known(30, false, false);
30    /// 30 frames per second with drop-frame labels.
31    pub const FPS_30_DF: Self = Self::known(30, false, true);
32    /// 48000/1001 frames per second, counted as 48.
33    pub const FPS_47_952: Self = Self::known(48, true, false);
34    /// 48 frames per second.
35    pub const FPS_48: Self = Self::known(48, false, false);
36    /// 50 frames per second.
37    pub const FPS_50: Self = Self::known(50, false, false);
38    /// 60000/1001 frames per second, counted as 60 without dropping labels.
39    pub const FPS_59_94: Self = Self::known(60, true, false);
40    /// 60000/1001 frames per second with drop-frame labels.
41    pub const FPS_59_94_DF: Self = Self::known(60, true, true);
42    /// 60 frames per second.
43    pub const FPS_60: Self = Self::known(60, false, false);
44    /// 60 frames per second with drop-frame labels.
45    pub const FPS_60_DF: Self = Self::known(60, false, true);
46    /// 100 frames per second.
47    pub const FPS_100: Self = Self::known(100, false, false);
48    /// 120000/1001 frames per second, counted as 120 without dropping labels.
49    pub const FPS_119_88: Self = Self::known(120, true, false);
50    /// 120000/1001 frames per second with drop-frame labels.
51    pub const FPS_119_88_DF: Self = Self::known(120, true, true);
52    /// 120 frames per second.
53    pub const FPS_120: Self = Self::known(120, false, false);
54    /// 120 frames per second with drop-frame labels.
55    pub const FPS_120_DF: Self = Self::known(120, false, true);
56
57    /// Every supported frame rate.
58    pub const ALL: [Self; 19] = [
59        Self::FPS_23_976,
60        Self::FPS_24,
61        Self::FPS_25,
62        Self::FPS_29_97,
63        Self::FPS_29_97_DF,
64        Self::FPS_30,
65        Self::FPS_30_DF,
66        Self::FPS_47_952,
67        Self::FPS_48,
68        Self::FPS_50,
69        Self::FPS_59_94,
70        Self::FPS_59_94_DF,
71        Self::FPS_60,
72        Self::FPS_60_DF,
73        Self::FPS_100,
74        Self::FPS_119_88,
75        Self::FPS_119_88_DF,
76        Self::FPS_120,
77        Self::FPS_120_DF,
78    ];
79
80    /// Looks up the rate with `nominal` labels per second, running 1000/1001 slower when `ntsc`
81    /// is set, and counting drop-frame labels when `drop_frame` is set.
82    ///
83    /// # Errors
84    ///
85    /// [`TimecodeError::UnsupportedFrameRate`] when the combination is not in [`FrameRate::ALL`],
86    /// such as 25 DF or 50 with the 1000/1001 factor.
87    pub const fn new(nominal: u8, ntsc: bool, drop_frame: bool) -> Result<Self, TimecodeError> {
88        let mut index = 0;
89        while index < Self::ALL.len() {
90            let rate = Self::ALL[index];
91            if rate.nominal == nominal && rate.ntsc == ntsc && rate.drop_frame == drop_frame {
92                return Ok(rate);
93            }
94            index += 1;
95        }
96        Err(TimecodeError::UnsupportedFrameRate)
97    }
98
99    /// The number of frame labels in one timecode second.
100    pub const fn nominal(self) -> u8 {
101        self.nominal
102    }
103
104    /// Whether frames run at 1000/1001 of the nominal rate, as 23.976 and 29.97 do.
105    pub const fn is_ntsc(self) -> bool {
106        self.ntsc
107    }
108
109    /// Whether labels use drop-frame counting.
110    pub const fn is_drop_frame(self) -> bool {
111        self.drop_frame
112    }
113
114    /// The exact number of frames per real-time second.
115    pub const fn frames_per_second(self) -> Ratio {
116        if self.ntsc {
117            Ratio::reduced(self.nominal as u64 * 1000, 1001)
118        } else {
119            Ratio::from_integer(self.nominal as u64)
120        }
121    }
122
123    /// The number of frames from `00:00:00:00` up to, but not including, the next midnight.
124    pub const fn frames_per_day(self) -> u32 {
125        self.frames_per_ten_minutes() * 6 * 24
126    }
127
128    /// Labels skipped at the start of each minute not divisible by ten. Zero without drop-frame.
129    pub(crate) const fn dropped_per_minute(self) -> u32 {
130        if self.drop_frame {
131            self.nominal as u32 / 15
132        } else {
133            0
134        }
135    }
136
137    pub(crate) const fn frames_per_minute(self) -> u32 {
138        self.nominal as u32 * 60 - self.dropped_per_minute()
139    }
140
141    pub(crate) const fn frames_per_ten_minutes(self) -> u32 {
142        // The first minute of every ten keeps all of its labels.
143        self.nominal as u32 * 600 - self.dropped_per_minute() * 9
144    }
145
146    const fn known(nominal: u8, ntsc: bool, drop_frame: bool) -> Self {
147        Self {
148            nominal,
149            ntsc,
150            drop_frame,
151        }
152    }
153}