vtc
vtc
v0.4.0

View Source Vtc.Range (vtc v0.4.0)

Holds a timecode range.

struct-fields

 Struct Fields

  • in: Start TC. Must be less than or equal to out.
  • out: End TC. Must be greater than or equal to in.
  • inclusive: See below for more information. Default: false

inclusive-vs-exclusive-ranges

 Inclusive vs. Exclusive Ranges

Inclusive ranges treat the out timecode as the last visible frame of a piece of footage. This style of tc range is most often associated with AVID.

Exclusive timecode ranges treat the out timecode as the boundary where the range ends. This style of tc range is most often associated with Final Cut and Premiere.

In mathematical notation, inclusive ranges are [in, out], while exclusive ranges are [in, out).

Link to this section Summary

Types

out_type()

Whether the end point should be treated as the Range's boundary (:exclusive), or its last element (:inclusive).

t()

Range struct type.

Functions

duration(range)

Returns the duration in Timecode of range.

intersection(a, b)

Returns nil if the two ranges do not intersect, otherwise returns the Range of the intersection of the two Ranges.

intersection!(a, b)

As intersection, but returns a Range from 00:00:00:00 - 00:00:00:00 when there is no overlap.

new(tc_in, tc_out, opts \\ [])

Creates a new Range.

new!(tc_in, tc_out, opts \\ [])

As new/3, but raises on error.

overlaps?(a, b)

Returns true if there is overlap between a and b.

separation(a, b)

Returns nil if the two ranges do intersect, otherwise returns the Range of the space between the intersections of the two Ranges.

separation!(a, b)

As separation, but returns a Range from 00:00:00:00 - 00:00:00:00 when there is overlap.

with_duration(tc_in, duration, opts \\ [])

Returns a range with an :in value of tc_in and a duration of duration. duration may be a Timecode value for any value that implements the Frames protocol.

with_duration!(tc_in, duration, opts \\ [])

As with_duration/3, but raises on error.

with_exclusive_out(range)

Adjusts range to have an exclusive out timecode.

with_inclusive_out(range)

Adjusts range to have an inclusive out timecode.

Link to this section Types

Link to this type

out_type()

View Source 
@type out_type() :: :inclusive | :exclusive

Whether the end point should be treated as the Range's boundary (:exclusive), or its last element (:inclusive).

Link to this type

t()

View Source 
@type t() :: %Vtc.Range{
  in: Vtc.Timecode.t(),
  out: Vtc.Timecode.t(),
  out_type: out_type()
}

Range struct type.

Link to this section Functions

Link to this function

duration(range)

View Source 
@spec duration(t()) :: Vtc.Timecode.t()

Returns the duration in Timecode of range.

examples

 Examples 

iex> tc_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> range = Range.new!(tc_in, "01:30:00:00")
iex> Range.duration(range) |> inspect()
"<00:30:00:00 <23.98 NTSC NDF>>"
Link to this function

intersection(a, b)

View Source 
@spec intersection(t(), t()) :: {:ok, t()} | {:error, :none}

Returns nil if the two ranges do not intersect, otherwise returns the Range of the intersection of the two Ranges.

a and b do not have to have matching :out_type settings, but the result will inherit a's setting.

examples

 Examples 

iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("01:50:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "02:30:00:00", out_type: :inclusive)
iex> Range.intersection(a, b) |> inspect()
"{:ok, <01:50:00:00 - 02:00:00:00 :inclusive <23.98 NTSC NDF>>}"
iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("02:10:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "03:30:00:00", out_type: :inclusive)
iex> Range.intersection(a, b)
{:error, :none}
Link to this function

intersection!(a, b)

View Source 
@spec intersection!(t(), t()) :: t()

As intersection, but returns a Range from 00:00:00:00 - 00:00:00:00 when there is no overlap.

This returned range inherets the framerate and out_type from a.

examples

 Examples 

iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("02:10:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "03:30:00:00", out_type: :inclusive)
iex> Range.intersection!(a, b) |> inspect()
"<00:00:00:00 - -00:00:00:01 :inclusive <23.98 NTSC NDF>>"
Link to this function

new(tc_in, tc_out, opts \\ [])

View Source 
@spec new(
  in_tc :: Vtc.Timecode.t(),
  out_tc :: Vtc.Timecode.t() | Vtc.Source.Frames.t(),
  opts :: [{:out_type, out_type()}]
) :: {:ok, t()} | {:error, Exception.t() | Vtc.Timecode.ParseError.t()}

Creates a new Range.

out_tc may be a Timecode value for any value that implements the Frames protocol.

Returns an error if the resulting range would not have a duration greater or eual to 0, or if tc_in and tc_out do not have the same rate.

examples

 Examples 

iex> tc_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> tc_out = Timecode.with_frames!("02:00:00:00", Rates.f23_98())
iex> Range.new(tc_in, tc_out) |> inspect()
"{:ok, <01:00:00:00 - 02:00:00:00 :exclusive <23.98 NTSC NDF>>}"

Using a timecode string as b:

iex> tc_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Range.new(tc_in, "02:00:00:00") |> inspect()
"{:ok, <01:00:00:00 - 02:00:00:00 :exclusive <23.98 NTSC NDF>>}"

Making a range with an inclusive out:

iex> tc_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Range.new(tc_in, "02:00:00:00", out_type: :inclusive) |> inspect()
"{:ok, <01:00:00:00 - 02:00:00:00 :inclusive <23.98 NTSC NDF>>}"
Link to this function

new!(tc_in, tc_out, opts \\ [])

View Source 
@spec new!(Vtc.Timecode.t(), Vtc.Timecode.t(), opts :: [{:out_type, out_type()}]) ::
  t()

As new/3, but raises on error.

Link to this function

overlaps?(a, b)

View Source 
@spec overlaps?(t(), t()) :: boolean()

Returns true if there is overlap between a and b.

examples

 Examples 

iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("01:50:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "02:30:00:00", out_type: :inclusive)
iex> Range.overlaps?(a, b)
true
iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("02:10:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "03:30:00:00", out_type: :inclusive)
iex> Range.overlaps?(a, b)
false
Link to this function

separation(a, b)

View Source 
@spec separation(t(), t()) :: {:ok, t()} | {:error, :none}

Returns nil if the two ranges do intersect, otherwise returns the Range of the space between the intersections of the two Ranges.

a and b do not have to have matching :out_type settings, but the result will inherit a's setting.

examples

 Examples 

iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("02:10:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "03:30:00:00", out_type: :inclusive)
iex> Range.separation(a, b) |> inspect()
"{:ok, <02:00:00:01 - 02:09:59:23 :inclusive <23.98 NTSC NDF>>}"
iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("01:50:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "02:30:00:00", out_type: :inclusive)
iex> Range.separation(a, b)
{:error, :none}
Link to this function

separation!(a, b)

View Source 
@spec separation!(t(), t()) :: t()

As separation, but returns a Range from 00:00:00:00 - 00:00:00:00 when there is overlap.

This returned range inherets the framerate and out_type from a.

examples

 Examples 

iex> a_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> a = Range.new!(a_in, "02:00:00:00", out_type: :inclusive)
iex>
iex> b_in = Timecode.with_frames!("01:50:00:00", Rates.f23_98())
iex> b = Range.new!(b_in, "02:30:00:00", out_type: :inclusive)
iex> Range.separation!(a, b) |> inspect()
"<00:00:00:00 - -00:00:00:01 :inclusive <23.98 NTSC NDF>>"
Link to this function

with_duration(tc_in, duration, opts \\ [])

View Source 
@spec with_duration(
  tc_in :: Vtc.Timecode.t(),
  duration :: Vtc.Timecode.t() | Vtc.Source.Frames.t(),
  opts :: [{:out_type, out_type()}]
) :: {:ok, t()} | {:error, Exception.t() | Vtc.Timecode.ParseError.t()}

Returns a range with an :in value of tc_in and a duration of duration. duration may be a Timecode value for any value that implements the Frames protocol.

Returns an error if duration is less than 0 seconds or if tc_in and tc_out do not have the same rate.

examples

 Examples 

iex> start_tc = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> duration = Timecode.with_frames!("00:30:00:00", Rates.f23_98())
iex> Range.with_duration(start_tc, duration) |> inspect()
"{:ok, <01:00:00:00 - 01:30:00:00 :exclusive <23.98 NTSC NDF>>}"

Using a timecode string as b:

iex> start_tc = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Range.with_duration(start_tc, "00:30:00:00") |> inspect()
"{:ok, <01:00:00:00 - 01:30:00:00 :exclusive <23.98 NTSC NDF>>}"

Making a range with an inclusive out:

iex> start_tc = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Range.with_duration(start_tc, "00:30:00:00", out_type: :inclusive) |> inspect()
"{:ok, <01:00:00:00 - 01:29:59:23 :inclusive <23.98 NTSC NDF>>}"
Link to this function

with_duration!(tc_in, duration, opts \\ [])

View Source 
@spec with_duration!(
  Vtc.Timecode.t(),
  Vtc.Timecode.t(),
  opts :: [{:out_type, out_type()}]
) :: t()

As with_duration/3, but raises on error.

Link to this function

with_exclusive_out(range)

View Source 
@spec with_exclusive_out(t()) :: t()

Adjusts range to have an exclusive out timecode.

examples

 Examples 

iex> tc_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> range = Range.new!(tc_in, "02:00:00:00", out_type: :inclusive)
iex> Range.with_exclusive_out(range) |> inspect()
"<01:00:00:00 - 02:00:00:01 :exclusive <23.98 NTSC NDF>>"
Link to this function

with_inclusive_out(range)

View Source 
@spec with_inclusive_out(t()) :: t()

Adjusts range to have an inclusive out timecode.

examples

 Examples 

iex> tc_in = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> range = Range.new!(tc_in, "02:00:00:00")
iex> Range.with_inclusive_out(range) |> inspect()
"<01:00:00:00 - 01:59:59:23 :inclusive <23.98 NTSC NDF>>"