v4l2loopback-ctl

Control v4l2 loopback devices

TLDR

Create a new loopback device with a custom name

$ sudo v4l2loopback-ctl add -n "[My Virtual Camera]"

List all v4l2 loopback devices

$ v4l2loopback-ctl list

Delete a loopback device

$ sudo v4l2loopback-ctl delete /dev/video[0]

Query a device for its properties

$ v4l2loopback-ctl query /dev/video[0]

Set the frame rate of a device

$ v4l2loopback-ctl set-fps /dev/video[0] [30]

Set the format capabilities of a device

$ v4l2loopback-ctl set-caps /dev/video[0] "[UYVY:1024x768@30/1]"

Set a timeout image displayed when no producer is active

$ v4l2loopback-ctl set-timeout-image -t [3000] /dev/video[0] [path/to/image.png]

v4l2loopback-ctl [options]v4l2loopback-ctl add [options] [outputdevice [capturedevice]]v4l2loopback-ctl delete devicev4l2loopback-ctl list [options]v4l2loopback-ctl query [options] devicev4l2loopback-ctl set-fps device fpsv4l2loopback-ctl set-caps device capsv4l2loopback-ctl set-timeout-image [options] device image

DESCRIPTION

v4l2loopback-ctl is a utility for managing virtual video loopback devices created by the v4l2loopback kernel module. These virtual devices act as pipes: one application feeds video frames into the device (producer), and another application reads them (consumer), enabling use cases like virtual webcams, screen sharing to video conferencing tools, and video processing pipelines.The tool uses a verb-based interface with commands for creating, deleting, listing, and querying loopback devices, as well as configuring their frame rate, format capabilities, and fallback timeout images.

PARAMETERS

-h, -?, --help

Display help information and exit.

-v, --version

Show version and exit.

ADD OPTIONS

-b num, --buffers num

Number of buffers in the queue.

-w w, --max-width w

Maximum frame width.

-h h, --max-height h

Maximum frame height.

--min-width w

Minimum frame width.

--min-height h

Minimum frame height.

-n name, --name name

Device name shown in applications.

-o num, --max-openers num

Maximum number of concurrent openers.

-x x, --exclusive-caps x

Announce exclusive capabilities (0 or 1).

SET-CAPS FORMAT

The caps argument uses the format '_fourcc_:_width_x_height_@_fps_', for example 'UYVY:1024x768@60/1'. Use 'any' to unset current caps.

SET-TIMEOUT-IMAGE OPTIONS

-t timeout, --timeout timeout

Timeout duration in milliseconds before the fallback image is displayed.

CAVEATS

Requires the v4l2loopback kernel module to be loaded. Creating and deleting devices typically requires root privileges. The set-caps format string must exactly match the expected fourcc:WxH@fps pattern. Not all applications correctly detect or use loopback devices, especially when exclusive capabilities are not set.

HISTORY

The v4l2loopback project was created by IOhannes m zmölnig to provide virtual video devices on Linux using the Video4Linux2 (V4L2) framework. It gained widespread adoption as a way to create virtual webcams, particularly popular during the rise of video conferencing. The v4l2loopback-ctl utility was added to provide a user-friendly interface for managing these devices without directly manipulating kernel module parameters.