Struct vtc::Framerate

pub struct Framerate { /* private fields */ }

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

impl Framerate

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())

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())

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())

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.

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.

Trait Implementations

impl Clone for Framerate

fn clone(&self) -> Framerate

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Framerate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Framerate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<Framerate> for Framerate

fn eq(&self, other: &Framerate) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Framerate

impl Eq for Framerate

impl StructuralEq for Framerate

impl StructuralPartialEq for Framerate