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

A camera on a Linux V4L2 device, captured through ffmpeg.

Declared like any other sensor:

    topology do
      link :head do
        sensor :eye, {BB.Camera.V4L, device: "/dev/video0", width: 1280, height: 720}
      end
    end

Consumers never talk to this module. They go through `BB.Camera`, which
refcounts them and asks the driver to start capturing when the first one
arrives and to stop when the last one leaves. Two browser tabs on the same
camera produce one ffmpeg, not two.

## What it captures

MJPEG, and only MJPEG. The camera is asked for `mjpeg` and ffmpeg copies the
packets through without decoding them, so a frame reaches the BEAM as the
bytes the camera's own encoder produced: no transcode, no quality loss, and
almost no CPU regardless of resolution.

A camera with no MJPEG mode can still be used by naming the pixel format it
does have — `input_format: :yuyv422` — and ffmpeg will encode to JPEG on the
way past. That costs real CPU per frame and is a fallback rather than the
intended path.

## What it reports

Capture is confirmed to the hub on the **first whole image**, not when ffmpeg
starts. `Port.open/2` returning says only that ffmpeg exists — a missing or
busy device would otherwise announce `BeginCapture` a moment before failing.

Dimensions come from the `SOF` marker of each frame, which is what the camera
actually encoded. They are not the numbers in the DSL: V4L2 is free to hand
back the nearest size it supports, and when it does, `BB.Camera.stream_info/2`
reports the real one.

The frame rate in `stream_info` is the one that was **requested**, not the
negotiated one. This driver does not query the device's rate back and does
not parse it out of ffmpeg's console output, so claiming it as actual would
be a guess dressed up as a measurement. What the frames actually did is
measured by `BB.Camera.Hub`, which sees every one of them, and reported
separately in `BB.Message.Camera.CaptureState`.

Nothing here enumerates the device's capabilities. Any positive width and
height and any positive rational frame rate can be asked for; if the device
refuses, ffmpeg says so on the console and capture fails. Use `v4l2-ctl
--list-formats-ext` to find out what a camera supports — the answer belongs
to the camera, not to this driver.

## Frames do not go on pubsub

A robot's pubsub carries capture lifecycle only:
`BB.Message.Camera.BeginCapture` and `EndCapture`, published by the hub.
Frame bytes travel over `BB.Camera`'s bounded media interface, and never
appear in an event or an error.

## Options

See `options_schema/0`. The ones most worth knowing about are `:device`,
`:width`, `:height` and `:frame_rate`; the rest are bounds with defaults that
suit a desktop and may want lowering on a small target.

Any of them can be filled from a parameter with `param/1`, and changing that
parameter while the robot runs reconfigures the camera - see
`handle_options/2`.

## Limitations

- **Linux only.** It drives V4L2 through ffmpeg and identifies processes
  through `/proc`.
- **Timestamps are arrival times.** The raw MJPEG stream carries no
  timestamps of its own, so a frame is stamped when the read completing it
  reached the BEAM. See `BB.Camera.V4L.Capture` for what that does and does
  not mean.
- **A failed capture is not retried.** The failure is reported and capture
  ends; reopening the device is the consumer's decision, taken by subscribing
  again. A driver that quietly reopened hardware on its own would be claiming
  to capture during a window where it is not.
- **Changing an option that reaches ffmpeg restarts it**, because V4L2
  negotiates format and rate when the device is opened. Capture ends and
  begins again around the change, with the events to match; it is not a
  seamless transition and does not pretend to be.
- **ffmpeg's diagnostics go to the VM's console**, not into the error. They
  cannot be merged into the frame stream without corrupting it.

# `handle_options`

Take up options that changed while the robot was running.

Reached when a `param/1` reference in the camera's DSL options resolves to a
new value. Only a change that alters the ffmpeg invocation restarts capture:
V4L2 negotiates format and rate when the device is opened, so a new size or
rate means a new ffmpeg. Capture stops and starts again around the change; it
is not a seamless transition and does not pretend to be. An option that
doesn't reach the command line - a framer bound, say - takes effect without
disturbing the stream.

**New options this driver cannot use stop the camera.** `handle_options/2`
has no way to refuse a change and stay running, so a value that satisfies
the parameter's declared type but not this driver - a width of `-1` against
a `:pos_integer` - takes the sensor down, and down again on each restart,
because the parameter was stored before anyone was asked about it. Declare
parameters with bounds that match the options they feed.

# `stream_info`

The format this camera is declared to produce.

Pure: it is called during discovery against robots that are not running, so
it reads the options and nothing else. Options that still hold unresolved
parameter references cannot imply a format, and produce an error rather than
a guess.

---

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