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

The ffmpeg 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 ffmpeg, and without starting anything.
Given how much of "why is this camera not working" turns out to be a wrong
flag, that is the part most worth being able to see.

## No shell, ever

The vector is handed to `Port.open/2` with `:spawn_executable`, which calls
`execve` directly. There is no shell, so no amount of punctuation in a device
path can turn into a command. The validation here is not defending against
that; it is defending against arguments that are merely *wrong* — a device
path beginning with `-` that ffmpeg would read as a flag, a format name that
is not a format name.

## Passthrough versus transcode

When the camera is asked for MJPEG, the stream is already a sequence of JPEG
images, and ffmpeg copies packets through without touching them: no decode,
no re-encode, no quality loss, and almost no CPU. That is the intended path
and the default.

When it is asked for anything else — `yuyv422` on a camera with no MJPEG
mode — ffmpeg has to encode, and `:quality` starts to matter. The encoded
path costs real CPU per frame and is the fallback, not the goal.

# `error`

```elixir
@type error() ::
  {:invalid_device, term()}
  | {:invalid_dimension, term()}
  | {:invalid_frame_rate, term()}
  | {:invalid_input_format, term()}
  | {:invalid_quality, term()}
  | {:invalid_lavfi_source, term()}
  | {:no_source, term()}
  | {:ffmpeg_not_found, term()}
```

# `source`

```elixir
@type source() :: {:device, String.t()} | {:lavfi, String.t()}
```

Where the frames come from.

`{:device, path}` is a real camera. `{:lavfi, filter}` is one of ffmpeg's own
synthetic sources, which produces a genuine MJPEG stream through the real
encoder and the real pipe without any hardware — useful for proving the
pipeline works before blaming the camera.

# `t`

```elixir
@type t() :: %BB.Camera.V4L.Command{
  executable: String.t(),
  frame_rate: BB.Camera.V4L.FrameRate.t(),
  height: pos_integer(),
  input_format: String.t(),
  quality: pos_integer(),
  source: source(),
  width: pos_integer()
}
```

# `argv`

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

The argument vector, without the executable itself.

    iex> {:ok, command} = BB.Camera.V4L.Command.new(
    ...>   device: "/dev/video0", width: 640, height: 480,
    ...>   frame_rate: 30, executable: "/usr/bin/ffmpeg")
    iex> BB.Camera.V4L.Command.argv(command)
    ["-hide_banner", "-loglevel", "error", "-f", "v4l2", "-input_format", "mjpeg",
     "-video_size", "640x480", "-framerate", "30", "-i", "/dev/video0", "-an",
     "-c:v", "copy", "-f", "mjpeg", "-flush_packets", "1", "pipe:1"]

    iex> {:ok, command} = BB.Camera.V4L.Command.new(
    ...>   lavfi: "testsrc2", width: 320, height: 240,
    ...>   frame_rate: 10, executable: "/usr/bin/ffmpeg")
    iex> BB.Camera.V4L.Command.argv(command)
    ["-hide_banner", "-loglevel", "error", "-re", "-f", "lavfi", "-i",
     "testsrc2=size=320x240:rate=10", "-an", "-c:v", "mjpeg", "-q:v", "5",
     "-r", "10", "-f", "mjpeg", "-flush_packets", "1", "pipe:1"]

# `device`

```elixir
@spec device(t()) :: String.t() | nil
```

The device path, or `nil` for a synthetic source.

# `new`

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

Build and validate a command.

## Options

- `:device` — path to the V4L2 device node, e.g. `/dev/video0` or a
  `/dev/v4l/by-id/...` symlink. Required, unless `:lavfi` is given.
- `:lavfi` — the name of an ffmpeg synthetic source such as `"testsrc2"`,
  instead of a device. Only the bare filter name is accepted; the size and
  rate are filled in from `:width`, `:height` and `:frame_rate`, so there is
  one source of truth for them and no filtergraph to get wrong.
- `:width`, `:height` — any positive pixel dimensions. There is no list of
  accepted sizes here: what a camera supports is a property of the camera,
  and this driver does not enumerate it. Ask for what you want; the frames
  report what you got.
- `:frame_rate` — see `BB.Camera.V4L.FrameRate`.
- `:input_format` — the V4L2 pixel format to request, as ffmpeg names it.
  Default `"mjpeg"`, which is the passthrough path.
- `:quality` — ffmpeg's `-q:v` for the MJPEG encoder, 1 (best) to 31.
  Ignored on the passthrough path. Default `5`.
- `:executable` — path to ffmpeg. Defaults to whatever is on `$PATH`.

# `passthrough?`

```elixir
@spec passthrough?(t()) :: boolean()
```

Is this command copying JPEG packets through rather than encoding them?

---

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