Struct vtc::Timecode

pub struct Timecode { /* fields omitted */ }

Timecode represents the frame at a particular time in a video.

New Timecode values are created with the Timecode::with_seconds, Timecode::with_frames, and Timecode::with_premiere_ticks methods.

Timecode is a Copy value.

Examples

For timecode attribute examples, see the individual methods of the Timecode type, such as Timecode::timecode. For examples of how to construct a new timecode, see the examples on the contructor methods like Timecode::with_frames.

There are a number of opeations we can apply to Timecode values.

Compare Timecodes

use vtc::{Timecode, rates};
let tc1 = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
let tc2 = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
let tc3 = Timecode::with_frames("00:30:00:00", rates::F23_98).unwrap();
let tc4 = Timecode::with_frames("01:30:00:00", rates::F23_98).unwrap();

assert!(tc1 == tc2);
assert!(tc1 > tc3);
assert!(tc1 < tc4);

Sort_Timecodes

let tc1 = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
let tc2 = Timecode::with_frames("01:30:00:00", rates::F23_98).unwrap();
let tc3 = Timecode::with_frames("00:30:00:00", rates::F23_98).unwrap();

let mut timecodes = vec![tc1, tc2, tc3];

timecodes.sort();

assert_eq!(timecodes[0], tc3);
assert_eq!(timecodes[1], tc1);
assert_eq!(timecodes[2], tc2);

Add Timecodes

let tc1 = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
let tc2 = Timecode::with_frames("00:30:00:00", rates::F23_98).unwrap();

let mut result = tc1 + tc2;

assert_eq!("01:30:00:00", result.timecode());

result += tc1;

assert_eq!("02:30:00:00", result.timecode());

Subtract Timecodes

let tc1 = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
let tc2 = Timecode::with_frames("00:30:00:00", rates::F23_98).unwrap();

let mut result = tc1 - tc2;

assert_eq!("00:30:00:00", result.timecode());

result -= tc1;

assert_eq!("-00:30:00:00", result.timecode());

Multiply Timecodes

let tc1 = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();

let mut result = tc1 * 1.5;

assert_eq!("01:30:00:00", result.timecode());

result *= 2;

assert_eq!("03:00:00:00", result.timecode());

Divide Timecodes

Dividing always acts as if floor devision had been done on the frame count of the Timecode.

let tc1 = Timecode::with_frames("01:00:00:01", rates::F23_98).unwrap();

let result = tc1 / 1.5;

assert_eq!("00:40:00:00", result.timecode());

This allows divisions and remainders to give correct, complementary values:

let result = tc1 % 1.5;

assert_eq!("00:00:00:01", result.timecode());

DivAssign and RemAssign are also implemented for Timecode:

let mut tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();

tc /= 2;

assert_eq!("00:30:00:00", tc.timecode());

tc %= 1.65;
assert_eq!("00:00:00:01", tc.timecode())

Implementations

impl Timecode

pub fn rate(&self) -> Framerate

Returns the Framerate of the timecode.

Examples

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!(rates::F23_98, tc.rate())

pub fn seconds(&self) -> Rational64

Returns the rational representation of the real-world seconds that would have elapsed between 00:00:00:00 and this timecode.

What it is

The number of real-world seconds that have elapsed between 00:00:00:00 and the timecode value. With NTSC timecode, the timecode drifts from the real-world elapsed time.

Where you see it

• Anywhere real-world time needs to be calculated.
• In code that needs to do lossless calculations of playback time and not rely on frame count, like adding two timecodes together with different framerates.

Examples

use num::Rational64;
let tc = Timecode::with_seconds(3600.0, rates::F24).unwrap();
assert_eq!(Rational64::new(3600, 1), tc.seconds())

pub fn sections(&self) -> TimecodeSections

The individual sections of a timecode string as i64 values.

Examples

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
let expected = TimecodeSections{
    negative: false,
    hours: 1,
    minutes: 0,
    seconds: 0,
    frames: 0,
};
assert_eq!(expected, tc.sections())

pub fn timecode(&self) -> String

Returns the the formatted SMPTE timecode: (ex: 01:00:00:00).

What it is

Timecode is used as a human-readable way to represent the id of a given frame. It is formatted to give a rough sense of where to find a frame: {HOURS}:{MINUTES}:{SECONDS}:{FRAME}. For more on timecode, see Frame.io’s excellent post on the subject.

Where you see it

Timecode is ubiquitous in video editing, a small sample of places you might see timecode:

• Source and Playback monitors in your favorite NLE.
• Burned into the footage for dailies.
• Cut lists like an EDL.

Examples

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

pub fn frames(&self) -> i64

Returns the number of frames that would have elapsed between 00:00:00:00 and this timecode.

What it is

Frame number / frames count is the number of a frame if the timecode started at 00:00:00:00 and had been running until the current value. A timecode of ‘00:00:00:10’ has a frame number of 10. A timecode of ‘01:00:00:00’ has a frame number of 86400.

Where you see it

• Frame-sequence files: ‘my_vfx_shot.0086400.exr’

• FCP7XML cut lists:

  <timecode>
      <rate>
          <timebase>24</timebase>
          <ntsc>TRUE</ntsc>
      </rate>
      <string>01:00:00:00</string>
      <frame>86400</frame>  <!-- <====THIS LINE-->
      <displayformat>NDF</displayformat>
  </timecode>
  

Examples

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!(86400, tc.frames())

pub fn runtime(&self, precision: usize) -> String

Returns the true, real-world runtime of the timecode in HH:MM:SS.FFFFFFFFF format.

Arguments

• precision - How many places to print after the decimal. Tailing 0’s will be truncated regardless of setting.

What it is

The formatted version of seconds. It looks like timecode, but with a decimal seconds value instead of a frame number place.

Where you see it

• Anywhere real-world time is used.

• FFMPEG commands:

  ffmpeg -ss 00:00:30.5 -i input.mov -t 00:00:10.25 output.mp4
  

Examples

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!("01:00:03.6", tc.runtime(9))

note:

Runtime and timecode will differ with NTSC framerates. NTSC reports timecode as-if it were running at a whole-frame rate (so 23.98 is reported as if it were running at 24.)

Timecode::runtime reports the true, real-world time elapsed since 00:00:00:00.

pub fn premiere_ticks(&self) -> i64

Returns the number of elapsed ticks this timecode represents in Adobe Premiere Pro.

What it is

Internally, Adobe Premiere Pro uses ticks to divide up a second, and keep track of how far into that second we are. There are 254016000000 ticks in a second, regardless of framerate in Premiere.

Where you see it

• Premiere Pro Panel functions and scripts

• FCP7XML cutlists generated from Premiere:

  <clipitem id="clipitem-1">
      ...
      <in>158</in>
      <out>1102</out>
      <pproTicksIn>1673944272000</pproTicksIn>
      <pproTicksOut>11675231568000</pproTicksOut>
      ...
  </clipitem>
  

Examples

use num::Rational64;
let tc = Timecode::with_seconds(1.0, rates::F24).unwrap();
assert_eq!(254016000000, tc.premiere_ticks())

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!(915372057600000, tc.premiere_ticks())

pub fn feet_and_frames(&self) -> String

Returns the number of feet and frames this timecode represents if it were shot on 35mm 4-perf film (16 frames per foot). ex: ‘5400+13’.

What it is

On physical film, each foot contains a certain number of frames. For 35mm, 4-perf film (the most common type on Hollywood movies), this number is 16 frames per foot. Feet-And-Frames was often used in place of Keycode to quickly reference a frame in the edit.

Where you see it

For the most part, feet + frames has died out as a reference, because digital media is not measured in feet. The most common place it is still used is Studio Sound Departments. Many Sound Mixers and Designers intuitively think in feet + frames, and it is often burned into the reference picture for them.

• Telecine.
• Sound turnover reference picture.
• Sound turnover change lists.

Examples

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!("5400+00", tc.feet_and_frames())

pub fn rebase(&self, rate: Framerate) -> Self

Returns a Timecode with the same number of frames running at a different Framerate.

Arguments

• rate - The new framerate to apply to the frrame count..

let tc = Timecode::with_frames("01:00:00:00", rates::F24).unwrap();
let rebased = tc.rebase(rates::F48);
assert_eq!("00:30:00:00", rebased.timecode())

pub fn abs(&self) -> Self

Returns the absolute value of the Timecode value.

Examples

use num::Rational64;
let tc = Timecode::with_frames("-01:00:00:00", rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.abs().timecode())

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.abs().timecode())

pub fn with_frames<T: FramesSource>(
    frames: T,
    rate: Framerate
) -> TimecodeParseResult

Returns a new Timecode with a Timecode::frames return value equal to the frames arg.

Timecode::with_frames takes many different formats (more than just numeric types) that represent the frame count of the timecode.

Arguments

• frames - A value which can be represented as a frame number / frame count.

• rate - The Framerate at which the frames are being played back.

Examples

Create a Timecode from a timecode string:

let tc = Timecode::with_frames("01:00:00:00", rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

From am integer frame count:

let tc = Timecode::with_frames(86400, rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

From a feet+frames string:

use num::Rational64;
let tc = Timecode::with_frames("5400+00", rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

pub fn with_seconds<T: SecondsSource>(
    seconds: T,
    rate: Framerate
) -> TimecodeParseResult

Returns a new Timecode with a Timecode::seconds return value equal to the seconds arg (rounded to the nearest frame).

Timecode::with_seconds takes many different formats (more than just numeric types) that represent the frame count of the timecode.

Arguments

• seconds - A value which can be represented as a number of seconds.

• rate - The Framerate which seconds will be rounded to match the nearest frame with.

Examples

From a float value:

let tc = Timecode::with_seconds(3600.0, rates::F24).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

From a Rational64 value:

use num::Rational64;
let tc = Timecode::with_seconds(Rational64::new(3600, 1), rates::F24).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

From a Rational64 runtime:

let tc = Timecode::with_seconds("01:00:00.0", rates::F24).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

Note:

Remember that seconds are rounded to the nearest whole frame, so what you get back may not exactly match what you put in:

use num::Rational64;
let tc = Timecode::with_seconds(Rational64::new(3600, 1), rates::F23_98).unwrap();
assert_eq!(Rational64::new(43200157, 12000), tc.seconds())

pub fn with_premiere_ticks<T: PremiereTicksSource>(
    ticks: T,
    rate: Framerate
) -> TimecodeParseResult

Returns a new Timecode with a Timecode::premiere_ticks return value equal to the ticks arg.

Arguments

• ticks - A value which can be represented as a number Adobe Premiere Pro ticks.

• rate - The Framerate which seconds will be rounded to match the nearest frame with.

Examples

use num::Rational64;
let tc = Timecode::with_premiere_ticks(915372057600000i64, rates::F23_98).unwrap();
assert_eq!("01:00:00:00", tc.timecode())

Trait Implementations

impl Add<Timecode> for Timecode

type Output = Timecode

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<T> AddAssign<T> for Timecode where
    Timecode: Add<T, Output = Timecode>, 

fn add_assign(&mut self, rhs: T)

Performs the += operation.

impl Clone for Timecode

fn clone(&self) -> Timecode

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Timecode

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

Formats the value using the given formatter.

impl Display for Timecode

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

Formats the value using the given formatter.

impl Div<Ratio<i64>> for Timecode

type Output = Timecode

The resulting type after applying the / operator.

fn div(self, rhs: Rational64) -> Self::Output

Performs the / operation.

impl Div<f64> for Timecode

type Output = Timecode

The resulting type after applying the / operator.

fn div(self, rhs: f64) -> Self::Output

Performs the / operation.

impl Div<i64> for Timecode

type Output = Timecode

The resulting type after applying the / operator.

fn div(self, rhs: i64) -> Self::Output

Performs the / operation.

impl<T> DivAssign<T> for Timecode where
    Timecode: Div<T, Output = Timecode>, 

fn div_assign(&mut self, rhs: T)

Performs the /= operation.

impl Mul<Ratio<i64>> for Timecode

type Output = Timecode

The resulting type after applying the * operator.

fn mul(self, rhs: Rational64) -> Self::Output

Performs the * operation.

impl Mul<f64> for Timecode

type Output = Timecode

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Self::Output

Performs the * operation.

impl Mul<i64> for Timecode

type Output = Timecode

The resulting type after applying the * operator.

fn mul(self, rhs: i64) -> Self::Output

Performs the * operation.

impl<T> MulAssign<T> for Timecode where
    Timecode: Mul<T, Output = Timecode>, 

fn mul_assign(&mut self, rhs: T)

Performs the *= operation.

impl Neg for Timecode

type Output = Self

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Ord for Timecode

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Timecode> for Timecode

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

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

#[must_use]

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

This method tests for !=.

impl PartialOrd<Timecode> for Timecode

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Rem<Ratio<i64>> for Timecode

type Output = Timecode

The resulting type after applying the % operator.

fn rem(self, rhs: Rational64) -> Self::Output

Performs the % operation.

impl Rem<f64> for Timecode

type Output = Timecode

The resulting type after applying the % operator.

fn rem(self, rhs: f64) -> Self::Output

Performs the % operation.

impl Rem<i64> for Timecode

type Output = Timecode

The resulting type after applying the % operator.

fn rem(self, rhs: i64) -> Self::Output

Performs the % operation.

impl<T> RemAssign<T> for Timecode where
    Timecode: Rem<T, Output = Timecode>, 

fn rem_assign(&mut self, rhs: T)

Performs the %= operation.

impl Sub<Timecode> for Timecode

type Output = Timecode

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl<T> SubAssign<T> for Timecode where
    Timecode: Sub<T, Output = Timecode>, 

fn sub_assign(&mut self, rhs: T)

Performs the -= operation.

impl Copy for Timecode

impl Eq for Timecode