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

One running capture: the ffmpeg process, the framer, and the bounds.

There is exactly one of these per camera while capture is running, and none
when it is not. Consumers never reach it — they talk to `BB.Camera.Hub`,
which refcounts them and tells the driver when to start and stop. Two browser
tabs on the same camera produce one of these, not two.

It is a process of its own rather than part of the sensor so that the sensor
stays answerable while a frame delivery is in flight. `BB.Camera.Hub.deliver/2`
is a synchronous call by design, and a sensor blocked inside one would not be
reading the `stop_capture` message asking it to shut down.

## Bounding ingress, and what that does not mean

Erlang ports have no flow control: a port reads its file descriptor as fast
as the OS will give it up and posts every read to the owner's mailbox,
whether or not the owner is keeping up. `Port.open/2`'s `busy_limits_msgq`
does not change that — on OTP 29 it is accepted and ignored for port-to-owner
data, and a `cat /dev/zero` port will queue gigabytes in seconds with it set.
So what bounds exist are built here:

1. **A drain-only owner.** This process frames bytes and hands frames on. It
   does no decoding, no encoding and no consumer work, so it falls behind
   only when something downstream is slow.
2. **Shedding.** Past `:drop_queue_len` queued messages, frames are framed
   but not delivered: the pipeline is behind, the hub keeps only the newest
   frame anyway, and a frame that would be superseded before anyone could see
   it is not worth a blocking call. This is self-balancing — the queue drains
   while frames are shed, delivery resumes below the threshold, and a
   permanently slow consumer settles at the rate it can take rather than
   starving.
3. **Failing.** Past `:fail_queue_len` the backlog is not transient and the
   capture stops with `{:shutdown, :overload}`.

The mailbox depth is checked on **every read**, before framing, because a
producer emitting bytes that never complete a frame would otherwise never
reach the check.

**This is fail-fast, not a memory bound.** `:fail_queue_len` limits the
number of queued reads this process has *observed*, and it can only observe
them when it is scheduled. A process starved of CPU accumulates messages
without running the check, and nothing here can stop that — the port keeps
reading regardless. Nor is `:max_frame_bytes` a byte-rate cap: it bounds one
image, not what a malfunctioning producer can write per second. What these
limits buy is that a sustained overload is noticed and reported rather than
silently eating memory. They do not make the memory ceiling a number you can
calculate in advance.

Within a single read, only the newest frame is delivered and the rest are
counted as dropped, for the same reason — the hub holds one frame, so the
others would be overwritten before any consumer saw them.

## Timestamps, honestly

A frame is stamped when the read that completed it arrived in this process.
That is **not** the moment the sensor was exposed. Between the two sit the
camera's own pipeline, the USB transfer, V4L2's buffers, ffmpeg's muxer, the
pipe, and the BEAM's scheduler.

Nothing better is available on this path: the raw MJPEG stream ffmpeg writes
is a bare concatenation of images with no container and therefore no
timestamps at all. Carrying real capture times would mean reading a container
format out of ffmpeg and demuxing it, which this spike does not do. The
stamps are monotonic, they are in arrival order, and the error between them
and exposure is roughly constant — so inter-frame intervals are meaningful
even though absolute times are offset.

# `event`

```elixir
@type event() ::
  {:exited, status :: integer()}
  | {:discarded, bytes :: pos_integer(), reason :: atom()}
  | {:dropped, frames :: pos_integer()}
  | {:overloaded, queue_len :: pos_integer()}
  | {:sink_error, term()}
  | {:ready, BB.Camera.V4L.Jpeg.info()}
```

What capture tells its owner about, beyond the frames themselves.

# `frame`

```elixir
@type frame() :: %{
  data: binary(),
  width: pos_integer(),
  height: pos_integer(),
  sequence: non_neg_integer(),
  monotonic_time: integer(),
  wall_time: integer(),
  metadata: map()
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `go`

```elixir
@spec go(GenServer.server()) :: :ok
```

Let frames start flowing to the sink.

A capture holds its frames until this is called, so that the hub cannot be
handed a frame before the driver has confirmed to it that capture started —
it would refuse one, and the frame would be lost for no reason. Opening the
device and confirming it are two steps in two processes, and this closes the
gap between them without either having to wait on the other.

Nothing is dropped in the meantime beyond what the newest-frame-wins policy
would have dropped anyway: the most recent frame is held and delivered here.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start a capture.

## Options

- `:command` — the validated `BB.Camera.V4L.Command`. Required.
- `:sink` — a 1-arity function called with each `t:frame/0`, returning
  `:ok` or `{:error, reason}`. Called inline, so a synchronous sink is what
  bounds delivery. Required.
- `:notify` — process to send `t:event/0`s to, tagged
  `{:bb_camera_v4l, capture_pid, event}`. Default the starting process.
- `:sequence_start` — first sequence number. A camera that restarts its
  capture must keep counting up, because the hub rejects a sequence that does
  not strictly increase. Default `0`.
- `:max_frame_bytes` — passed to `BB.Camera.V4L.Framer`.
- `:drop_queue_len` — shed frames above this mailbox depth. Default
  8.
- `:fail_queue_len` — stop above this mailbox depth. Default
  256.
- `:stop_timeout_ms` — how long ffmpeg gets to exit on its own after being
  asked politely, before the reaper signals it. Default
  2000.
- `:backend`, `:backend_opts` — defaults `BB.Camera.V4L.Backend.FFmpeg`
  and `[]`.
- `:reaper` — the `BB.Camera.V4L.Reaper` to register the OS process with.

# `stats`

```elixir
@spec stats(GenServer.server()) :: map()
```

Counters for this capture: frames delivered, frames shed, bytes discarded.

# `stop`

```elixir
@spec stop(GenServer.server()) :: :ok
```

Stop the capture, giving ffmpeg a chance to release the device first.

Asynchronous, because the caller is the sensor and the sensor has a hub
waiting to be told that capture has ended. Blocking it for however long
ffmpeg takes to notice would hold up that answer, and the teardown is
guaranteed by `BB.Camera.V4L.Reaper` rather than by anybody waiting for it.

`Process.monitor/1` the capture first when you need to know it has finished.

---

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