Getting Started with V4L2 on Linux

V4L2 in short

V4L2 (Video4Linux2) is the Linux kernel interface that applications use to talk to video capture hardware such as USB webcams, HDMI capture cards, TV tuners and many camera sensors on embedded boards. The kernel driver exposes each device as a character node like /dev/video0. Programs open that node to query the device, choose a format and receive frames. To get started you do not need to write code. Install the command-line tools, identify your device, read its supported formats and controls, and run a test capture.

• Install the v4l-utils package with your distribution's package manager. The package name is usually v4l-utils.
• Run v4l2-ctl --list-devices to see which /dev/video nodes belong to which camera.
• Run v4l2-ctl -d /dev/video0 --list-formats-ext to see pixel formats, resolutions and frame intervals.
• Run v4l2-ctl -d /dev/video0 --list-ctrls to see adjustable settings such as brightness or exposure.
• Open the device in an application, or test a capture with v4l2-ctl, ffmpeg or GStreamer.

How V4L2 works

There are several layers between the camera and your application. The hardware connects to a kernel driver. For example, most USB webcams follow the USB Video Class and use the uvcvideo driver. The driver implements the V4L2 API, which is a set of ioctl calls on the device node. Applications use that API directly or through libraries. The libv4l library can convert some camera formats into formats that older applications understand.

Device nodes

One physical camera can create more than one node. On recent kernels, UVC cameras often expose a second node that carries metadata instead of images, so opening it will not give you video. Run v4l2-ctl -d /dev/videoN --all and look at the Device Caps section. A node that delivers images lists Video Capture. Node numbers can change between boots or when you replug a device. On systems that use udev, the symlinks under /dev/v4l/by-id and /dev/v4l/by-path give stable names that are better for scripts.

Formats, resolutions and frame rates

Pixel formats are identified by four-character codes. Two common ones are YUYV, which is uncompressed YUV 4:2:2, and MJPG, which is Motion JPEG. Each format has its own list of frame sizes, and each size has its own list of frame intervals. A camera may offer higher resolutions or frame rates only in a compressed format, because uncompressed video needs more bus bandwidth. The available combinations depend on the device and its driver. Read them from --list-formats-ext instead of assuming them from a product description.

Controls

Controls are named settings such as brightness, contrast, white balance, focus and exposure. The driver defines their names, ranges, defaults and step sizes. Some control names have changed between kernel versions. For example, older systems may show exposure_auto where newer ones show auto_exposure. Always check the names on your own system with --list-ctrls. Use --list-ctrls-menus to see the choices for menu-type controls.

Buffers and streaming

During capture, the application requests a set of buffers and queues them to the driver. The driver fills each buffer with a frame, and the application dequeues the buffer, processes it and queues it again. Memory-mapped buffers (mmap) are the most common method; user pointers and DMABUF sharing also exist. Usually only one application can stream from a node at a time. A second program typically fails with a Device or resource busy error.

Practical V4L2 tasks

Check that the camera is detected

If v4l2-ctl --list-devices shows nothing, look at recent kernel messages with dmesg. You may need sudo to run it. For a USB camera, also run lsusb to confirm the device appears on the bus. Some laptops have a physical shutter, a hardware switch or a function key that disables the camera. Check these before you troubleshoot software.

Fix permission errors

Run ls -l /dev/video* to see who owns the device nodes. They usually belong to the video group. On many desktop systems the logged-in user also gets access automatically through session access rules. If you get permission denied, add your account to the group with sudo usermod -aG video $USER, then log out and back in. Do not make the nodes world-writable. That gives every local process access to the camera.

Set a format and capture test frames

Pick a combination that appeared in the format list and apply it. For example, run v4l2-ctl -d /dev/video0 --set-fmt-video=width=1280,height=720,pixelformat=MJPG. Then capture a short burst with v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=30 --stream-to=test.raw. The output file holds the raw buffers in the selected format, not a ready-to-play video file. If streaming starts and the file grows, the driver and format work. Afterwards, run v4l2-ctl -d /dev/video0 --get-fmt-video. The driver may adjust requested values to the nearest supported ones, and this command shows what it actually applied.

Preview or record with ffmpeg and GStreamer

For a quick preview, run ffplay -f v4l2 -input_format mjpeg -video_size 1280x720 -i /dev/video0. To record to a file, run ffmpeg -f v4l2 -input_format mjpeg -video_size 1280x720 -framerate 30 -i /dev/video0 -c:v libx264 output.mkv. Use a frame rate that your camera actually lists for that format and size. With GStreamer, gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! autovideosink opens a preview window. Which encoders and plugins are available depends on how your distribution built these tools.

Adjust image controls

Set a value with a command such as v4l2-ctl -d /dev/video0 --set-ctrl=brightness=128. The value must be within the range shown by --list-ctrls. Some controls are marked inactive until you switch off the matching automatic mode. Manual exposure, for example, often has no effect while auto exposure is on. Settings may reset when the camera is replugged or the system restarts. If you need them to persist, reapply them with a small script or a udev rule.

Writing your own capture program

Most V4L2 tutorials on Linux follow the same sequence. Open the node, then call VIDIOC_QUERYCAP to confirm capture and streaming support. Call VIDIOC_ENUM_FMT to list formats and VIDIOC_S_FMT to set one, then read back the format the driver accepted. Call VIDIOC_REQBUFS to allocate buffers and map them with mmap. Queue them with VIDIOC_QBUF and start with VIDIOC_STREAMON. Then loop on VIDIOC_DQBUF and VIDIOC_QBUF to process frames, and stop with VIDIOC_STREAMOFF. The kernel's V4L2 documentation includes an example capture program, and the v4l-utils source code is a useful reference for correct API use.

Limits and related questions

V4L2, libcamera and PipeWire

Plain V4L2 works best with devices that output finished images, such as UVC webcams and capture cards. Many embedded boards and some newer laptops use MIPI camera sensors that deliver raw sensor data. These need media controller setup and image processing before you get a usable picture. libcamera handles that pipeline, and a simple V4L2 application may not get a usable image from such hardware. On desktops, sandboxed applications may reach the camera through PipeWire instead of opening /dev/video nodes directly. Support for this depends on your distribution and application versions.

Bandwidth and multiple cameras

Several cameras on the same USB controller can fail to stream at the same time, especially with uncompressed formats. Try a compressed format, a lower resolution or frame rate, or connect the cameras to ports on different controllers. A camera that works alone but fails next to another device often points to this limit rather than a driver bug.

Virtual cameras

The v4l2loopback module creates virtual video nodes. Other programs can write into them, so video call software sees the output as a camera. It is not part of the mainline kernel and must be installed separately. Depending on your setup, it may need rebuilding after kernel updates or signing when Secure Boot is enabled.

What about the webcam microphone?

V4L2 covers video only. A built-in webcam microphone usually appears as a separate USB audio device and is handled by ALSA and your sound server. Run arecord -l to check that it is detected, and choose it in the application's audio settings rather than in V4L2 tools.

Privacy and file handling

V4L2 only moves frames between the driver and the program that opened the device. Whether an application stores, uploads or shares those frames depends on that application, so verify this in its own documentation and settings. Test captures are written to the path you give, usually the current directory, so delete them when you are done. Whether the camera indicator light always turns on during capture depends on the hardware and firmware. Do not rely on it as a guarantee.