BB.Camera.AVF.Command (bb_camera_avf 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 name can turn into a command. The validation here is not defending against that; it is defending against arguments that are merely wrong.

Naming a camera

ffmpeg's AVFoundation input takes a camera by name or by index, and both have sharp edges that are ffmpeg's rather than this driver's:

  • An index is not stable. It is a position in the list ffmpeg prints with -list_devices true, which changes as cameras are plugged in. Indices past the last camera are screens, so a stale index can capture a display.
  • A name is matched exactly, and two identical webcams share one.
  • A name containing : cannot be used. ffmpeg splits its input on : into a video and an audio device, so it is refused here rather than silently truncated.
  • A name beginning none or default is not a name. ffmpeg compares only those prefixes, and treats them as "no video" and "the system's default camera" respectively. "default" is accepted on purpose; a name beginning none is refused.

Newer ffmpeg can select a camera by its unique ID. 9.0 cannot, so neither can this driver.

Always encoding

AVFoundation hands ffmpeg decompressed buffers, even from a USB camera that sends MJPEG over the wire. There is no passthrough path here: every frame is encoded to JPEG by ffmpeg, and :quality always matters. This is the expensive path that bb_camera_v4l treats as a fallback. On a laptop it is affordable; it is still real CPU per frame.

Frame timing

ffmpeg is told not to change the frame rate on the way out (-fps_mode passthrough). A camera that slows down in low light should produce fewer frames, not have ffmpeg duplicate them up to the requested rate and encode each copy.

Summary

Types

Where the frames come from.

t()

Functions

The argument vector, without the executable itself.

Build and validate a command.

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() | non_neg_integer()} | {:lavfi, String.t()}

Where the frames come from.

{:device, name} and {:device, index} are 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.AVF.Command{
  executable: String.t(),
  frame_rate: BB.Camera.FFmpeg.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.AVF.Command.new(
...>   device: "FaceTime HD Camera", width: 1280, height: 720,
...>   frame_rate: 30, executable: "/opt/homebrew/bin/ffmpeg")
iex> BB.Camera.AVF.Command.argv(command)
["-nostdin", "-hide_banner", "-loglevel", "error", "-f", "avfoundation",
 "-pixel_format", "nv12", "-video_size", "1280x720", "-framerate", "30",
 "-i", "FaceTime HD Camera", "-an", "-c:v", "mjpeg", "-q:v", "5",
 "-fps_mode", "passthrough", "-f", "mjpeg", "-flush_packets", "1", "pipe:1"]

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

new(opts)

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

Build and validate a command.

Options

  • :device — the camera's name as ffmpeg lists it ("FaceTime HD Camera"), "default" for the system's default camera, or its index in that list. 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. ffmpeg refuses a size the camera does not list, and prints the list when it does.
  • :frame_rate — see BB.Camera.FFmpeg.FrameRate. ffmpeg matches it against the camera's own rates to within 0.01, so 30 selects a camera's 30.000030.
  • :input_format — the pixel format to ask AVFoundation for, as ffmpeg names it. Default "nv12", which is already 4:2:0 and is the cheapest to hand the JPEG encoder. A camera that lacks it gets its first listed format instead, with a warning from ffmpeg.
  • :quality — ffmpeg's -q:v for the MJPEG encoder, 1 (best) to 31. Default 5.
  • :executable — path to ffmpeg. Defaults to whatever is on $PATH.