v4l2loopback

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-bin
AUR
or
zoom
AUR
. 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/video
X
, 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-bin
AUR
and
zoom
AUR
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-bin
AUR
.
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:
Install
the main
obs-studio
package and the
obs-backgroundremoval
AUR
plugin.
Load
obs
and add the real camera as an input source for the scene.
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.)
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.
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.
Move/resize the background image so that it takes up most of the scene.
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
If this library is not available, you may have some luck with
$ LD_PRELOAD=/usr/lib/libcamera/v4l2-compat.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