BB.Camera.V4L.Command (bb_camera_v4l v0.1.0)

Copy Markdown View Source

The ffmpeg invocation for one capture, built and validated up front.

Keeping this separate from the process that runs it means the exact argument vector for a given set of camera options is a pure function, and can be asserted on without a camera, without ffmpeg, and without starting anything. Given how much of "why is this camera not working" turns out to be a wrong flag, that is the part most worth being able to see.

No shell, ever

The vector is handed to Port.open/2 with :spawn_executable, which calls execve directly. There is no shell, so no amount of punctuation in a device path can turn into a command. The validation here is not defending against that; it is defending against arguments that are merely wrong — a device path beginning with - that ffmpeg would read as a flag, a format name that is not a format name.

Passthrough versus transcode

When the camera is asked for MJPEG, the stream is already a sequence of JPEG images, and ffmpeg copies packets through without touching them: no decode, no re-encode, no quality loss, and almost no CPU. That is the intended path and the default.

When it is asked for anything else — yuyv422 on a camera with no MJPEG mode — ffmpeg has to encode, and :quality starts to matter. The encoded path costs real CPU per frame and is the fallback, not the goal.

Summary

Types

Where the frames come from.

t()

Functions

The argument vector, without the executable itself.

The device path, or nil for a synthetic source.

Build and validate a command.

Is this command copying JPEG packets through rather than encoding them?

Types

error()

@type error() ::
  {:invalid_device, term()}
  | {:invalid_dimension, term()}
  | {:invalid_frame_rate, term()}
  | {:invalid_input_format, term()}
  | {:invalid_quality, term()}
  | {:invalid_lavfi_source, term()}
  | {:no_source, term()}
  | {:ffmpeg_not_found, term()}

source()

@type source() :: {:device, String.t()} | {:lavfi, String.t()}

Where the frames come from.

{:device, path} is a real camera. {:lavfi, filter} is one of ffmpeg's own synthetic sources, which produces a genuine MJPEG stream through the real encoder and the real pipe without any hardware — useful for proving the pipeline works before blaming the camera.

t()

@type t() :: %BB.Camera.V4L.Command{
  executable: String.t(),
  frame_rate: BB.Camera.V4L.FrameRate.t(),
  height: pos_integer(),
  input_format: String.t(),
  quality: pos_integer(),
  source: source(),
  width: pos_integer()
}

Functions

argv(command)

@spec argv(t()) :: [String.t()]

The argument vector, without the executable itself.

iex> {:ok, command} = BB.Camera.V4L.Command.new(
...>   device: "/dev/video0", width: 640, height: 480,
...>   frame_rate: 30, executable: "/usr/bin/ffmpeg")
iex> BB.Camera.V4L.Command.argv(command)
["-hide_banner", "-loglevel", "error", "-f", "v4l2", "-input_format", "mjpeg",
 "-video_size", "640x480", "-framerate", "30", "-i", "/dev/video0", "-an",
 "-c:v", "copy", "-f", "mjpeg", "-flush_packets", "1", "pipe:1"]

iex> {:ok, command} = BB.Camera.V4L.Command.new(
...>   lavfi: "testsrc2", width: 320, height: 240,
...>   frame_rate: 10, executable: "/usr/bin/ffmpeg")
iex> BB.Camera.V4L.Command.argv(command)
["-hide_banner", "-loglevel", "error", "-re", "-f", "lavfi", "-i",
 "testsrc2=size=320x240:rate=10", "-an", "-c:v", "mjpeg", "-q:v", "5",
 "-r", "10", "-f", "mjpeg", "-flush_packets", "1", "pipe:1"]

device(command)

@spec device(t()) :: String.t() | nil

The device path, or nil for a synthetic source.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, error()}

Build and validate a command.

Options

  • :device — path to the V4L2 device node, e.g. /dev/video0 or a /dev/v4l/by-id/... symlink. Required, unless :lavfi is given.
  • :lavfi — the name of an ffmpeg synthetic source such as "testsrc2", instead of a device. Only the bare filter name is accepted; the size and rate are filled in from :width, :height and :frame_rate, so there is one source of truth for them and no filtergraph to get wrong.
  • :width, :height — any positive pixel dimensions. There is no list of accepted sizes here: what a camera supports is a property of the camera, and this driver does not enumerate it. Ask for what you want; the frames report what you got.
  • :frame_rate — see BB.Camera.V4L.FrameRate.
  • :input_format — the V4L2 pixel format to request, as ffmpeg names it. Default "mjpeg", which is the passthrough path.
  • :quality — ffmpeg's -q:v for the MJPEG encoder, 1 (best) to 31. Ignored on the passthrough path. Default 5.
  • :executable — path to ffmpeg. Defaults to whatever is on $PATH.

passthrough?(command)

@spec passthrough?(t()) :: boolean()

Is this command copying JPEG packets through rather than encoding them?