# `BB.Camera.AVF.Command`
[🔗](https://github.com/beam-bots/bb_camera_avf/blob/main/lib/bb/camera/avf/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
name can turn into a command. The validation here is not defending against
that; it is defending against arguments that are merely *wrong*.

## Naming a camera

ffmpeg's AVFoundation input takes a camera by name or by index, and both
have sharp edges that are ffmpeg's rather than this driver's:

- **An index is not stable.** It is a position in the list ffmpeg prints with
  `-list_devices true`, which changes as cameras are plugged in. Indices past
  the last camera are *screens*, so a stale index can capture a display.
- **A name is matched exactly**, and two identical webcams share one.
- **A name containing `:` cannot be used.** ffmpeg splits its input on `:`
  into a video and an audio device, so it is refused here rather than
  silently truncated.
- **A name beginning `none` or `default` is not a name.** ffmpeg compares
  only those prefixes, and treats them as "no video" and "the system's
  default camera" respectively. `"default"` is accepted on purpose; a name
  beginning `none` is refused.

Newer ffmpeg can select a camera by its unique ID. 9.0 cannot, so neither
can this driver.

## Always encoding

AVFoundation hands ffmpeg decompressed buffers, even from a USB camera that
sends MJPEG over the wire. There is no passthrough path here: every frame is
encoded to JPEG by ffmpeg, and `:quality` always matters. This is the
expensive path that `bb_camera_v4l` treats as a fallback. On a laptop it is
affordable; it is still real CPU per frame.

## Frame timing

ffmpeg is told not to change the frame rate on the way out
(`-fps_mode passthrough`). A camera that slows down in low light should
produce fewer frames, not have ffmpeg duplicate them up to the requested
rate and encode each copy.

# `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() | non_neg_integer()} | {:lavfi, String.t()}
```

Where the frames come from.

`{:device, name}` and `{:device, index}` are 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.AVF.Command{
  executable: String.t(),
  frame_rate: BB.Camera.FFmpeg.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.AVF.Command.new(
    ...>   device: "FaceTime HD Camera", width: 1280, height: 720,
    ...>   frame_rate: 30, executable: "/opt/homebrew/bin/ffmpeg")
    iex> BB.Camera.AVF.Command.argv(command)
    ["-nostdin", "-hide_banner", "-loglevel", "error", "-f", "avfoundation",
     "-pixel_format", "nv12", "-video_size", "1280x720", "-framerate", "30",
     "-i", "FaceTime HD Camera", "-an", "-c:v", "mjpeg", "-q:v", "5",
     "-fps_mode", "passthrough", "-f", "mjpeg", "-flush_packets", "1", "pipe:1"]

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

# `new`

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

Build and validate a command.

## Options

- `:device` — the camera's name as ffmpeg lists it (`"FaceTime HD Camera"`),
  `"default"` for the system's default camera, or its index in that list.
  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. ffmpeg refuses a size
  the camera does not list, and prints the list when it does.
- `:frame_rate` — see `BB.Camera.FFmpeg.FrameRate`. ffmpeg matches it against
  the camera's own rates to within 0.01, so `30` selects a camera's
  `30.000030`.
- `:input_format` — the pixel format to ask AVFoundation for, as ffmpeg names
  it. Default `"nv12"`, which is already 4:2:0 and is the cheapest to hand
  the JPEG encoder. A camera that lacks it gets its first listed format
  instead, with a warning from ffmpeg.
- `:quality` — ffmpeg's `-q:v` for the MJPEG encoder, 1 (best) to 31.
  Default `5`.
- `:executable` — path to ffmpeg. Defaults to whatever is on `$PATH`.

---

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