pub struct Framerate { /* private fields */ }
Expand description
The rate at which a video file frames are played back.
Framerate is measured in frames-per-second (24/1 = 24 frames-per-second).
Implementations§
source§impl Framerate
impl Framerate
sourcepub fn playback(&self) -> Rational64
pub fn playback(&self) -> Rational64
The rational representation of the real-world playback speed as a fraction in frames-per-second.
Examples
use vtc::{Framerate, Ntsc};
use num::Rational64;
let rate = Framerate::with_timebase("24/1", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback())
sourcepub fn timebase(&self) -> Rational64
pub fn timebase(&self) -> Rational64
The rational representation of the timecode timebase speed as a fraction in frames-per-second.
Examples
use vtc::{Framerate, Ntsc};
use num::Rational64;
let rate = Framerate::with_playback("24000/1001", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24, 1), rate.timebase())
sourcepub fn ntsc(&self) -> Ntsc
pub fn ntsc(&self) -> Ntsc
Whether this is an NTSC-style time base (aka 23.98, 24000/1001, etc). Returns an enum detailing if it is not NTSC or what type of NTSC flavor it is.
Examples
use vtc::{Framerate, Ntsc};
let rate = Framerate::with_playback("24000/1001", Ntsc::NonDropFrame).unwrap();
assert_eq!(Ntsc::NonDropFrame, rate.ntsc())
sourcepub fn with_playback<T: FramerateSource>(
rate: T,
ntsc: Ntsc
) -> FramerateParseResult
pub fn with_playback<T: FramerateSource>( rate: T, ntsc: Ntsc ) -> FramerateParseResult
Creates a new Framerate with a given real-world media playback value measured in frames-per-second.
Arguments
-
rate
- A value that represents playback frames-per-second. -
ntsc
- The ntsc standard this value should be parsed as.
Examples
We can generate any NTSC framerates from f32 or f64 values easily.
use vtc::{Framerate, FramerateSource, Ntsc};
use num::Rational64;
let rate = Framerate::with_playback(23.98, Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
Floats are automatically rounded to the nearest valid NTSC playback speed:
let rate = Framerate::with_playback(23.5, Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
&str and String can be parsed if they are a float or rational format:
let rate = Framerate::with_playback("23.98", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
let rate = Framerate::with_playback("24000/1001", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
Non-valid NTSC playback rates will result in an error if we are parsing NTSC drop or non-drop values:
let err = Framerate::with_playback("24/1", Ntsc::NonDropFrame);
assert_eq!(FramerateParseError::Ntsc("ntsc framerates must be n/1001".to_string()), err.err().unwrap());
This means that integers will always result in an error if ntsc != Ntsc::None:
let err = Framerate::with_playback(24, Ntsc::NonDropFrame);
assert!(err.is_err());
If we switch our NTSC settings to Ntsc::None, we can parse integers and integer strings, as well as other arbirary playback speed values:
let rate = Framerate::with_playback(24, Ntsc::None).unwrap();
assert_eq!(Rational64::new(24, 1), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::None, rate.ntsc());
let rate = Framerate::with_playback("24", Ntsc::None).unwrap();
assert_eq!(Rational64::new(24, 1), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::None, rate.ntsc());
let rate = Framerate::with_playback("3/1", Ntsc::None).unwrap();
assert_eq!(Rational64::new(3, 1), rate.playback());
assert_eq!(Rational64::new(3, 1), rate.timebase());
assert_eq!(Ntsc::None, rate.ntsc());
If we try to parse a non-drop-frame NTSC value with the wrong timbebase we will get an error:
let err = Framerate::with_playback(23.98, Ntsc::DropFrame);
assert_eq!(FramerateParseError::DropFrame("dropframe must have playback divisible by 30000/1001 (multiple of 29.97)".to_string()), err.err().unwrap());
For more information on why drop-frame timebases must be a multiple of 30000/1001, see this blogpost.
note
Using a float with Ntsc::None will result in an error. Floats are not precise, and without the ntsc flag, vtc cannot know exactly what framerate you want. A Rational64 value must be used.
sourcepub fn with_timebase<T: FramerateSource>(
base: T,
ntsc: Ntsc
) -> FramerateParseResult
pub fn with_timebase<T: FramerateSource>( base: T, ntsc: Ntsc ) -> FramerateParseResult
Creates a new Framerate with a given timecode timebase playback value measured in frames-per-second. For NTSC framerates, the timebase will differ from the playback.
Arguments
-
base
- A value that represents timebase frames-per-second. -
ntsc
- The ntsc standard this value should be parsed as.
Examples
We can generate any NTSC framerates from any non 128-bit integer type easily:
use vtc::{Framerate, FramerateSource, Ntsc};
use num::Rational64;
let rate = Framerate::with_timebase(24, Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
Floats are automatically rounded to the nearest valid NTSC timebase speed:
let rate = Framerate::with_timebase(24.0, Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
&str and String can be parsed if they are an int, float or rational format:
let rate = Framerate::with_timebase("24", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
let rate = Framerate::with_timebase("24.0", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
let rate = Framerate::with_timebase("24/1", Ntsc::NonDropFrame).unwrap();
assert_eq!(Rational64::new(24000, 1001), rate.playback());
assert_eq!(Rational64::new(24, 1), rate.timebase());
assert_eq!(Ntsc::NonDropFrame, rate.ntsc());
Non-valid NTSC timebase will result in an error if we are parsing NTSC drop or non-drop values:
let err = Framerate::with_timebase("24000/1001", Ntsc::NonDropFrame);
assert_eq!(
FramerateParseError::Ntsc("ntsc timebases must be whole numbers".to_string()),
err.err().unwrap(),
);
If we switch our NTSC settings, we can parse arbirary Framerate values:
let rate = Framerate::with_timebase("3/1", Ntsc::None).unwrap();
assert_eq!(Rational64::new(3, 1), rate.playback());
assert_eq!(Rational64::new(3, 1), rate.timebase());
assert_eq!(Ntsc::None, rate.ntsc());
If we try to parse a drop-frame value with the wrong timbebase we will get an error:
let err = Framerate::with_timebase("24", Ntsc::DropFrame);
assert_eq!(
FramerateParseError::DropFrame("dropframe must have timebase divisible by 30 (multiple of 29.97)".to_string()),
err.err().unwrap(),
);
For more information on why drop-frame timebases must be a multiple of 30, see this blogpost.