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
noneordefaultis 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 beginningnoneis 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
@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.
@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
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"]
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:lavfiis 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,:heightand: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— seeBB.Camera.FFmpeg.FrameRate. ffmpeg matches it against the camera's own rates to within 0.01, so30selects a camera's30.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:vfor the MJPEG encoder, 1 (best) to 31. Default5.:executable— path to ffmpeg. Defaults to whatever is on$PATH.