@spec abs(t()) :: t()

Returns the absolute value of tc.

examples

Examples

iex> stamp = Framestamp.with_frames!("-01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.abs(stamp)
iex> inspect(result)
"<01:00:00:00 <23.98 NTSC>>"

iex> stamp = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.abs(stamp)
iex> inspect(result)
"<01:00:00:00 <23.98 NTSC>>"

@spec add(
  a :: t() | Vtc.Source.Frames.t(),
  b :: t() | Vtc.Source.Frames.t(),
  opts :: [inherit_rate: inherit_opt(), round: round()]
) :: t()

Add two framestamps.

Uses the real-world seconds representation. When the rates of a and b are not equal, the result will inherit the framerate of a and be rounded to the seconds representation of the nearest whole-frame at that rate.

auto-casts Frames values.

options

Options

• inherit_rate: Which side to inherit the framerate from in mixed-rate calculations. If false, this function will raise if a.rate does not match b.rate. Default: false.

• round: How to round the result with respect to whole-frames when mixing framerates. Default: :closest.

examples

Examples

Two framestamps running at the same rate:

iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Framestamp.with_frames!("01:30:21:17", Rates.f23_98())
iex>
iex> result = Framestamp.add(a, b)
iex> inspect(result)
"<02:30:21:17 <23.98 NTSC>>"

Two framestamps running at different rates:

iex> a = Framestamp.with_frames!("01:00:00:02", Rates.f23_98())
iex> b = Framestamp.with_frames!("00:00:00:02", Rates.f47_95())
iex>
iex> result = Framestamp.add(a, b, inherit_rate: :left)
iex> inspect(result)
"<01:00:00:03 <23.98 NTSC>>"
iex>
iex> result = Framestamp.add(a, b, inherit_rate: :right)
iex> inspect(result)
"<01:00:00:06 <47.95 NTSC>>"

If :inherit_rate is not set...

iex> a = Framestamp.with_frames!("01:00:00:02", Rates.f23_98())
iex> b = Framestamp.with_frames!("00:00:00:02", Rates.f47_95())
iex> Framestamp.add(a, b)
** (Vtc.Framestamp.MixedRateArithmeticError) attempted `Framestamp.add(a, b)` where `a.rate` does not match `b.rate`. try `:inherit_rate` option to `:left` or `:right`. alternatively, do your calculation in seconds, then cast back to `Framestamp` with the appropriate framerate using `with_seconds/3`

Using a framestamps and a bare string:

iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.add(a, "01:30:21:17")
iex> inspect(result)
"<02:30:21:17 <23.98 NTSC>>"

@spec div(
  dividend :: t(),
  divisor :: Ratio.t() | number(),
  opts :: [{:round, round()}]
) :: t()

Divides dividend by divisor.

The result will inherit the framerate of dividend and rounded to the nearest whole-frame based on the :round option.

options

Options

• round: How to round the result with respect to whole-frame values. Defaults to :trunc to match divmod and the expected meaning of div to mean integer division in elixir.

examples

Examples

iex> dividend = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.div(dividend, 2)
iex> inspect(result)
"<00:30:00:00 <23.98 NTSC>>"

iex> dividend = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.div(dividend, 0.5)
iex> inspect(result)
"<02:00:00:00 <23.98 NTSC>>"

@spec divrem(
  dividend :: t(),
  divisor :: Ratio.t() | number(),
  opts :: [round_frames: round(), round_remainder: round()]
) :: {t(), t()}

Divides the total frame count of dividend by divisor and returns both a quotient and a remainder.

The quotient returned is equivalent to Framestamp.div/3 with the :round option set to :trunc.

options

Options

• round_frames: How to round the frame count before doing the divrem operation. Default: :closest.

• round_remainder: How to round the remainder frames when a non-whole frame would be the result. Default: :closest.

examples

Examples

iex> dividend = Framestamp.with_frames!("01:00:00:01", Rates.f23_98())
iex>
iex> result = Framestamp.divrem(dividend, 4)
iex> inspect(result)
"{<00:15:00:00 <23.98 NTSC>>, <00:00:00:01 <23.98 NTSC>>}"

@spec eval(
  [at: Vtc.Framerate.t() | number() | Ratio.t(), ntsc: Vtc.Framerate.ntsc()],
  Macro.input()
) ::
  Macro.t()

Evaluates Framestamp mathematical expressions in a do block.

Any code captured within this macro can use Kernel operators to work with Framestamp values instead of module functions like add/2.

options

Options

• at: The Framerate to cast non-Framestamp values to. If this value is not set, then at least one value in each operation must be a Framestamp. This value can be any value accepted by Framerate.new/2.

• ntsc: The ntsc value to use when creating a new Framerate with at. Not needed if at is a Framerate value.

examples

Examples

Use eval to do some quick math. The block captures variables from the outer scope, but contains the expression within its own scope, just like an if or with statement.

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> result =
iex>   Framestamp.eval do
iex>     a + b * 2 - c
iex>   end
iex>
iex> inspect(result)
"<01:45:00:00 <23.98 NTSC>>"

Or if you want to do it in one line:

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> result = Framestamp.eval(a + b * 2 - c)
iex>
iex> inspect(result)
"<01:45:00:00 <23.98 NTSC>>"

Just like the regular Framestamp functions, only one value in an arithmetic expression needs to be a Framestamp value. In the case above, since multiplication happens first, that's b:

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

You can supply a default framerate if you just want to do some quick calculations. This framerate is inherited by every value that implements the Frames protocol in the block, including integers:

iex> result =
iex>   Framestamp.eval at: Rates.f23_98() do
iex>     "01:00:00:00" + "00:30:00:00" * 2 - "00:15:00:00"
iex>   end
iex>
iex> inspect(result)
"<01:45:00:00 <23.98 NTSC>>"

You can use any value that can be parsed by Framerate.new/2.

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

ntsc: :non_drop, coerce_ntsc?: true is assumed by default, but you can set a different value with the :ntsc option:

iex> result =
iex>   Framestamp.eval at: 24, ntsc: nil do
iex>     "01:00:00:00" + "00:30:00:00" * 2 - "00:15:00:00"
iex>   end
iex>
iex> inspect(result)
"<01:45:00:00 <24.0 fps>>"

@spec minus(t()) :: t()

As the kernel -/1 function.

• Makes a positive tc value negative.
• Makes a negative tc value positive.

examples

Examples

iex> stamp = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.minus(stamp)
iex> inspect(result)
"<-01:00:00:00 <23.98 NTSC>>"

iex> stamp = Framestamp.with_frames!("-01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.minus(stamp)
iex> inspect(result)
"<01:00:00:00 <23.98 NTSC>>"

@spec mult(
  a :: t(),
  b :: Ratio.t() | number(),
  opts :: [{:round, round()}]
) :: t()

Scales a by b.

The result will inherit the framerate of a and be rounded to the seconds representation of the nearest whole-frame based on the :round option.

options

Options

• round: How to round the result with respect to whole-frame values. Defaults to :closest.

examples

Examples

iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.mult(a, 2)
iex> inspect(result)
"<02:00:00:00 <23.98 NTSC>>"

iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.mult(a, 0.5)
iex> inspect(result)
"<00:30:00:00 <23.98 NTSC>>"

@spec rem(
  dividend :: t(),
  divisor :: Ratio.t() | number(),
  opts :: [round_frames: round(), round_remainder: round()]
) :: t()

Divides the total frame count of dividend by devisor, and returns the remainder.

The quotient is truncated before the remainder is calculated.

options

Options

• round_frames: How to round the frame count before doing the rem operation. Default: :closest.

• round_remainder: How to round the remainder frames when a non-whole frame would be the result. Default: :closest.

examples

Examples

iex> dividend = Framestamp.with_frames!("01:00:00:01", Rates.f23_98())
iex>
iex> result = Framestamp.rem(dividend, 4)
iex> inspect(result)
"<00:00:00:01 <23.98 NTSC>>"

@spec sub(
  a :: t() | Vtc.Source.Frames.t(),
  b :: t() | Vtc.Source.Frames.t(),
  opts :: [inherit_rate: inherit_opt(), round: round()]
) :: t()

Subtract b from a.

Uses their real-world seconds representation. When the rates of a and b are not equal, the result will inherit the framerate of a and be rounded to the seconds representation of the nearest whole-frame at that rate.

auto-casts Frames values.

options

Options

• inherit_rate: Which side to inherit the framerate from in mixed-rate calculations. If false, this function will raise if a.rate does not match b.rate. Default: false.

• round: How to round the result with respect to whole-frames when mixing framerates. Default: :closest.

examples

Examples

Two framestamps running at the same rate:

iex> a = Framestamp.with_frames!("01:30:21:17", Rates.f23_98())
iex> b = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.sub(a, b)
iex> inspect(result)
"<00:30:21:17 <23.98 NTSC>>"

Two framestamps running at different rates:

iex> a = Framestamp.with_frames!("01:00:00:02", Rates.f23_98())
iex> b = Framestamp.with_frames!("00:00:00:02", Rates.f47_95())
iex>
iex> result = Framestamp.sub(a, b, inherit_rate: :left)
iex> inspect(result)
"<01:00:00:01 <23.98 NTSC>>"
iex>
iex> result = Framestamp.sub(a, b, inherit_rate: :right)
iex> inspect(result)
"<01:00:00:02 <47.95 NTSC>>"

If :inherit_rate is not set...

iex> a = Framestamp.with_frames!("01:00:00:02", Rates.f23_98())
iex> b = Framestamp.with_frames!("00:00:00:02", Rates.f47_95())
iex> Framestamp.sub(a, b)
** (Vtc.Framestamp.MixedRateArithmeticError) attempted `Framestamp.sub(a, b)` where `a.rate` does not match `b.rate`. try `:inherit_rate` option to `:left` or `:right`. alternatively, do your calculation in seconds, then cast back to `Framestamp` with the appropriate framerate using `with_seconds/3`

When b is greater than a, the result is negative:

iex> a = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Framestamp.with_frames!("02:00:00:00", Rates.f23_98())
iex>
iex> result = Framestamp.sub(a, b)
iex> inspect(result)
"<-01:00:00:00 <23.98 NTSC>>"

Using a framestamps and a bare string:

iex> a = Framestamp.with_frames!("01:30:21:17", Rates.f23_98())
iex>
iex> result = Framestamp.sub(a, "01:00:00:00")
iex> inspect(result)
"<00:30:21:17 <23.98 NTSC>>"