#
View Source Vtc.Framestamp.Range (vtc v0.13.15)

Holds a framestamp 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` framestamp as the last visible frame of a piece of footage. This style of timecode range is most often associated with AVID.

Exclusive framestamp ranges treat the `out` framestamp as the boundary where the range ends. This style of timecode 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.

## Parse

new(stamp_in, stamp_out, opts \\ [])

Creates a new Range.

new!(stamp_in, stamp_out, opts \\ [])

As `new/3`, but raises on error.

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

Returns a range with an `:in` value of `stamp_in` and a duration of `duration`.

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

As with_duration/3, but raises on error.

## Manipulate

with_exclusive_out(range)

Adjusts range to have an exclusive out framestamp.

with_inclusive_out(range)

Adjusts range to have an inclusive out framestamp.

## Inspect

duration(range)

Returns the duration in Framestamp of `range`.

## Compare

contains?(range, framestamp)

Returns `true` if `range` contains `framestamp`. `framestamp` may be any value that implements Frames.

intersection(a, b)

Returns the the range where `a` and `b` overlap/intersect.

intersection!(a, b)

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

overlaps?(a, b)

Returns `true` if there is overlap between `a` and `b`.

separation(a, b)

Returns the range between two, non-overlapping ranges.

separation!(a, b)

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

## Functions

embed_as(_)

Callback implementation for `Ecto.Type.embed_as/1`.

equal?(term1, term2)

Callback implementation for `Ecto.Type.equal?/2`.

# 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.Framestamp.Range{
      in: Vtc.Framestamp.t(),
      out: Vtc.Framestamp.t(),
      out_type: out_type()
    }

Range struct type.

# Link to this section Parse

Link to this function

# new(stamp_in, stamp_out, opts \\ [])

View Source

    @spec new(
      stamp_in :: Vtc.Framestamp.t(),
      stamp_out :: Vtc.Framestamp.t() | Vtc.Source.Frames.t(),
      opts :: [{:out_type, out_type()}]
    ) :: {:ok, t()} | {:error, Exception.t() | Vtc.Framestamp.ParseError.t()}

Creates a new Range.

`out_tc` may be a Framestamp 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 `stamp_in` and `stamp_out` do not have the same `rate`.

##

examples

Examples

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex> stamp_out = Framestamp.with_frames!("02:00:00:00", Rates.f23_98())
    iex>
    iex> result = Range.new(stamp_in, stamp_out)
    iex> inspect(result)
    "{:ok, <01:00:00:00 - 02:00:00:00 :exclusive <23.98 NTSC>>}"

Using a timecode string as `b`:

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex>
    iex> result = Range.new(stamp_in, "02:00:00:00")
    iex> inspect(result)
    "{:ok, <01:00:00:00 - 02:00:00:00 :exclusive <23.98 NTSC>>}"

Making a range with an inclusive out:

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex>
    iex> result = Range.new(stamp_in, "02:00:00:00", out_type: :inclusive)
    iex> inspect(result)
    "{:ok, <01:00:00:00 - 02:00:00:00 :inclusive <23.98 NTSC>>}"

Link to this function

# new!(stamp_in, stamp_out, opts \\ [])

View Source

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

As `new/3`, but raises on error.

Link to this function

# with_duration(stamp_in, duration, opts \\ [])

View Source

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

Returns a range with an `:in` value of `stamp_in` and a duration of `duration`.

`duration` may be a Framestamp value for any value that implements the Frames protocol. Returns an error if `duration` is less than `0` seconds or if `stamp_in` and `stamp_out` do not have the same `rate`.

##

examples

Examples

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

Using a timecode string as `b`:

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex>
    iex> result = Range.with_duration(stamp_in, "00:30:00:00")
    iex> inspect(result)
    "{:ok, <01:00:00:00 - 01:30:00:00 :exclusive <23.98 NTSC>>}"

Making a range with an inclusive out:

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex>
    iex> result = Range.with_duration(stamp_in, "00:30:00:00", out_type: :inclusive)
    iex> inspect(result)
    "{:ok, <01:00:00:00 - 01:29:59:23 :inclusive <23.98 NTSC>>}"

Link to this function

# with_duration!(stamp_in, duration, opts \\ [])

View Source

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

As with_duration/3, but raises on error.

# Link to this section Manipulate

Link to this function

# with_exclusive_out(range)

View Source

    @spec with_exclusive_out(t()) :: t()

Adjusts range to have an exclusive out framestamp.

##

examples

Examples

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex> range = Range.new!(stamp_in, "02:00:00:00", out_type: :inclusive)
    iex>
    iex> result = Range.with_exclusive_out(range)
    iex> inspect(result)
    "<01:00:00:00 - 02:00:00:01 :exclusive <23.98 NTSC>>"

Link to this function

# with_inclusive_out(range)

View Source

    @spec with_inclusive_out(t()) :: t()

Adjusts range to have an inclusive out framestamp.

##

examples

Examples

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

# Link to this section Inspect

Link to this function

# duration(range)

View Source

    @spec duration(t()) :: Vtc.Framestamp.t()

Returns the duration in Framestamp of `range`.

##

examples

Examples

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex> range = Range.new!(stamp_in, "01:30:00:00")
    iex>
    iex> result = Range.duration(range)
    iex> inspect(result)
    "<00:30:00:00 <23.98 NTSC>>"

# Link to this section Compare

Link to this function

# contains?(range, framestamp)

View Source

    @spec contains?(t(), Vtc.Framestamp.t() | Vtc.Source.Frames.t()) :: boolean()

Returns `true` if `range` contains `framestamp`. `framestamp` may be any value that implements Frames.

##

examples

Examples

    iex> stamp_in = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
    iex> range = Range.new!(stamp_in, "01:30:00:00")
    iex>
    iex> Range.contains?(range, "01:10:00:00")
    true
    iex> Range.contains?(range, "01:40:00:00")
    false

Link to this function

# intersection(a, b)

View Source

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

Returns the the range where `a` and `b` overlap/intersect.

Returns `nil` if the two ranges do not intersect.

`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 = Framestamp.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 = Framestamp.with_frames!("01:50:00:00", Rates.f23_98())
    iex> b = Range.new!(b_in, "02:30:00:00", out_type: :inclusive)
    iex>
    iex> result = Range.intersection(a, b)
    iex> inspect(result)
    "{:ok, <01:50:00:00 - 02:00:00:00 :inclusive <23.98 NTSC>>}"

    iex> a_in = Framestamp.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 = Framestamp.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 = Framestamp.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 = Framestamp.with_frames!("02:10:00:00", Rates.f23_98())
    iex> b = Range.new!(b_in, "03:30:00:00", out_type: :inclusive)
    iex>
    iex> result = Range.intersection!(a, b)
    iex> inspect(result)
    "<00:00:00:00 - -00:00:00:01 :inclusive <23.98 NTSC>>"

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 = Framestamp.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 = Framestamp.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 = Framestamp.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 = Framestamp.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 the range between two, non-overlapping ranges.

Returns `nil` if the two ranges are not separated.

`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 = Framestamp.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 = Framestamp.with_frames!("02:10:00:00", Rates.f23_98())
    iex> b = Range.new!(b_in, "03:30:00:00", out_type: :inclusive)
    iex>
    iex> result = Range.separation(a, b)
    iex> inspect(result)
    "{:ok, <02:00:00:01 - 02:09:59:23 :inclusive <23.98 NTSC>>}"

    iex> a_in = Framestamp.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 = Framestamp.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 = Framestamp.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 = Framestamp.with_frames!("01:50:00:00", Rates.f23_98())
    iex> b = Range.new!(b_in, "02:30:00:00", out_type: :inclusive)
    iex>
    iex> result = Range.separation!(a, b)
    iex> inspect(result)
    "<00:00:00:00 - -00:00:00:01 :inclusive <23.98 NTSC>>"

# Link to this section Functions

Link to this function

# embed_as(_)

View Source

Callback implementation for `Ecto.Type.embed_as/1`.

Link to this function

# equal?(term1, term2)

View Source

Callback implementation for `Ecto.Type.equal?/2`.