BB.Camera.FFmpeg.Backend behaviour (bb_camera_ffmpeg v0.1.0)

Copy Markdown View Source

How BB.Camera.FFmpeg.Capture talks to the thing producing bytes.

There is one real implementation — BB.Camera.FFmpeg.Backend.MuonTrap, ffmpeg running under MuonTrap behind a port — and the behaviour exists so capture can also be driven by a stub that 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 camera 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 a stub each one is a function call.

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 port/0 for the real backend.

Every {:data, binary} must be acknowledged with ack/2 once it has been read. A backend may stop sending until it is.

Summary

Types

Opaque reference to a running capture.

Callbacks

Acknowledge bytes of output as read, so the backend may send more.

Drop the handle without waiting for an exit status.

Start executable with args. Must be called from the process that will receive its messages.

Ask the program to exit. The backend is responsible for making sure it does, and reports the exit as {:exit_status, status}.

Types

handle()

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

Opaque reference to a running capture.

Callbacks

ack(handle, bytes)

@callback ack(handle(), bytes :: pos_integer()) :: :ok

Acknowledge bytes of output as read, so the backend may send more.

close(handle)

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

Drop the handle without waiting for an exit status.

open(executable, args, opts)

@callback open(executable :: String.t(), args :: [String.t()], opts :: keyword()) ::
  {:ok, handle()} | {:error, term()}

Start executable with args. Must be called from the process that will receive its messages.

opts holds :stdio_window and :stop_timeout_ms from the capture, merged with the capture's :backend_opts.

request_stop(handle)

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

Ask the program to exit. The backend is responsible for making sure it does, and reports the exit as {:exit_status, status}.