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:
- 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.
- Shedding. Past
:drop_queue_lenqueued 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. - Failing. Past
:fail_queue_lenthe 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.
Summary
Functions
Returns a specification to start this module under a supervisor.
Let frames start flowing to the sink.
Start a capture.
Counters for this capture: frames delivered, frames shed, bytes discarded.
Stop the capture, giving ffmpeg a chance to release the device first.
Types
@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.
@type frame() :: %{ data: binary(), width: pos_integer(), height: pos_integer(), sequence: non_neg_integer(), monotonic_time: integer(), wall_time: integer(), metadata: map() }
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@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.
@spec start_link(keyword()) :: GenServer.on_start()
Start a capture.
Options
:command— the validatedBB.Camera.V4L.Command. Required.:sink— a 1-arity function called with eachframe/0, returning:okor{:error, reason}. Called inline, so a synchronous sink is what bounds delivery. Required.:notify— process to sendevent/0s 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. Default0.:max_frame_bytes— passed toBB.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— defaultsBB.Camera.V4L.Backend.FFmpegand[].:reaper— theBB.Camera.V4L.Reaperto register the OS process with.
@spec stats(GenServer.server()) :: map()
Counters for this capture: frames delivered, frames shed, bytes discarded.
@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.