{"id":15030932,"url":"https://github.com/fangfufu/linux-fake-background-webcam","last_synced_at":"2025-05-14T09:06:44.888Z","repository":{"id":37230528,"uuid":"255077623","full_name":"fangfufu/Linux-Fake-Background-Webcam","owner":"fangfufu","description":"Faking your webcam background under GNU/Linux, now supports background blurring, animated background, colour map effect, hologram effect and on-demand processing.","archived":false,"fork":false,"pushed_at":"2025-04-27T23:59:08.000Z","size":7829,"stargazers_count":1651,"open_issues_count":27,"forks_count":165,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-05-14T09:05:36.885Z","etag":null,"topics":["akvcam","mediapipe","opencv-python","tensorflow-lite","v4l2loopback","webcam","webcam-background"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fangfufu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-12T12:28:12.000Z","updated_at":"2025-05-12T09:48:57.000Z","dependencies_parsed_at":"2023-01-17T14:02:02.235Z","dependency_job_id":"bda632ac-933b-4d02-8b0c-62d5eed2f4b4","html_url":"https://github.com/fangfufu/Linux-Fake-Background-Webcam","commit_stats":{"total_commits":213,"total_committers":46,"mean_commits":4.630434782608695,"dds":"0.37089201877934275","last_synced_commit":"2cc5987e6a54c0632c0f017184eacf7a760dd0cb"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangfufu%2FLinux-Fake-Background-Webcam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangfufu%2FLinux-Fake-Background-Webcam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangfufu%2FLinux-Fake-Background-Webcam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangfufu%2FLinux-Fake-Background-Webcam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fangfufu","download_url":"https://codeload.github.com/fangfufu/Linux-Fake-Background-Webcam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110374,"owners_count":22016391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["akvcam","mediapipe","opencv-python","tensorflow-lite","v4l2loopback","webcam","webcam-background"],"created_at":"2024-09-24T20:14:33.574Z","updated_at":"2025-05-14T09:06:44.867Z","avatar_url":"https://github.com/fangfufu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CodeFactor](https://www.codefactor.io/repository/github/fangfufu/linux-fake-background-webcam/badge)](https://www.codefactor.io/repository/github/fangfufu/linux-fake-background-webcam)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/9ab112be62e4472aa114181bcde1a885)](https://app.codacy.com/gh/fangfufu/Linux-Fake-Background-Webcam/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n\n# Linux-Fake-Background-Webcam\n\n## Background\nVideo conferencing software support for background blurring and background\nreplacement under Linux is relatively poor. The Linux version of Microsoft\nTeam does not support background blur. Over at Webcamoid, we tried to figure out\nif we can do these reliably using open source software\n([issues/250](https://github.com/webcamoid/webcamoid/issues/250)).\n\nThis repository started of as a tidy up of Benjamen Elder's\n[blog post](https://elder.dev/posts/open-source-virtual-background/). His\nblogpost described a background replacement solution using Python, OpenCV,\nBodypix neural network, which is only available under Tensorflow.js. The scripts\nin Elder's blogpost do not work out of box. This repository originally provided\na turn-key solution for creating a virtual webcam with background replacement\nand additionally foreground object placement, e.g. a podium.\n\nOver time this repository got strangely popular. However it has been clear over\ntime that Bodypix is slow and difficult to set up. Various users wanted to use\ntheir GPU with Tensorflow.js, this does not always work. The extra code that\nprovided GPU support sometimes created problems for CPU-only users.\n\nRecently Google released selfie segmentation support for\n[Mediapipe](https://github.com/google/mediapipe/releases/tag/v0.8.5). This\nrepository has been updated to use Mediapipe for image segmentation. This\nsignificantly increased the performance. The older version of this repository\nis now stored in the ``bodypix`` branch.\n\nThe performance improvement introduced by\n[2f7d698](https://github.com/fangfufu/Linux-Fake-Background-Webcam/commit/2f7d6988a3275b8aa4cbc73bed8151666c5aedef)\nmeans that you can get at least 25FPS on an i7-4900MQ.\n\n## Prerequisite\nYou need to install either v4l2loopback or akvcam. This repository was\noriginally written with v4l2loopback in mind. However, there has been report\nthat v4l2loopback does not work with certain versions of Ubuntu. Therefore \nsupport for akvcam has been added.\n\n### v4l2loopback\nThe v4l2loopback kernel module can be installed through the package manager of\nyour Linux distribution or compiled from source following the instructions in\nthe [v4l2loopback github repository](https://github.com/umlaeute/v4l2loopback).\n\nOnce installed, the module needs to be loaded. This can be done manually for\nthe current session by running\n\n```shell\nsudo modprobe v4l2loopback devices=1 exclusive_caps=1 video_nr=2 card_label=\"fake-cam\"\n```\n\nwhich will create a virtual video device `/dev/video2`, however, this will not\npersist past reboot. (Note that the `exclusive_caps=1` option is required for\nprograms such as Zoom and Chrome).\n\nTo create the virtual video device on startup, run the `v4l2loopback-install.sh`\nscript to create `/etc/modules-load.d/v4l2loopback.conf` to load the module and\n`/etc/modprobe.d/linux-fake-background.conf` to configure the module.\n\nYou can provide the video device number you want to use as an argument to this installation script.\nFor example, if you run `v4l2-ctl --list-devices` and get something like this:\n\n```text\nIntegrated Camera: Integrated C (usb-0000:00:14.0-4):\n\t/dev/video0\n\t/dev/video1\n\t/dev/video2\n\t/dev/video3\n\t/dev/media0\n\t/dev/media1\n```\n\nYou would want to run the command as follows to use the next available device number:\n\n```shell\n./v4l2loopback-install.sh 4\n```\n\nIf you don't provide a video device number, the script will try to infer the next available device number for you.\nThis functionality requires `grep` with PCRE support and `bc`.\n\nThe camera will appear as `fake-cam` in your video source list.\n\nIf you get an error like\n```\nOSError: [Errno 22] Invalid argument\n```\n\nwhen opening the webcam from Python, please try the latest version of\nv4l2loopback from the its\n[GitHub repository](https://github.com/umlaeute/v4l2loopback), as the version\nfrom your package manager may be too old.\n\n### v4l2loopback-ctl\n\nYou can also use `v4l2loopback-ctl` to control virtual video device.\n\nTo add a virtual video device, use `sudo v4l2loopback-ctl add --exclusive-caps=1 --name=\"fake-cam\" /dev/video2`.\n\nTo remove a virtual video device, use `sudo v4l2loopback-ctl delete /dev/video2`.\n\nTo list available virtual video devices, use `sudo v4l2loopback-ctl list`.\n\n#### Ubuntu 18.04\nIf you are using Ubuntu 18.04, and if you want to use v4l2loopback, please\ncompile v4l2loopback from the source. You need to do the following:\n1. Remove the ``v4l2loopback`` package\n    - `sudo rmmod -r v4l2loopback`\n    - `sudo apt-get remove v4l2loopback-dkms`\n2. Install DKMS and the Linux kernel headers\n    - ``sudo apt-get install dkms linux-headers-`uname -r` ``\n3. Install v4l2loopback from the repository\n    - `git clone https://github.com/umlaeute/v4l2loopback.git`\n    - `cd v4l2loopback`\n4. Install the module via DKMS\n    - `sudo cp -R . /usr/src/v4l2loopback-1.1`\n    - `sudo dkms add -m v4l2loopback -v 1.1`\n    - `sudo dkms build -m v4l2loopback -v 1.1`\n    - `sudo dkms install -m v4l2loopback -v 1.1`\n5. Load the module\n    - `sudo modprobe v4l2loopback`\n\nThis may apply for other versions of Ubuntu as well. For more information,\nplease refer to the following Github\n[issue](https://github.com/jremmons/pyfakewebcam/issues/7#issuecomment-616617011).\n\n### Akvcam\nTo install akvcam, you need to do the following:\n1. Install the driver by following the instruction at\n[Akvcam wiki](https://github.com/webcamoid/akvcam/wiki/Build-and-install). I\nrecommend installing and managing the driver via DKMS.\n2. Configure the driver by copying ``akvcam`` to ``/etc/``. Please note that the\nconfiguration file I supplied locks your Akvcam instance\nto a resolution of 1280x720. It is different to the configuration file\nautomatically generated by Webcamoid, as my configuration locks the input/output\ncolour format of Akvcam.\n3. Note down the output of ``ls /dev/video*``.\n4. Run ``sudo modprobe akvcam`` or make the akvcam start with a system:\n``sudo akvcam-install.sh``\n5. Akvcam should have created two extra ``video`` devices.\n6. When running ``lfbw.py``, you need to set ``-v`` to the first video device\nthat Akvcam created, e.g. if Akvcam created ``/dev/video5`` and ``/dev/video6``,\nyou need to set ``-v /dev/video5``.\n7. The software that uses the virtual webcam should the second device that\nAkvcam created, e.g. if Akvcam created ``/dev/video5`` and ``/dev/video6``,\nyou need to set the software to use ``/dev/video6``.\n\nNote that in ``akvcam/config.ini``, ``Akvcam (Output device)`` is the  device\nthat ``lfbw.py`` outputs to, and ``Akvcam (Capture device)`` is the \"capture\ndevice\", which is opened by the software that you want to use the virtual webcam\nwith.\n\nYou might have to specify the ``--no-ondemand`` flag when using Akvcam.\n\nFor more information on configuring Akvcam, please refer to\n[Akvcam wiki](https://github.com/webcamoid/akvcam/wiki/Configure-the-cameras)\n\n### Disabling UEFI Secure boot\nBoth v4l2loopback and Akvcam require custom kernel module. This might not be\npossible if you have secure boot enabled. Please refer to your device\nmanufacturer's manual on disabling secure boot.\n\n## Installation\n\nSet up a virtual environment running Python \u003e= 3.9 and \u003c=3.11. You can use conda, pyenv, virtual-env or whatever you like.\n\nActivate this virtual environment.\n\nMediapipe requires pip version 19.3 or above. (Please refer to [here](https://pypi.org/project/mediapipe/#files) and [here](https://github.com/pypa/manylinux)).\nUpgrade pip by running:\n\n```\npython -m pip install --upgrade pip\n```\n\nThen clone the repository and install the software:\n\n```\ngit clone https://github.com/fangfufu/Linux-Fake-Background-Webcam\ncd Linux-Fake-Background-Webcam\npython -m pip install --upgrade .\n```\n\nIf pip complains about being unable to resolve `mediapipe`, it means you are running an unsupported Python version (\u003c3.8 or \u003e3.11). Mediapipe currently supports only Python 3.8-3.11.\n\n### Installing with Docker\nThe use of Docker is no longer supported. I no longer see any reason for using\nDocker with this software. However I have left behind the files\nrelated to Docker, for those who want to fix Docker support.\nPlease also refer to [DOCKER.md](DOCKER.md). The Docker related files were\nprovided by [liske](https://github.com/liske).\n\nDocker made starting up and shutting down the virtual webcam more convenient\nfor when Bodypix was needed. The ability to change background and foreground\nimages on-the-fly is unsupported when running under Docker.\n\n## Usage\n\nInside the virtual environment in which you installed the software, simply run\n```shell\nlfbw\n```\n\nYou configure it using a ini file, see `./config-example.ini`.\nTo run with a config file, use the following command:\n\n```shell\nlfbw -c ./config-example.ini\n```\n\nThe files that you might want to replace are the followings:\n\n  - ``background.jpg`` - the background image\n  - ``foreground.jpg`` - the foreground image\n  - ``foreground-mask.jpg`` - the foreground image mask\n\nBy default this program uses on-demand processing. The program processes images\nfrom the real webcam only when there are programs using the fake webcam. If\nthere are no programs reading from the fake webcam, this program disconnects the\nreal webcam, pauses processing and outputs a black image at 1 FPS to reduce CPU\nusage. You can manually toggle between the paused/unpaused state by pressing\n``CTRL-C``. Unpausing the program also reload the files listed above. This\nallows you to replace them without restarting the program. You can disable the\non-demand processing behaviour by specifying the ``--no-ondemand`` flag.\n\nNote that animated background is supported. You can use any video file that can\nbe read by OpenCV.\n\n### lfbw\n\n`lfbw` supports the following options:\n\n```\nusage: lfbw    [-h] [-c CONFIG] [-W WIDTH] [-H HEIGHT] [-F FPS] [-C CODEC]\n               [-w WEBCAM_PATH] [-v V4L2LOOPBACK_PATH] [--no-background]\n               [-b BACKGROUND_IMAGE] [--tile-background] [--background-blur k]\n               [--background-blur-sigma-frac frac] [--background-keep-aspect]\n               [--no-foreground] [-f FOREGROUND_IMAGE]\n               [-m FOREGROUND_MASK_IMAGE] [--hologram] [--no-ondemand]\n               [--background-mask-update-speed BACKGROUND_MASK_UPDATE_SPEED]\n               [--use-sigmoid] [--threshold THRESHOLD] [--no-postprocess]\n               [--select-model SELECT_MODEL] [--cmap-person CMAP_PERSON]\n               [--cmap-bg CMAP_BG]\n\nFaking your webcam background under GNU/Linux. Please refer to:\nhttps://github.com/fangfufu/Linux-Fake-Background-Webcam\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -c CONFIG, --config CONFIG\n                        Config file (default: None)\n  -W WIDTH, --width WIDTH\n                        Set real webcam width (default: 1280)\n  -H HEIGHT, --height HEIGHT\n                        Set real webcam height (default: 720)\n  -F FPS, --fps FPS     Set real webcam FPS (default: 30)\n  -C CODEC, --codec CODEC\n                        Set real webcam codec (default: MJPG)\n  -w WEBCAM_PATH, --webcam-path WEBCAM_PATH\n                        Set real webcam path (default: /dev/video0)\n  -v V4L2LOOPBACK_PATH, --v4l2loopback-path V4L2LOOPBACK_PATH\n                        V4l2loopback device path (default: /dev/video2)\n  --no-background       Disable background image and blur the real background\n                        (default: False)\n  -b BACKGROUND_IMAGE, --background-image BACKGROUND_IMAGE\n                        Background image path, animated background is\n                        supported. (default: background.jpg)\n  --tile-background     Tile the background image (default: False)\n  --background-blur k   The gaussian bluring kernel size in pixels (default:\n                        21)\n  --background-blur-sigma-frac frac\n                        The fraction of the kernel size to use for the sigma\n                        value (ie. sigma = k / frac) (default: 3)\n  --background-keep-aspect\n                        Crop background if needed to maintain aspect ratio\n                        (default: False)\n  --no-foreground       Disable foreground image (default: False)\n  -f FOREGROUND_IMAGE, --foreground-image FOREGROUND_IMAGE\n                        Foreground image path (default: foreground.jpg)\n  -m FOREGROUND_MASK_IMAGE, --foreground-mask-image FOREGROUND_MASK_IMAGE\n                        Foreground mask image path (default: foreground-\n                        mask.png)\n  --hologram            Add a hologram effect. Shortcut for --selfie=hologram\n                        (default: False)\n  --selfie SELFIE       Foreground effects. Can be passed multiple time and\n                        support the following effects: \"hologram\",\n                        \"solid=\u003cN,N,N\u003e\", \"cmap=\u003cname\u003e\" and \"blur=\u003cN\u003e\"\n                        (default: [])\n  --no-ondemand         Continue processing when there is no application\n                        using the virtual webcam (default: False)\n  --background-mask-update-speed BACKGROUND_MASK_UPDATE_SPEED\n                        The running average percentage for background mask\n                        updates (default: 50)\n  --use-sigmoid         Force the mask to follow a sigmoid distribution\n                        (default: False)\n  --threshold THRESHOLD\n                        The minimum percentage threshold for accepting a pixel\n                        as foreground (default: 75)\n  --no-postprocess      Disable postprocessing (masking dilation and blurring)\n                        (default: True)\n  --select-model SELECT_MODEL\n                        Select the model for MediaPipe. For more information,\n                        please refer to https://github.com/fangfufu/Linux-\n                        Fake-Background-\n                        Webcam/issues/135#issuecomment-883361294 (default: 1)\n  --cmap-person CMAP_PERSON\n                        Apply colour map to the person using cmapy. Shortcut\n                        for --selfie=cmap=\u003cname\u003e. For examples, please refer\n                        to https://gitlab.com/cvejarano-\n                        oss/cmapy/blob/master/docs/colorize_all_examples.md\n                        (default: None)\n  --cmap-bg CMAP_BG     Apply colour map to background using cmapy (default:\n                        None)\n\n--selfie=\u003cfilter\u003e can be specified multiple times and accept a filter + its optional\narguments like --selfie=FILTER[=FILTER_ARGUMENTS].\n\nEach filter is applied to the foreground (self) in the order they appear.\nThe following are supported:\n- hologram: Apply an hologram effect?\n- solid=\u003cB,G,R\u003e: Fill-in the foreground fowith the specific color\n- cmap=\u003cname\u003e: Apply colour map \u003cname\u003e using cmapy\n- blur=\u003cN\u003e: Blur (0-100)\n\nExample:\nlfbw.py --selfie=blur=30 --selfie=hologram # slightly blur and apply the hologram effect\n\nArgs that start with '--' (eg. -W) can also be set in a config file (specified\nvia -c). Config file syntax allows: key=value, flag=true, stuff=[a,b,c] (for\ndetails, see syntax at https://goo.gl/R74nmi). If an arg is specified in more\nthan one place, then commandline values override config file values which\noverride defaults.\n```\n\n### Per-user systemd service\n\nModify `./systemd-user/lfbw_start_wrapper.sh` to suit your needs.\nIn particular, point to the correct `activate` shim for your virtual environment, and to the correct path to your config file.\nCopy the file inside `$HOME/.local/bin` folder.\n```\ncp ./systemd-user/lfbw_start_wrapper.sh $HOME/.local/bin/\n```\n\nCopy the systemd service file from `systemd-user` folder to a location\nsuitable for user-defined systemd services (typically\n`$HOME/.config/systemd/user`).\n\n```\ncp ./systemd-user/lfbw.service $HOME/.config/systemd/user/\n```\n\nTo start the service and enable it so that it is run after login, run the\nfollowing (as normal user):\n```\n$ systemctl --user start lfbw\n$ systemctl --user enable lfbw\n```\n\nCheck that the process is running smoothly:\n```\n$ systemctl --user status lfbw\n```\n\n## Contributors\n\nThanks for your contribution to the project!\n\n[![Contributors Avatars](https://contributors-img.web.app/image?repo=fangfufu/Linux-Fake-Background-Webcam)](https://github.com/fangfufu/Linux-Fake-Background-Webcam/graphs/contributors)\n[![Contributors Count](https://img.shields.io/github/contributors-anon/fangfufu/Linux-Fake-Background-Webcam?style=for-the-badge\u0026logo=Linux-Fake-Background-Webcam)](https://github.com/fangfufu/Linux-Fake-Background-Webcam/graphs/contributors)\n\n## License\nThe source code of this repository are released under GPLv3.\n\n    Linux Fake Background Webcam\n    Copyright (C) 2020-2024  Fufu Fang\n\n    This program is free software: you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangfufu%2Flinux-fake-background-webcam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffangfufu%2Flinux-fake-background-webcam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangfufu%2Flinux-fake-background-webcam/lists"}