How to Use the Command 'v4l2-ctl' (with Examples)

The v4l2-ctl command is a versatile tool used for controlling video devices on Linux systems. This command can list video devices, query their formats and capabilities, capture video frames, and control device settings. It utilizes the video4linux2 (V4L2) API, which is widely used for webcam and other video device control on Linux. This article provides detailed use cases with examples on how to effectively employ v4l2-ctl to manage video device settings and operations.

Use Case 1: List All Video Devices

Code:

v4l2-ctl --list-devices

Motivation: Understanding and identifying all the video devices connected to your Linux system is crucial, especially when multiple cameras or video capture cards are attached. By listing all video devices, you gain a clear overview of each device’s availability and can select the appropriate one for your specific video capture or control task.

Explanation:

• --list-devices: This option tells v4l2-ctl to display all the video devices currently connected to the system, including their device paths. It provides a snapshot of available video interfaces.

Example Output:

USB Camera (Logitech): /dev/video0
Built-in Webcam: /dev/video1
Capture Card: /dev/video2

Use Case 2: List Supported Video Formats and Resolutions of Default Video Device

Code:

v4l2-ctl --list-formats-ext

Motivation: Knowing the supported video formats and resolutions of a video device is essential for ensuring compatible recording and streaming configurations. This command will provide the necessary information to configure your video application correctly and optimize video quality and storage.

Explanation:

• --list-formats-ext: This option queries the default video device (typically /dev/video0) for its supported pixel formats and frame sizes or resolutions.

Example Output:

ioctl: VIDIOC_ENUM_FMT
    Type: Video Capture

    [0]: 'MJPG' (Motion-JPEG, compressed)
        Size: Discrete 1280x720
        Size: Discrete 640x480
    [1]: 'YUYV' (YUYV 4:2:2)
        Size: Discrete 640x480

Use Case 3: List Supported Video Formats and Resolutions of a Specific Video Device

Code:

v4l2-ctl --list-formats-ext --device path/to/video_device

Motivation: In scenarios where multiple video devices are attached to a system, you may need to extract format and resolution details of a specific device rather than the default one. This command allows customization and specificity in device selection.

Explanation:

• --list-formats-ext: As before, this option queries the device for its formats and resolutions.
• --device path/to/video_device: This specifies the exact device path of the video device you’re interested in examining.

Example Output:

ioctl: VIDIOC_ENUM_FMT
    Type: Video Capture

    [0]: 'H264' (H.264, compressed)
        Size: Discrete 1920x1080
        Size: Discrete 1280x720
    [1]: 'RGB3' (24-bit RGB)
        Size: Discrete 800x600

Use Case 4: Get All Details of a Video Device

Code:

v4l2-ctl --all --device path/to/video_device

Motivation: To diagnose any issues or fully understand the capabilities of a specific video device, it is helpful to obtain a comprehensive summary of all its properties and settings. This detailed information can be critical for developers and support engineers.

Explanation:

• --all: This option instructs v4l2-ctl to print all available information about the specified video device.
• --device path/to/video_device: Specifies the device path for which details are to be printed.

Example Output:

Driver Info:
    Driver name      : uvcvideo
    Card type        : USB Video
    Bus info         : usb-0000:00:14.0-1
    Driver version   : 4.19.118

Video input:
    Name             : Camera 1
    Type             : Camera

Use Case 5: Capture a JPEG Photo with a Specific Resolution from Video Device

Code:

v4l2-ctl --device path/to/video_device --set-fmt-video=width=width,height=height,pixelformat=MJPG --stream-mmap --stream-to=path/to/output.jpg --stream-count=1

Motivation: Capturing high-quality still images from a video device at a specified resolution is crucial for various applications, such as surveillance, content creation, or documentation purposes. This command empowers users to acquire precise image snapshots.

Explanation:

• --device path/to/video_device: Identifies the video device for photo capture.
• --set-fmt-video=width=width,height=height,pixelformat=MJPG: Sets the video format for the capture operation, defining the resolution and image format (MJPG for JPEG).
• --stream-mmap: Specifies the use of memory mapping for efficient image streaming.
• --stream-to=path/to/output.jpg: Sets the output path for the captured JPEG photo.
• --stream-count=1: Captures only one frame to obtain a single photo.

Example Output:

Captured 1 frame to 'path/to/output.jpg'

Use Case 6: Capture a Raw Video Stream from Video Device

Code:

v4l2-ctl --device path/to/video_device --set-fmt-video=width=width,height=height,pixelformat=format --stream-mmap --stream-to=path/to/output --stream-count=number_of_frames_to_capture

Motivation: For video processing tasks or custom applications, capturing raw video streams directly from a device is essential. This operation allows further processing, analysis, or storage of recorded video data.

Explanation:

• --device path/to/video_device: Specifies the device from which to capture the video stream.
• --set-fmt-video=width=width,height=height,pixelformat=format: Defines the resolution and pixel format for video capture.
• --stream-mmap: Utilizes memory mapping for efficient data streaming.
• --stream-to=path/to/output: Designates the output file or location to save the captured video stream.
• --stream-count=number_of_frames_to_capture: Limits the number of frames to capture for the video stream.

Example Output:

Captured 100 frames to 'path/to/output'

Use Case 7: List All Video Device’s Controls and Their Values

Code:

v4l2-ctl --list-ctrls --device path/to/video_device

Motivation: Listing the control settings and values of a video device allows users to understand and potentially modify the device’s operational parameters, such as brightness, contrast, or other image properties. This information is crucial for fine-tuning video output to meet specific requirements.

Explanation:

• --list-ctrls: Requests a list of all the control parameters available on the specified video device.
• --device path/to/video_device: Identifies the device whose controls are to be listed.

Example Output:

Brightness (int)    : min=0 max=255 step=1 default=128 value=128
Contrast (int)      : min=0 max=63 step=1 default=32 value=32

Use Case 8: Set the Value of a Video Device Control

Code:

v4l2-ctl --device path/to/video_device --set-ctrl=control_name=value

Motivation: Adjusting device control values is necessary for optimizing video capture conditions, such as altering exposure settings in varying lighting conditions or tweaking color settings for desired aesthetic effects.

Explanation:

• --device path/to/video_device: Determines the specific video device you wish to control.
• --set-ctrl=control_name=value: Sets a specific control to a new value, where control_name is the name of the control (e.g., brightness) and value is the desired setting.

Example Output:

Setting control 'Brightness' to 150

Conclusion:

The v4l2-ctl command is a powerful tool for managing and controlling video devices on Linux systems. By understanding and leveraging its various options and functionalities, users can effectively interact with, configure, and utilize video capture devices for diverse applications ranging from simple image captures to complex video streaming solutions.