v4l2loopback - ArchWiki

Jump to content
From ArchWiki

Related articles

- Webcam setup

From the project repository:

  v4l2loopback - a kernel module to create V4L2 loopback devices
  This module allows you to create "virtual video devices". Normal (v4l2) applications will read these devices as if they were ordinary video devices, but the video will not be read from e.g. a capture card but instead it is generated by another application.

## Installation

Install the v4l2loopback-dkms package and the headers for the target kernel/kernels (see Dynamic Kernel Module Support#Installation). For example, for the default linux kernel this would be linux-headers. Other kernels have their own respective headers packages.

Command line utilities are provided by v4l2loopback-utils and v4l-utils.

Many of the use case examples in this article also use ffmpeg.

## Loading the kernel module

The `v4l2loopback` kernel module can be loaded via the Dynamic Kernel Module Support:

    # modprobe v4l2loopback

`v4l2-ctl` can be used to list all video devices, where the new `v4l2loopback` device should appear:

    $ v4l2-ctl --list-devices

`v4l2loopback` can be loaded with various options for device creation:

    # modprobe v4l2loopback video_nr=9 card_label=Video-Loopback exclusive_caps=1

This should create `/dev/video9` as a loopback device. `exclusive_caps=1` is neccessary for some Chromium/WebRTC based application like jitsi-meet-desktop-binAUR or zoomAUR. More options can be found in the official documentation.

If the module is already loaded, the above command has likely no effect. The module first has to be unloaded, before loaded again:

    # modprobe -r v4l2loopback

See Kernel module#Manual module handling for more details.

Tip: It is also possible to manage the devices dynamically without reloading the kernel module using `v4l2loopback-ctl` as described in the official documentation.

It is possible to create multiple loopback devices by using the `devices` argument. Options for the every device are specified by using a comma. The following command creates three loopback devices, `/dev/video8`, `/dev/video9` and the first available `/dev/videoX`, all with `exclusive_caps` enabled.

    # modprobe v4l2loopback devices=3 video_nr=8,9 exclusive_caps=1,1,1 card_label="Loopback-1,Loopback-2,Loopback-3"

Restarting the system will unload the module, but is possible to load the modules automatically at boot with custom device options, which is useful if one loopback device is used for an internal webcam. See Kernel module#Automatic module loading and the official documentation for details.

## Viewing a v4l2loopback video feed

Note: `v4l2loopback` video devices only output video, if there is a stream piped into them like the examples in #Use cases do. Otherwise many applications won't even detect the video devices.

A loopback video device at `/dev/video0` can be viewed for testing with any of the following: `ffplay` (part of ffmpeg), mpv, or `gst-launch` (part of gstreamer):

    $ ffplay /dev/video0
    $ mpv av://v4l2:/dev/video0
    $ gst-launch-1.0 -v v4l2src device=/dev/video0 ! glimagesink

As noted in #Loading the kernel module, when `exclusive_caps=1` is used Chromium and applications like jitsi-meet-desktop-binAUR and zoomAUR should be able to use the loopback device as a virtual webcam, while a video stream is piped into them. In a browser the virtual webcam can be tested on webcamtests.com.

See also Webcam setup#Applications.

Tip: If you pipe a video stream to the video device and your application doesn't detect it, try it with and without `exclusive_caps=1`.
Note:

- Various other issues with Firefox have been reported.
- It has been reported, that skypeforlinux-stable-binAUR detects the virtual video device, but outputs a blank screen.

## Use cases

Note: Because v4l2loopback devices can be handled as v4l2 devices, numerous applications can interact with them. For more information about v4l2 devices see the Webcam setup article.

Generally, FFmpeg is very convenient in combination with v4l2loopback, because it can transcode various input streams to the widely supported yuv420p pixel format and pipe the output to a v4l2loopback device by using the `ffmpeg` arguments `-vf format=yuv420p -f v4l2`. See the examples below in this article.

FFmpeg can also use the v4l2loopback device as an input stream. See FFmpeg#Recording webcam.

GStreamer can also use v4l2loopback devices as sources and sinks.

Further examples can be found at the official v4l2loopback wiki.

Tip: PipeWire is an upcoming new low-level multimedia framework, which can also do some things v4l2loopback is used for.

### Screen casting

Below are examples how to implement screen sharing by streaming the screen to a v4l2 loopback device, which can be used as a virtual webcam.

#### Casting X11 using FFmpeg

Note: This requires #Loading the kernel module with `exclusive_caps=1` and assumes the created video device is `/dev/video0`.

FFmpeg can be used to select a region on a X11 display and then stream it to a v4l2 loopback device:

    $ ffmpeg -f x11grab -select_region 1 -show_region 1 -framerate 25 -i $DISPLAY -vf format=yuv420p -f v4l2 /dev/video0

See the x11grab docs for a description of all the arguments.

#### Casting Wayland using wf-recorder

Note:

- See also PipeWire#WebRTC screen sharing for a different approach to this.
- This requires #Loading the kernel module with `exclusive_caps=1` and assumes the created video device is `/dev/video0`.

Install wf-recorder (or wf-recorder-gitAUR). To start recording the screen with `wf-recorder` and stream it to a v4l2 loopback device use:

    $ wf-recorder --muxer=v4l2 --codec=rawvideo --file=/dev/video0 -x yuv420p

If you encounter `Unknown V4L2 pixel format equivalent for rgb0` run `wf-recorder` with `--force-yuv` or `-t` to force conversion of the data to yuv format, before sending it to the GPU. [1]

##### Screen casting only a specific region

Warning: This method does not involve a proper implementation of individual application sharing as the region being shared will not change after resizing any windows.

As explained above, `wf-recorder` is able to record only a portion of the screen by first selecting a region with slurp. To use this functionality for sharing a specific region/application window through a virtual video device, start recording the screen with the following modified command:

    $ wf-recorder -g "$(slurp)" --muxer=v4l2 --codec=rawvideo --file=/dev/video0 -x yuv420p

### Using a photo camera as webcam with gPhoto

Note: This requires #Loading the kernel module with `exclusive_caps=1` and assumes the created video device is `/dev/video0`.

If gPhoto is installed and working with your camera, you can use `gphoto2` and FFmpeg to pipe the liveview stream of the camera to a v4l2 loopback device:

    $ gphoto2 --stdout --capture-movie | ffmpeg -i - -vf format=yuv420p -f v4l2 /dev/video0

For troubleshooting refer to gPhoto#Troubleshooting. This should work with all cameras, which have the liveview functionality listed on the official gPhoto website.

### Using a network stream as webcam

Note: This requires #Loading the kernel module with `exclusive_caps=1` and assumes the created video device is `/dev/video0`.

FFmpeg can be used to capture a network stream and pipe it to a v4l2 loopback device:

    $ ffmpeg -i http://ip_address:port/video -vf format=yuv420p -f v4l2 /dev/video0

#### Using an Android device as webcam

On Android IP Webcam can be used to broadcast a network video stream. Then the command above can be used to pipe it into a v4l2 loopback device and use it like a webcam. IP Webcam defaults to port 8080.

Depending on the network connection, the network stream over WiFi might have a lot of latency and could be stuttering. If you have Android Debug Bridge configured with your computer and the Android device, it is possible to tunnel the stream over a USB cable using `adb forward`, which provides a more stable connection:

    $ adb wait-for-usb-device && adb forward tcp:8080 tcp:8080 && ffmpeg -i http://127.0.0.1:8080/video -vf format=yuv420p -f v4l2 /dev/video0

Tip: An other option is Iriun with iriunwebcam-binAUR.

## Troubleshooting

### Firefox

If Firefox is unable to read the video stream and prints a message like `AbortError: Starting video failed`, try preloading v4l2compat.so:

    $ LD_PRELOAD=/usr/lib/v4l1compat.so firefox

### ioctl(VIDIOC_G_FMT)

If you get a `ioctl(VIDIOC_G_FMT)` error, when trying to use the video device with `ffmpeg`, try unloading and reloading the kernel module. [2]

## See also

- v4l2loopback repository
- v4l2loopback wiki

Categories:

- Video
- Digital imaging