Struct vtc::Framerate

pub struct Framerate { /* fields omitted */ }

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: &Framerate) -> bool

This method tests for !=.

impl Copy for Framerate

impl Eq for Framerate

impl StructuralEq for Framerate

impl StructuralPartialEq for Framerate