Vtc.Timecode (vtc v0.2.6) View Source
Represents the frame at a particular time in a video.
New Timecode values are created with the with_seconds/2
and with_frames/2
, and
other function prefaced by with_*
.
Link to this section Summary
Functions
Returns whether a
is greater than, equal to, or less than b
in terms of real-world
seconds.
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'.
Returns the number of frames that would have elapsed between 00:00:00:00 and this timecode.
Returns the number of elapsed ticks this timecode represents in Adobe Premiere Pro.
Rebases the timecode to a new framerate.
As rebase/2
, but raises on error.
Runtime Returns the true, real-world runtime of the timecode in HH:MM:SS.FFFFFFFFF format.
The individual sections of a timecode string as i64 values.
Returns the the formatted SMPTE timecode: (ex: 01:00:00:00). Drop frame timecode will be rendered with a ';' sperator before the frames field.
Returns a new Timecode
with a frames/1
return value equal to the frames
arg.
As Timecode.with_frames/2
, but raises on error.
Returns a new Timecode
with a premiere_ticks/1
return value equal
to the ticks arg.
As with_premiere_ticks/2
, but raises on error.
Returns a new Timecode
with a Timecode.seconds field value equal to the
seconds arg.
As with_seconds/2
, but raises on error.
Link to this section Types
Specs
parse_result() :: {:ok, t()} | {:error, Vtc.Timecode.ParseError.t()}
Type returned by with_seconds/2
and with_frames/2
.
Specs
t() :: %Vtc.Timecode{rate: Vtc.Framerate.t(), seconds: Vtc.Utils.Rational.t()}
Timecode
type.
Fields
seconds: The real-world seconds elapsed since 01:00:00:00 as a rational value. (Note: The Ratio module automatically will coerce itself to an integer whenever possible, so this value may be an integer when exactly a whole-second value).
rate: the Framerate of the timecode.
Link to this section Functions
Specs
compare(t(), t() | Vtc.Source.Frames.t()) :: :lt | :eq | :gt
Returns whether a
is greater than, equal to, or less than b
in terms of real-world
seconds.
b May be any value that implements the Frames
protocol, such as a timecode string,
and will be assumed to be the same framerate as a
. This is mostly to support quick
scripting.
Examples
Using two timecodes, 01:00:00:00
NTSC is greater than 01:00:00:00
true because it
represents more real-world time.
iex> a = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Timecode.with_frames!("01:00:00:00", Rates.f24())
iex> :gt = Timecode.compare(a, b)
Using a timcode and a bare string:
iex> timecode = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> :eq = Timecode.compare(timecode, "01:00:00:00")
Specs
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.
Specs
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>
Specs
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>
Specs
rebase(t(), Vtc.Framerate.t()) :: parse_result()
Rebases the timecode to a new framerate.
The real-world seconds are recalculated using the same frame count as if they were
being played back at new_rate
instead of timecode.rate
.
Examples
iex> timecode = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> {:ok, rebased} = Timecode.rebase(timecode, Rates.f47_95())
iex> Timecode.to_string(rebased)
"<00:30:00:00 @ <47.95 NTSC NDF>>"
Specs
rebase!(t(), Vtc.Framerate.t()) :: t()
As rebase/2
, but raises on error.
Specs
Runtime Returns the true, real-world runtime of the timecode in HH:MM:SS.FFFFFFFFF format.
Arguments
precision
: The number of places to round to. Extra trailing 0's will still be trimmed.
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
Note
The true runtime will often diverge from the hours, minutes, and seconds value of the timecode representation when dealing with non-whole-frame framerates. Even drop-frame timecode does not continuously adhere 1:1 to the actual runtime. For instance, <01:00:00;00 @ <29.97 NTSC DF>> has a true runtime of '00:59:59.9964', and <01:00:00:00 @ <23.98 NTSC NDF>> has a true runtime of '01:00:03.6'
Specs
sections(t()) :: Vtc.Timecode.Sections.t()
The individual sections of a timecode string as i64 values.
Specs
Returns the the formatted SMPTE timecode: (ex: 01:00:00:00). Drop frame timecode will be rendered with a ';' sperator before the frames field.
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.
Specs
Specs
with_frames(Vtc.Source.Frames.t(), Vtc.Framerate.t()) :: parse_result()
Returns a new Timecode
with a frames/1
return value equal to the frames
arg.
Arguments
frames: A value which can be represented as a frame number / frame count. Must implement the
Frames
protocol.rate: Frame-per-second playback value of the timecode.
Specs
with_frames!(Vtc.Source.Frames.t(), Vtc.Framerate.t()) :: t()
As Timecode.with_frames/2
, but raises on error.
Specs
with_premiere_ticks(Vtc.Source.PremiereTicks.t(), Vtc.Framerate.t()) :: parse_result()
Returns a new Timecode
with a premiere_ticks/1
return value equal
to the ticks arg.
Arguments
ticks: Any value that can represent the number of ticks for a given timecode. Must implement the
PremiereTicks
protocol.rate: Frame-per-second playback value of the timecode.
Specs
with_premiere_ticks!(Vtc.Source.Frames.t(), Vtc.Framerate.t()) :: t()
As with_premiere_ticks/2
, but raises on error.
Specs
with_seconds(Vtc.Source.Seconds.t(), Vtc.Framerate.t()) :: parse_result()
Returns a new Timecode
with a Timecode.seconds field value equal to the
seconds arg.
Arguments
seconds: A value which can be represented as a number of seconds. Must implement the
Seconds
protocol.rate: Frame-per-second playback value of the timecode.
Specs
with_seconds!(Vtc.Source.Seconds.t(), Vtc.Framerate.t()) :: t()
As with_seconds/2
, but raises on error.