Skip to main content

smpte_timecode/timecode/
pull.rs

1use super::Ratio;
2
3/// An exact pull-up or pull-down factor for a frame rate or a sample rate.
4///
5/// Pulling a rate multiplies it by the factor. 0.1% pulls move between film and NTSC speeds and
6/// 4% pulls between 24 and 25 frames per second. A pulled rate is usually not a whole number:
7/// 48 kHz pulled down 0.1% is 48 000 000/1001 ≈ 47 952.05 Hz, which equipment labels 47.952 kHz.
8///
9/// ```
10/// use smpte_timecode::{FrameRate, Pull, Ratio};
11///
12/// let pulled = Pull::DOWN_0_1_PERCENT.apply(Ratio::from_integer(48_000)).unwrap();
13/// assert_eq!((pulled.numer(), pulled.denom()), (48_000_000, 1001));
14///
15/// let film_to_pal = Pull::UP_4_PERCENT.apply(FrameRate::FPS_24.frames_per_second()).unwrap();
16/// assert_eq!(film_to_pal, FrameRate::FPS_25.frames_per_second());
17/// ```
18#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
19pub struct Pull(Ratio);
20
21impl Pull {
22    /// No change.
23    pub const NONE: Self = Self(Ratio::from_integer(1));
24    /// 1001/1000, from NTSC speed up to film speed.
25    pub const UP_0_1_PERCENT: Self = Self(Ratio::reduced(1001, 1000));
26    /// 1000/1001, from film speed down to NTSC speed.
27    pub const DOWN_0_1_PERCENT: Self = Self(Ratio::reduced(1000, 1001));
28    /// 25/24, from 24 up to 25 frames per second. The exact change is +4.1667%.
29    pub const UP_4_PERCENT: Self = Self(Ratio::reduced(25, 24));
30    /// 24/25, from 25 down to 24 frames per second.
31    pub const DOWN_4_PERCENT: Self = Self(Ratio::reduced(24, 25));
32
33    /// The exact factor the pull multiplies a rate by.
34    pub const fn factor(self) -> Ratio {
35        self.0
36    }
37
38    /// The pull that applies `self` and then `next`, or `None` if the combined factor does not fit
39    /// in a [`Ratio`].
40    pub const fn then(self, next: Self) -> Option<Self> {
41        match self.0.checked_mul(next.0) {
42            Some(factor) => Some(Self(factor)),
43            None => None,
44        }
45    }
46
47    /// Pulls `rate`, or returns `None` if the result does not fit in a [`Ratio`].
48    pub const fn apply(self, rate: Ratio) -> Option<Ratio> {
49        rate.checked_mul(self.0)
50    }
51}