# Linux-Fake-Background-Webcam **Repository Path**: mirrors_Knetic/Linux-Fake-Background-Webcam ## Basic Information - **Project Name**: Linux-Fake-Background-Webcam - **Description**: Faking your webcam background under GNU/Linux, now supports background blurring, animated background, hologram effect and on-demand processing - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-08-06 - **Last Updated**: 2026-06-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Linux-Fake-Background-Webcam ## Background Video conferencing software support for background blurring and background replacement under Linux is relatively poor. The Linux version of Zoom only supports background replacement via chroma key. The Linux version of Microsoft Team does not support background blur. Over at Webcamoid, we tried to figure out if we can do these reliably using open source software ([issues/250](https://github.com/webcamoid/webcamoid/issues/250)). This repository started of as a tidy up of Benjamen Elder's [blog post](https://elder.dev/posts/open-source-virtual-background/). His blogpost described a background replacement solution using Python, OpenCV, Bodypix neural network, which is only available under Tensorflow.js. The scripts in Elder's blogpost do not work out of box. This repository originally provided a turn-key solution for creating a virtual webcam with background replacement and additionally foreground object placement, e.g. a podium. Over time this repository got strangely popular. However it has been clear over time that Bodypix is slow and difficult to set up. Various users wanted to use their GPU with Tensorflow.js, this does not always work. The extra code that provided GPU support sometimes created problems for CPU-only users. Recently Google released selfie segmentation support for [Mediapipe](https://github.com/google/mediapipe/releases/tag/v0.8.5). This repository has been updated to use Mediapipe for image segmentation. This significantly increased the performance. The older version of this repository is now stored in the ``bodypix`` branch. ## Prerequisite You need to install either v4l2loopback or akvcam. This repository was originally written with v4l2loopback in mind. However, there has been report that v4l2loopback does not work with certain versions of Ubuntu. Additionally, the author has never really managed to get v4l2loopback to work with Microsoft Team. Therefore support for akvcam has been added. ### v4l2loopback The v4l2loopback kernel module can be installed through the package manager of your Linux distribution or compiled from source following the instructions in the [v4l2loopback github repository](https://github.com/umlaeute/v4l2loopback). Once installed, the module needs to be loaded. This can be done manually for the current session by running $ sudo modprobe v4l2loopback devices=1 exclusive_caps=1 video_nr=2 card_label="fake-cam" which will create a virtual video device `/dev/video2`, however, this will no persist past reboot. (Note that the `exclusive_caps=1` option is required for programs such as Zoom and Chrome). To create the virtual video device on startup, run the `v4l2loopback-install.sh` script to create `/etc/modules-load.d/v4l2loopback.conf` to load the module and `/etc/modprobe.d/linux-fake-background.conf` to configure the module. The camera will appear as `fake-cam` in your video source list. If you get an error like ``` OSError: [Errno 22] Invalid argument ``` when opening the webcam from Python, please try the latest version of v4l2loopback from the its [Github repository](https://github.com/umlaeute/v4l2loopback), as the version from your package manager may be too old. #### Ubuntu 18.04 If you are using Ubuntu 18.04, and if you want to use v4l2loopback, please compile v4l2loopback from the source. You need to do the following: 1. Remove the ``v4l2loopback`` package - `sudo rmmod -r v4l2loopback` - `sudo apt-get remove v4l2loopback-dkms` 2. Install DKMS and the Linux kernel headers - ``sudo apt-get install dkms linux-headers-`uname -r` `` 3. Install v4l2loopback from the repository - `git clone https://github.com/umlaeute/v4l2loopback.git` - `cd v4l2loopback` 4. Install the module via DKMS - `sudo cp -R . /usr/src/v4l2loopback-1.1` - `sudo dkms add -m v4l2loopback -v 1.1` - `sudo dkms build -m v4l2loopback -v 1.1` - `sudo dkms install -m v4l2loopback -v 1.1` 5. Load the module - `sudo modprobe v4l2loopback` This may apply for other versions of Ubuntu as well. For more information, please refer to the following Github [issue](https://github.com/jremmons/pyfakewebcam/issues/7#issuecomment-616617011). ### Akvcam To install akvcam, you need to do the following: 1. Install the driver by following the instruction at [Akvcam wiki](https://github.com/webcamoid/akvcam/wiki/Build-and-install). I recommend installing and managing the driver via DKMS. 2. Configure the driver by copying ``akvcam`` to ``/etc/``. Please note that the configuration file I supplied locks your Akvcam instance to a resolution of 1280x720. It is different to the configuration file automatically generated by Webcamoid, as my configuration locks the input/output colour format of Akvcam. 3. Note down the output of ``ls /dev/video*``. 4. Run ``sudo modprobe akvcam`` 5. Akvcam should have created two extra ``video`` devices. 6. When running ``fake.py``, you need to set ``-v`` to the first video device that Akvcam created, e.g. if Akvcam created ``/dev/video5`` and ``/dev/video6``, you need to set ``-v /dev/video5``. 7. The software that uses the virtual webcam should the second device that Akvcam created, e.g. if Akvcam created ``/dev/video5`` and ``/dev/video6``, you need to set the software to use ``/dev/video6``. Note that in ``akvcam/config.ini``, ``Akvcam (Output device)`` is the device that ``fake.py`` outputs to, and ``Akvcam (Capture device)`` is the "capture device", which is opened by the software that you want to use the virtual webcam with. You might have to specify the ``--no-ondemand`` flag when using Akvcam. For more information on configuring Akvcam, please refer to [Akvcam wiki](https://github.com/webcamoid/akvcam/wiki/Configure-the-cameras) ### Disabling UEFI Secure boot Both v4l2loopback and Akvcam require custom kernel module. This might not be possible if you have secure boot enabled. Please refer to your device manufacturer's manual on disabling secure boot. ### Python 3 You will need Python 3. You need to have pip installed. Please make sure that you have installed the correct version pip, if you have both Python 2 and Python 3 installed. Please make sure that the command ``pip3`` runs. In Debian, you can run sudo apt-get install python3-pip I am assuming that you have set up your user environment properly, and when you install Python packages, they will be installed locally within your home directory. You might want to add the following line in your ``${HOME}/.profile``. This line is needed for Debian Buster. export PATH="$HOME/.local/bin":$PATH ### Upgrading pip Mediapipe requires pip version 19.3 or above. (Please refer to [here](https://pypi.org/project/mediapipe/#files) and [here](https://github.com/pypa/manylinux)). However, the pip distributed with some Linux distributions is outdated, e.g. [Debian Buster](https://packages.debian.org/buster/python3-pip). If you are on Debian Buster please make sure ``.local/bin`` is in your ``PATH``. You can make sure this is the case by adding: PATH="$HOME/.local/bin":$PATH in your ``~/.profile``. You can then upgrade pip by running: pip3 install --upgrade pip ## Installation The actual installation can be done by simply running ./install.sh ### Installing with Docker The use of Docker is no longer supported. I no longer see any reason for using Docker with this software. However I have left behind the files related to Docker, for those who want to fix Docker support. Please also refer to [DOCKER.md](DOCKER.md). The Docker related files were provided by [liske](https://github.com/liske). Docker made starting up and shutting down the virtual webcam more convenient for when Bodypix was needed. The ability to change background and foreground images on-the-fly is unsupported when running under Docker. ## Usage In the terminal window, do the following (if using v4l2loopback) : python3 fake.py The files that you might want to replace are the followings: - ``background.jpg`` - the background image - ``foreground.jpg`` - the foreground image - ``foreground-mask.jpg`` - the foreground image mask By default this program uses on-demand processing. The program processes images from the real webcam only when there are programs using the fake webcam. If there are no programs reading from the fake webcam, this program disconnects the real webcam, pauses processing and outputs a black image at 1 FPS to reduce CPU usage. You can manually toggle between the paused/unpaused state by pressing ``CTRL-C``. Unpausing the program also reload the files listed above. This allows you to replace them without restarting the program. You can disable the on-demand processing behaviour by specifying the ``--no-ondemand`` flag. Note that animated background is supported. You can use any video file that can be read by OpenCV. ### fake.py ``fakecam.py`` supports the following options: usage: fake.py [-h] [-W WIDTH] [-H HEIGHT] [-F FPS] [-C CODEC] [-w WEBCAM_PATH] [-v V4L2LOOPBACK_PATH] [-i IMAGE_FOLDER] [--no-background] [-b BACKGROUND_IMAGE] [--tile-background] [--background-blur BACKGROUND_BLUR] [--background-keep-aspect] [--no-foreground] [-f FOREGROUND_IMAGE] [-m FOREGROUND_MASK_IMAGE] [--hologram] [--no-ondemand] [--background-mask-update-speed BACKGROUND_MASK_UPDATE_SPEED] [--use-sigmoid] [--threshold THRESHOLD] [--no-postprocess] Faking your webcam background under GNU/Linux. Please refer to: https://github.com/fangfufu/Linux-Fake-Background-Webcam optional arguments: -h, --help show this help message and exit -W WIDTH, --width WIDTH Set real webcam width -H HEIGHT, --height HEIGHT Set real webcam height -F FPS, --fps FPS Set real webcam FPS -C CODEC, --codec CODEC Set real webcam codec -w WEBCAM_PATH, --webcam-path WEBCAM_PATH Set real webcam path -v V4L2LOOPBACK_PATH, --v4l2loopback-path V4L2LOOPBACK_PATH V4l2loopback device path -i IMAGE_FOLDER, --image-folder IMAGE_FOLDER Folder which contains foreground and background images --no-background Disable background image and blur the real background -b BACKGROUND_IMAGE, --background-image BACKGROUND_IMAGE Background image path, animated background is supported. --tile-background Tile the background image --background-blur BACKGROUND_BLUR Set background blur level --background-keep-aspect Crop background if needed to maintain aspect ratio --no-foreground Disable foreground image -f FOREGROUND_IMAGE, --foreground-image FOREGROUND_IMAGE Foreground image path -m FOREGROUND_MASK_IMAGE, --foreground-mask-image FOREGROUND_MASK_IMAGE Foreground mask image path --hologram Add a hologram effect --no-ondemand Continue processing when no consumers are present --background-mask-update-speed BACKGROUND_MASK_UPDATE_SPEED The running average percentage for background mask updates (default to 50) --use-sigmoid Force the mask to follow a sigmoid distribution, default to False --threshold THRESHOLD The minimum percentage threshold for accepting a pixel as foreground (default to 75) --no-postprocess Disable postprocessing (masking dilation and blurring), default to False ## License The source code of this repository are released under GPLv3. Linux Fake Background Webcam Copyright (C) 2020-2021 Fufu Fang This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see .