v4l2loopback

From ArchWiki

Related articles

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 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.

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-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:

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

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: An other option is 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/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