# `BB.Camera.FFmpeg.FrameRate`
[🔗](https://github.com/beam-bots/bb_camera_ffmpeg/blob/main/lib/bb/camera/ffmpeg/frame_rate.ex#L5)

An exact frame rate, held as a rational.

Video frame rates are rational numbers and some of the common ones are not
representable in binary floating point: 30000/1001 is the NTSC rate, and
rounding it to `29.97` is a different rate that drifts against the real one.
ffmpeg takes a rational, so there is no reason to lose it on the way
through. What a device input does with it is the input's business; some
match it against the camera's own rates only approximately.

A rate can be given as a `Localize.Unit` in hertz (what the rest of the BB
DSL uses), a bare positive number, or a `{numerator, denominator}` tuple when
the exact rational matters:

    frame_rate: ~u(30 hertz)
    frame_rate: 30
    frame_rate: {30_000, 1001}

Non-integer values are converted by scaling out the decimal digits and
reducing, so `29.97` becomes `2997/100` — exactly the number that was
written, not an approximation of something else. Ask for `{30_000, 1001}` if
that is the rate you actually mean.

# `input`

```elixir
@type input() :: Localize.Unit.t() | {pos_integer(), pos_integer()} | number()
```

# `t`

```elixir
@type t() :: %BB.Camera.FFmpeg.FrameRate{
  denominator: pos_integer(),
  numerator: pos_integer()
}
```

# `new`

```elixir
@spec new(input() | t()) :: {:ok, t()} | {:error, :not_positive | :not_a_frame_rate}
```

Build a frame rate from any of the accepted forms.

    iex> {:ok, rate} = BB.Camera.FFmpeg.FrameRate.new({30_000, 1001})
    iex> BB.Camera.FFmpeg.FrameRate.to_string(rate)
    "30000/1001"

    iex> {:ok, rate} = BB.Camera.FFmpeg.FrameRate.new(30)
    iex> BB.Camera.FFmpeg.FrameRate.to_string(rate)
    "30"

    iex> {:ok, rate} = BB.Camera.FFmpeg.FrameRate.new(29.97)
    iex> BB.Camera.FFmpeg.FrameRate.to_string(rate)
    "2997/100"

    iex> BB.Camera.FFmpeg.FrameRate.new(0)
    {:error, :not_positive}

    iex> BB.Camera.FFmpeg.FrameRate.new({30, 0})
    {:error, :not_positive}

# `new!`

```elixir
@spec new!(input() | t()) :: t() | no_return()
```

Build a frame rate, raising on anything that is not one.

# `option_type`

```elixir
@spec option_type() :: {:custom, module(), atom(), [term()]}
```

A `Spark.Options` type accepting every form of `t:input/0`.

# `to_float`

```elixir
@spec to_float(t()) :: float()
```

The rate as a float, for reporting.

    iex> BB.Camera.FFmpeg.FrameRate.to_float(BB.Camera.FFmpeg.FrameRate.new!({30_000, 1001}))
    29.97002997002997

# `to_string`

```elixir
@spec to_string(t()) :: String.t()
```

The rate in the `num/den` form ffmpeg accepts.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
