# `BB.Camera.FFmpeg.Framer`
[🔗](https://github.com/beam-bots/bb_camera_ffmpeg/blob/main/lib/bb/camera/ffmpeg/framer.ex#L5)

Turns the byte stream coming out of a capture into whole JPEG frames.

A pipe hands over whatever happened to be readable, so a frame arrives across
several reads and a read routinely holds the tail of one frame and the head
of the next. The framer owns that buffer, hands back the frames that have
completed, and resumes its scan where it left off rather than re-reading the
bytes it has already walked — see `BB.Camera.FFmpeg.Jpeg` for the scanner.

It is a plain struct with no process of its own, so it can be driven straight
from a test with a list of byte chunks.

## Bounds

Framing is where a hostile or broken stream turns into unbounded memory: a
frame whose `EOI` never arrives would otherwise grow the buffer until the VM
dies. `max_frame_bytes` is the hard stop, and it applies to frames that
complete as much as to frames that do not — a single oversized image
delivered whole in one read is refused rather than passed on because it
happened to arrive in one piece.

An image that completes but carries no frame header is discarded too. It has
no dimensions to report, and the driver's whole claim to know what a frame
actually is rests on having read them out of it.

That makes the retained buffer bounded by `max_frame_bytes` plus whatever one
read delivered, regardless of what the stream does. The same resynchronisation
handles a malformed frame and leading garbage, so there is one recovery path
rather than three.

Note that this bounds the *framer*. The mailbox of the process reading the
capture is bounded separately, by the flow-control window described in
`BB.Camera.FFmpeg.Capture`.

## Reporting

Every discard produces an event in the returned list, rather than a log line,
so that the caller decides how to report it: a camera quietly dropping half
its frames should be visible to an operator. Events never carry frame bytes,
only counts and a reason.

# `event`

```elixir
@type event() ::
  {:discarded, bytes :: pos_integer(),
   reason :: :oversized | :malformed | :desynchronised}
```

Something was thrown away, and why.

- `:oversized` — no end-of-image marker inside `max_frame_bytes`.
- `:malformed` — the bytes are not a well-formed JPEG.
- `:desynchronised` — the stream did not begin at a start-of-image marker.

# `frame`

```elixir
@type frame() :: {data :: binary(), info :: BB.Camera.FFmpeg.Jpeg.info()}
```

A complete image and what its own frame header says about it.

# `t`

```elixir
@type t() :: %BB.Camera.FFmpeg.Framer{
  buffer: binary(),
  info: BB.Camera.FFmpeg.Jpeg.info() | nil,
  max_frame_bytes: pos_integer(),
  scan: BB.Camera.FFmpeg.Jpeg.state() | nil
}
```

# `buffered`

```elixir
@spec buffered(t()) :: non_neg_integer()
```

How many bytes the framer is holding on to.

# `new`

```elixir
@spec new(keyword()) :: t()
```

Build a framer.

## Options

- `:max_frame_bytes` — the largest image to accept, in bytes. Default
  4194304. That default is a spike bound, not a measured
  one: MJPEG frame sizes depend on resolution, quality and scene detail, and a
  high-quality 4K frame can exceed it. Raise it if the camera's frames are
  legitimately bigger; lower it on a memory-constrained target, where it also
  caps what a broken stream can make the framer hold.

# `push`

```elixir
@spec push(t(), binary()) :: {[frame()], [event()], t()}
```

Append `bytes` to the buffer and extract whatever that completes.

Returns the frames in arrival order, any discard events, and the framer to
use for the next read.

---

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