Jump to content

# v4l2loopback

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, for example, a capture card; 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 necessary for some Chromium/WebRTC based application like jitsi-meet-desktop-binAUR or zoomAUR. This will enable `exclusive_caps` mode that only reports CAPTURE/OUTPUT capabilities exclusively. The newly created device will announce OUTPUT capabilities only (so ordinary webcam applications (including Chrome) will not see it). As soon as you have attached a producer to the device, it will start announcing CAPTURE capabilities only (so applications that refuse to open devices that have other capabilities apart from capturing can open it too). 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.

You can create multiple loopback devices by using the `devices` argument, and specify options for each device separated by commas. 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 will only output video if there is a stream piped into them, as shown in the examples in the #Use cases section. Without an input stream, many applications will not detect these 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.

## 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 a new low-level multimedia framework, which can also do some things v4l2loopback is used for.

### Screen casting

Below are examples of how to implement screen sharing by streaming your screen to a v4l2 loopback device, which can then 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`.
- This command will not work with non-wlroots-based compositors such as KWin.

Install wf-recorder. 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 Wi-Fi 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/videofeed -vf format=yuv420p -f v4l2 /dev/video0

Another easier way is to use scrcpy:

    $ scrcpy --video-source=camera --camera-id=0 --camera-size=1920x1080 --video-bit-rate=20M --v4l2-sink=/dev/video0 --no-playback

Tip Another option is to use Iriun with iriunwebcam-binAUR.

### Using a background image in video conferencing

There are a number of different options for hiding/replacing the background in video conferencing software like Microsoft Teams and Zoom.

#### OBS

OBS is used by streamers as a real-time video management system, for switching between video feeds. It can have multiple "scenes" set up (e.g. each with a different background image) and then they can be switched with a button click. It can also provide other video filters, has a plugin system for new ones, can display multiple video feeds at the same time, and so on. It can send its output to a v4l2loopback device that works with any application that supports V4L2 cameras.

To set this up:

1. Install the main obs-studio package and the obs-backgroundremovalAUR plugin.
2. Load `obs` and add the real camera as an input source for the scene.
3. Right-click on the source and edit the filters, and add the background removal filter. You should now see the background erased, only showing black. (You can also opt to blur the background instead of removing it, in the advanced options.)
4. Add another input source of type "Image" and select your preferred background image. The source type could also be a video file or another webcam, but start with an image until everything is working.
5. Drag the image entry in the source list so that it is below the entry for the video source, in order for the image to appear behind the video instead of in front of it.
6. Move/resize the background image so that it takes up most of the scene.
7. Enable the virtual output and the virtual webcam is ready to use.

`obs` must be left running with the virtual output enabled in order for the virtual webcam to be usable by video conferencing software.

If you get a corrupted or blank image (common after changing the output resolution) you may need to delete and recreate the V4L2 loopback device (or unload and reload the `v4l2loopback` module).

See #Viewing a v4l2loopback video feed above for troubleshooting - if these programs play the feed fine then the problem is with the application consuming the video. If these utilities also do not see video properly, the problem is with the loopback set up.

## 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/v4l2compat.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

v4l2loopback
Add topic