Settings View Source Print cheatsheet Quickstart

parsing

Parsing

Parsing is flexible, we can pass in partial or malformed timecode.

In Vtc, there are only two ways to parse framestamps, either with Timecode.with_frames/2 for formats that represent a discrete frame count, or Timecode.with_seconds/2 for formats that represent a number of real-world, elapsed seconds were those frames to be played back at the framestamp's rate.

other-film-formats

Other film formats

By default, feet+frames is interpreted as 35mm, 4perf film. You can use the FeetAndFrames struct to parse other film formats.

16mm feet + frames

iex> alias Vtc.Source.Frames.FeetAndFrames
iex> 
iex> {:ok, feet_and_frames} = FeetAndFrames.from_string("5400+00", film_format: :ff16mm)
iex> 
iex> Framestamp.with_frames(feet_and_frames, Rates.f23_98())
"{:ok, <01:15:00:00 <23.98 NTSC>>}"

eval

Eval

Special Framestamp.eval do blocks let us use native operators.

eval/2

iex> require Framestamp
iex> 
iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Framestamp.with_frames!("00:30:00:00", Rates.f23_98())
iex> c = Framestamp.with_frames!("00:15:00:00", Rates.f23_98())
iex> 
iex> Framestamp.eval do
iex>   a + b * 2 - c
iex> end
"<01:45:00:00 <23.98 NTSC>>"

Or even do some quick scratch calculations in a given framerate:

scratch calculation

iex> Framestamp.eval at: 23.98 do
iex>   "01:00:00:00" + "00:30:00:00" * 2 - "00:15:00:00"
iex> end
"<01:45:00:00 <23.98 NTSC>>"

framerates

Framerates

We can make drop-frame framestamps for 29.97 or 59.94 using one of the pre-set framerates.

drop-frame

iex> Framestamp.with_frames!(15_000, Rates.f29_97_df())
"<00:08:20;18 <29.97 NTSC DF>>"

We can make new framestamps with arbitrary framerates if we want.

non-ntsc

iex> Framestamp.with_frames!("01:00:00:00", Framerate.new!(240, nil))
"<01:00:00:00 <240.0 fps>>"

Using :non_drop indicates this framestamp represents an NTSC timecode, and will convert whole-number timebases to the correct speed.

non-drop coercion

iex> Framestamp.with_frames!("01:00:00:00", Framerate.new!(48, :non_drop))
"<01:00:00:00 <47.95 NTSC>>"

We can also rebase the frames using a new framerate!

rebase

iex> Framestamp.rebase(tc, Rates.f23_98())
"<02:00:00:00 <23.98 NTSC>>"

comparisons-and-sorting

Comparisons and Sorting

It's easy to compare two framestamps.

compare/2

iex> a = Framestamp.with_frames!("02:00:00:00", Rates.f23_98())
iex> b = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> 
iex> Framestamp.compare(a, b)
:lt

There a host of other specific comparison functions like eq?/2, gt?/2 that return booleans.

Specific comparison

iex> Framestamp.lt?(a, b)
true

Like arithmetic, we can compare directly with a timecode string:

compare/2 with string

iex> Framestamp.compare(a, "00:59:00:00")
:gt

Sorting is supported through the compare/2 function.

sort through Framestamp

iex> framestamp_01 = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> framestamp_02 = Framestamp.with_frames!("02:00:00:00", Rates.f23_98())
iex> 
iex> data_01 = %{id: 2, tc: framestamp_01}
iex> data_02 = %{id: 1, tc: framestamp_02}
iex> 
iex> Enum.sort_by([data_02, data_01], & &1.tc, Framestamp)
"[%{id: 2, tc: <01:00:00:00 <23.98 NTSC>>}, %{id: 1, tc: <02:00:00:00 <23.98 NTSC>>}]"

ranges

Ranges

Range helps with common operations using in/out points. Let's set two of those up.

new/3

iex> a_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> a_out = Framestamp.with_frames!("02:00:00:00", Rates.f23_98())
iex> 
iex> a = Framestamp.Range.new!(a_in, a_out)
"<01:00:00:00 - 02:00:00:00 :exclusive <23.98 NTSC>>"

By default, ranges are exclusive, meaning the out point represents the boundary where the clip ends, not the final frame that is part of the video clip. This way will be familiar to Premiere and Final Cut editors. But fear not, our Avid brethren, inclusive out points like you are used to are available as well!

Just like addition, we can write a bare timecode string as the out value if we want.

new/3 with string

iex> b_in = Framestamp.with_frames!("01:45:00:00", Rates.f23_98())
iex> 
iex> b = Framestamp.Range.new!(b_in, "02:30:00:00")
"<01:45:00:00 - 02:30:00:00 :exclusive <23.98 NTSC>>"

We can get the duration of a range.

duration/1

iex> Framestamp.Range.duration(b)
iex> "<00:45:00:00 <23.98 NTSC>>"

... see if a specific framestamp is in a range:

contains?/2

iex> Framestamp.Range.contains?(b, "02:00:00:00")
iex> true

... or see if it overlaps with another range.

overlaps?/2

iex> Framestamp.Range.overlaps?(a, b)
iex> true

We can even get the overlapping area as its own range!

intersection/2

iex> Framestamp.Range.intersection!(a, b)
"<01:45:00:00 - 02:00:00:00 :exclusive <23.98 NTSC>>"

postgres-types

Postgres Types

To include Postgres types with Ecto. Add the following into you applications configuration file:

config :vtc,
  env: config_env(),
  include_postgres_types?: true

See each Postgres type for information on it's configuration.