pub struct Timecode { /* private fields */ }
Expand description
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.
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§
source§impl Timecode
impl Timecode
sourcepub fn rate(&self) -> Framerate
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())
sourcepub fn seconds(&self) -> Rational64
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())
sourcepub fn sections(&self) -> TimecodeSections
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())
sourcepub fn timecode(&self) -> String
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())
sourcepub fn frames(&self) -> i64
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())
sourcepub fn runtime(&self, precision: usize) -> String
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.
sourcepub fn premiere_ticks(&self) -> i64
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())
sourcepub fn feet_and_frames(&self, rep: FilmFormat) -> String
pub fn feet_and_frames(&self, rep: FilmFormat) -> String
Create a feet+frames string of self
.
What it is
The customary text representation of frame-accurate film footage.
The rep
parameter selects the film format. 35mm, 4-perf vertical
pulldown is by far the most common, but other film gauges and pulldowns
are supported. See the [FeetFramesRep] enum for all available formats.
Where you see it
- Film assembly and pull lists, chronologs and camera reports
- FLX and ALE telecine log files
- Avid film pull lists, cut lists and change lists
sourcepub fn rebase(&self, rate: Framerate) -> Self
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())
sourcepub fn abs(&self) -> Self
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())
sourcepub fn with_frames<T: FramesSource>(
frames: T,
rate: Framerate
) -> TimecodeParseResult
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())
sourcepub fn with_seconds<T: SecondsSource>(
seconds: T,
rate: Framerate
) -> TimecodeParseResult
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())
sourcepub fn with_premiere_ticks<T: PremiereTicksSource>(
ticks: T,
rate: Framerate
) -> TimecodeParseResult
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§
source§impl<T> AddAssign<T> for Timecodewhere
Timecode: Add<T, Output = Timecode>,
impl<T> AddAssign<T> for Timecodewhere Timecode: Add<T, Output = Timecode>,
source§fn add_assign(&mut self, rhs: T)
fn add_assign(&mut self, rhs: T)
+=
operation. Read moresource§impl<T> DivAssign<T> for Timecodewhere
Timecode: Div<T, Output = Timecode>,
impl<T> DivAssign<T> for Timecodewhere Timecode: Div<T, Output = Timecode>,
source§fn div_assign(&mut self, rhs: T)
fn div_assign(&mut self, rhs: T)
/=
operation. Read moresource§impl<T> MulAssign<T> for Timecodewhere
Timecode: Mul<T, Output = Timecode>,
impl<T> MulAssign<T> for Timecodewhere Timecode: Mul<T, Output = Timecode>,
source§fn mul_assign(&mut self, rhs: T)
fn mul_assign(&mut self, rhs: T)
*=
operation. Read moresource§impl Ord for Timecode
impl Ord for Timecode
source§impl PartialEq<Timecode> for Timecode
impl PartialEq<Timecode> for Timecode
source§impl PartialOrd<Timecode> for Timecode
impl PartialOrd<Timecode> for Timecode
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> RemAssign<T> for Timecodewhere
Timecode: Rem<T, Output = Timecode>,
impl<T> RemAssign<T> for Timecodewhere Timecode: Rem<T, Output = Timecode>,
source§fn rem_assign(&mut self, rhs: T)
fn rem_assign(&mut self, rhs: T)
%=
operation. Read moresource§impl<T> SubAssign<T> for Timecodewhere
Timecode: Sub<T, Output = Timecode>,
impl<T> SubAssign<T> for Timecodewhere Timecode: Sub<T, Output = Timecode>,
source§fn sub_assign(&mut self, rhs: T)
fn sub_assign(&mut self, rhs: T)
-=
operation. Read more