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

Returns the absolute value of tc.

examples

Examples

iex> tc = Timecode.with_frames!("-01:00:00:00", Rates.f23_98())
iex> Timecode.abs(tc) |> inspect()
"<01:00:00:00 <23.98 NTSC>>"

iex> tc = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Timecode.abs(tc) |> inspect()
"<01:00:00:00 <23.98 NTSC>>"

@spec add(
  a :: t() | Vtc.Source.Frames.t(),
  b :: t() | Vtc.Source.Frames.t(),
  opts :: [{:round, maybe_round()}]
) :: t()

Add two timecodes.

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

auto-casts Frames values.

options

Options

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

examples

Examples

Two timecodes running at the same rate:

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

Two timecodes running at different rates:

iex> a = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Timecode.with_frames!("00:00:00:02", Rates.f47_95())
iex> Timecode.add(a, b) |> inspect()
"<01:00:00:01 <23.98 NTSC>>"

Using a timcode and a bare string:

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

@spec div(
  dividend :: t(),
  divisor :: Ratio.t() | number(),
  opts :: [{:round, maybe_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 :floor to match divmod and the expected meaning of div to mean integer division in elixir.

examples

Examples

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

iex> dividend = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Timecode.div(dividend, 0.5) |> inspect()
"<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 Timecode.div/3 with the :round option set to :floor.

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 = Timecode.with_frames!("01:00:00:01", Rates.f23_98())
iex> Timecode.divrem(dividend, 4) |> inspect()
"{<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()

Evalutes timecode mathematical expressions in a do block.

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

options

Options

• at: The Framerate to cast non-timecode values to. If this value is not set, then at least one value in each operation must be a Timecode. 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 Timecode
iex>
iex> a = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Timecode.with_frames!("00:30:00:00", Rates.f23_98())
iex> c = Timecode.with_frames!("00:15:00:00", Rates.f23_98())
iex>
iex> result = Timecode.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 Timecode
iex>
iex> a = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> b = Timecode.with_frames!("00:30:00:00", Rates.f23_98())
iex> c = Timecode.with_frames!("00:15:00:00", Rates.f23_98())
iex>
iex> result = Timecode.eval(a + b * 2 - c)
iex>
iex> inspect(result)
"<01:45:00:00 <23.98 NTSC>>"

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

iex> b = Timecode.with_frames!("00:30:00:00", Rates.f23_98())
iex>
iex> result = Timecode.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 = Timecode.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 = Timecode.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 is assumed by default, but you can set a different value with the :ntsc option:

iex> result = Timecode.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> tc = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Timecode.minus(tc) |> inspect()
"<-01:00:00:00 <23.98 NTSC>>"

iex> tc = Timecode.with_frames!("-01:00:00:00", Rates.f23_98())
iex> Timecode.minus(tc) |> inspect()
"<01:00:00:00 <23.98 NTSC>>"

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

Scales a by b.

The result will inheret the framerat 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 = Timecode.with_frames!("01:00:00:00", Rates.f23_98())
iex> Timecode.mult(a, 2) |> inspect()
"<02:00:00:00 <23.98 NTSC>>"

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

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

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

The quotient is floored 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 = Timecode.with_frames!("01:00:00:01", Rates.f23_98())
iex> Timecode.rem(dividend, 4) |> inspect()
"<00:00:00:01 <23.98 NTSC>>"

@spec sub(
  a :: t(),
  b :: t() | Vtc.Source.Frames.t(),
  opts :: [{:round, maybe_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 inheret the framerat of a and be rounded to the seconds representation of the nearest whole-frame at that rate.

auto-casts Frames values.

options

Options

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

examples

Examples

Two timecodes running at the same rate:

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

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

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

Two timecodes running at different rates:

iex> a = Timecode.with_frames!("01:00:00:02", Rates.f23_98())
iex> b = Timecode.with_frames!("00:00:00:02", Rates.f47_95())
iex> Timecode.sub(a, b) |> inspect()
"<01:00:00:01 <23.98 NTSC>>"

Using a timcode and a bare string:

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