# `BB.Camera.Libcamera.Command`
[🔗](https://github.com/beam-bots/bb_camera_libcamera/blob/main/lib/bb/camera/libcamera/command.ex#L5)

The `rpicam-vid` invocation for one capture, built and validated up front.

Keeping this separate from the process that runs it means the exact argument
vector for a given set of camera options is a pure function, and can be
asserted on without a camera, without `rpicam-vid`, and without starting
anything.

## No shell, ever

The vector is handed to MuonTrap, which `execvp`s `rpicam-vid` with the
arguments as given. No shell parses them.

## Which camera

`rpicam-vid --camera` takes an index into its own camera list, and that list
is the only thing the index means anything against. A camera named by its
libcamera id is therefore resolved to an index by asking the same executable
for that list - see `BB.Camera.Libcamera.Devices` - immediately before each
capture, rather than once and remembered. `argv/2` takes the resolved index;
the command itself holds what was asked for.

## Encoding

`rpicam-vid` encodes MJPEG itself, in software with libjpeg, on every Pi:
there is no camera-side JPEG to pass through as there is with a USB webcam.
So every frame costs an encode on the Pi's CPU, and `:quality` and the frame
size both matter.

# `camera`

```elixir
@type camera() :: {:index, non_neg_integer()} | {:id, String.t()}
```

Which camera to capture from: an index into `rpicam-vid --list-cameras`, or
a libcamera camera id such as
`"/base/axi/pcie@1000120000/rp1/i2c@88000/imx219@10"`.

# `error`

```elixir
@type error() ::
  {:invalid_camera, term()}
  | {:invalid_dimension, term()}
  | {:invalid_frame_rate, term()}
  | {:invalid_quality, term()}
  | {:invalid_flip, term()}
  | {:invalid_buffer_count, term()}
  | {:rpicam_vid_not_found, term()}
```

# `t`

```elixir
@type t() :: %BB.Camera.Libcamera.Command{
  buffer_count: pos_integer() | nil,
  camera: camera(),
  executable: String.t(),
  frame_rate: BB.Camera.FFmpeg.FrameRate.t(),
  height: pos_integer(),
  hflip: boolean(),
  quality: 1..100,
  vflip: boolean(),
  width: pos_integer()
}
```

# `argv`

```elixir
@spec argv(t(), non_neg_integer()) :: [String.t()]
```

The argument vector for capturing from the camera at `index`, without the
executable itself.

    iex> {:ok, command} = BB.Camera.Libcamera.Command.new(
    ...>   width: 640, height: 480, frame_rate: 30, executable: "/usr/bin/rpicam-vid")
    iex> BB.Camera.Libcamera.Command.argv(command, 0)
    ["--nopreview", "--timeout", "0", "--verbose", "0", "--camera", "0", "--codec",
     "mjpeg", "--quality", "50", "--width", "640", "--height", "480", "--framerate",
     "30.0", "--flush", "--output", "-"]

    iex> {:ok, command} = BB.Camera.Libcamera.Command.new(
    ...>   camera: 1, width: 1280, height: 720, frame_rate: {30_000, 1001}, hflip: true,
    ...>   vflip: true, buffer_count: 2, executable: "/usr/bin/rpicam-vid")
    iex> BB.Camera.Libcamera.Command.argv(command, 1)
    ["--nopreview", "--timeout", "0", "--verbose", "0", "--camera", "1", "--codec",
     "mjpeg", "--quality", "50", "--width", "1280", "--height", "720", "--framerate",
     "29.97002997002997", "--hflip", "--vflip", "--buffer-count", "2", "--flush",
     "--output", "-"]

# `new`

```elixir
@spec new(keyword()) :: {:ok, t()} | {:error, error()}
```

Build and validate a command.

## Options

- `:camera` — an index into `rpicam-vid --list-cameras`, or a libcamera
  camera id from the same list. Default `0`.
- `:width`, `:height` — any positive pixel dimensions. libcamera picks the
  sensor mode and the ISP scales to fit; what was produced is read back from
  each frame.
- `:frame_rate` — see `BB.Camera.FFmpeg.FrameRate`.
- `:quality` — the JPEG encoder's quality, 1 to 100. Default `50`, which is
  `rpicam-vid`'s own.
- `:hflip`, `:vflip` — mirror the image. Both together rotate it by 180°,
  for a camera mounted upside down. Default `false`.
- `:buffer_count` — how many frame buffers libcamera allocates. Default
  `nil`, leaving it to `rpicam-vid`. Fewer buffers use less CMA, which is
  what lets several cameras capture at once on a board with little of it.
- `:executable` — path to `rpicam-vid`. Defaults to whatever is on `$PATH`.

---

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