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

How `BB.Camera.V4L.Capture` talks to the thing producing bytes.

There is one real implementation — `BB.Camera.V4L.Backend.FFmpeg`, an
`Port` around ffmpeg — and the behaviour exists so capture can also be driven
by `BB.Camera.V4L.Backend.Stub`, which produces exactly the bytes a test
asks for, exactly when the test asks for them.

That matters more than it might look. Everything interesting about capture is
a sequence of events: a frame split across three reads, a device that stops
sending halfway through one, an ffmpeg that exits with a status nobody
expected, a consumer falling behind. Against a real camera those are
arrangeable only by luck. Against the stub each one is a function call, and
the test asserts on the result rather than on how long it waited.

## Message protocol

A backend delivers to the process that called `open/3`, shaped exactly like
the port messages it stands in for:

    {handle, {:data, binary}}
    {handle, {:exit_status, integer}}

and, for a backend that links, an exit signal from `handle` when it goes
away. The handle is opaque: a `t:port/0` for the real backend.

# `handle`

```elixir
@type handle() :: port() | reference() | pid()
```

Opaque reference to a running capture.

# `close`

```elixir
@callback close(handle()) :: :ok
```

Drop the handle without waiting. Does not guarantee the OS process is gone —
see `BB.Camera.V4L.Reaper` for the part that does.

# `open`

```elixir
@callback open(command :: BB.Camera.V4L.Command.t(), opts :: keyword()) ::
  {:ok, handle()} | {:error, term()}
```

Start the capture. Must be called from the process that will receive its
messages.

# `os_pid`

```elixir
@callback os_pid(handle()) :: pos_integer() | nil
```

The OS process id behind this handle, or `nil` when there isn't one.

# `request_stop`

```elixir
@callback request_stop(handle()) :: :ok
```

Ask the capture to shut down cleanly, if it has a way to.

---

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