{"id":21088241,"url":"https://github.com/hamidzr/webcam-mods","last_synced_at":"2025-05-16T11:32:36.214Z","repository":{"id":37213724,"uuid":"258922834","full_name":"hamidzr/webcam-mods","owner":"hamidzr","description":"Face tracking, bg removal, crop, zoom, record \u0026 replay, and more webcam mods","archived":false,"fork":false,"pushed_at":"2023-02-16T04:46:08.000Z","size":2663,"stargazers_count":63,"open_issues_count":9,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-04T01:01:35.849Z","etag":null,"topics":["v4l2","v4l2loopback","webcam","webcam-streaming"],"latest_commit_sha":null,"homepage":"https://youtu.be/FfD7lu_A1Dw","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamidzr.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}},"created_at":"2020-04-26T02:41:40.000Z","updated_at":"2025-01-12T15:20:15.000Z","dependencies_parsed_at":"2023-01-31T04:45:54.364Z","dependency_job_id":null,"html_url":"https://github.com/hamidzr/webcam-mods","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidzr%2Fwebcam-mods","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidzr%2Fwebcam-mods/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidzr%2Fwebcam-mods/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidzr%2Fwebcam-mods/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamidzr","download_url":"https://codeload.github.com/hamidzr/webcam-mods/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254522279,"owners_count":22085080,"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":["v4l2","v4l2loopback","webcam","webcam-streaming"],"created_at":"2024-11-19T21:16:29.904Z","updated_at":"2025-05-16T11:32:31.088Z","avatar_url":"https://github.com/hamidzr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Webcam Mods\n\nTested on Arch Linux.\n\n\nCheckout my other repository for some ffmpeg-only solutions [here](https://github.com/hamidzr/scripts/tree/master/ffmpeg)\n\nFind installation and a work-in-progress demos here:\n - Latest demo [https://youtu.be/FfD7lu_A1Dw](https://youtu.be/FfD7lu_A1Dw) (recorded on commit `8f08bc68` on Jan 2022). It showcases some of the main features.\n - Archived demo [https://youtu.be/idp7ei-pF40](https://youtu.be/idp7ei-pF40) (recorded using version [cf765](https://github.com/hamidzr/webcam-mods/commit/cf7651fe08caea024e4cc9f33540fa4bd2a2eb82))\n\n## Included Mods\n\n### Face Tracking\n\nSetup your webcam to focus and follow your face by cropping and resizing the frames it receives from\nyour main webcam.\n\n### Person Segmentation\n\nSeparate the people in the frame from the background using a fast real-time prediction model. The model\noutputs a mask values between 0 to 1.\nWe have mods based on this to swap the background with:\n\n- a solid color\n- another image\n- blurred version of the input frame (aka blur my background)\n\n### Cropping\n\nInteractively move your camera around with arrow keys `ctrl+arrowkeys`\nResize the cropped frame using `ctrl+shift+arrowkeys`\nYou can disable this control by defining the environment variable `PAN_CONTROL=False`.\n\n### Padding\n\nInteractively pad your camera output with arrow keys `alt+arrowkeys` while keeping the output\nframesize fixed.\nYou can disable this control by defining the environment variable `PADDING_CONTROL=False`.\n\n#### Record \u0026 Replay\n\nRecord and replay your camera feed on the fly. While you're in any of the other modes above\npress `r` to start recording and press `p` to stop recording and start replaying in a loop.\n\n_For entertainment purposes only_\n\n## Installation\n\nDepending on your python setup you might need to include the current directory in your `$PYTHONPATH`.\nTo do so run the following: `export PYTHONPATH=\"$PYTHONPATH:./\"`\n\n### Dependencies\n\nSystem dependencies:\n\n- Python 3.8: Some installation options include [pyenv](https://github.com/pyenv/pyenv) [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html)\n- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n- A virtual camera device: [Linux] v4l2loopback [Windows or MacOS] [OBS](https://obsproject.com/).\nFollow [pyvirtualcam's instructions](https://github.com/letmaik/pyvirtualcam#supported-virtual-cameras) to set this up.\n\n\nIf you're just interested in running the released features install the project as a python package using:\n`pip install git+https://github.com/hamidzr/webcam-mods@master` (python 3.8 environment) and access the\noffered features using `webcam_mods` CLI. This would replace the `entry.py` mentions in the rest of \nthe documentation.\n\nPython dependencies are listed in `Pipfile`. Install them using [Pipenv](https://pipenv-fork.readthedocs.io/en/latest/) (recommended)\n\n[WARN] If you don't use `pipenv` for dependency and virtual env management you'd need to find replacements wherever you\nsee `pipenv` mentioned =\u003e `grep -R pipenv .`\n\n1. create a virtual environment: `pipenv --python 3.8`\n2. activate it `pipenv shell`\n3. install the dependencies `pipenv install --skip-lock`\n\n## Setting up a virtual webcam device on Linux\n\nOn Linux once you have the v4l2 module installed you can run `sudo make add-video-dev` to add a virtual\ncamera device with some pre-set flags.\n\nWhich executes the following to remove and re-insert the module.\nYou might need root access for this.\n\n```\npkill gst-launch \u0026\u003e /dev/null || true\nrmmod v4l2loopback \u0026\u003e /dev/null || true\nmodprobe v4l2loopback devices=1 max_buffers=2 exclusive_caps=1 video_nr=10 card_label=\"v4l2-cam\"\n```\n\n\n\n## Upgrading\n\nIf you run into an issue upgrading try removing the old config file at `.webcam.conf`\n\n## Running the Mods\n\nAfter you've successfully followed installation steps, you can run the different modes by\ncalling `python webcam_mods/entry.py --help` from within the `src` directory .\n\n## Settings\n\nWhen you use the interactive controls to move the camera around the resulting parameters are saved in\na text file to your disk which is by default located at `$HOME/.webcam-mods.conf`\n\n### Environment Variables\n\nEnvironment variables are used to configure different parameters. Read more about how to set or\npersist them [here](https://lmgtfy.app/?q=how+to+set+environment+variables+in+linux)\nThese are mostly defined in the `config.py` file. To see their default values take a look at that\nfile.\n\n- `VIDEO_IN` \u0026 `VIDEO_OUT`:\nIf you have multiple video input devices, aka webcams, you can pick the one you want by providing its\nindex through by setting the `VIDEO_IN` environment variable. eg `export VIDEO_IN=0`. Same if you have\nmultiple output devices.\n\n- `MAX_OUT_FPS`: [Default: 30] set an upper limit for output FPS.\n\n- `IN_WIDTH` [Default: 640], `IN_HEIGHT` [Default: 480]: Your video input device likely support\nmultiple resolution and FPS settings use these env variables to pick and persist the one you want.\n`v4l2-ctl` can list out the different settings your webcam driver supports: `v4l2-ctl --list-formats-ext | less`\n\n- `OUT_WIDTH` [Default: 640], `OUT_HEIGHT` [Default: 480]: similar to `IN_HEIGHT` and `OUT_HEIGHT`\nbut for your output device.\n\n- `ON_DEMAND` [Default: False, Linux only]: set to True to lower cpu usage while the output camera device isn't actively\nused.\n\n- `IN_FORMAT`: input video format. This dictates the requested video format from the input video device (webcam)\nwhich directly affects picture quality and FPS. If you're looking to get higher a resolution or FPS\nout of your webcam it's crucial to inspect your camera and driver capabilities and set the appropriate format here.\n\n- `PAN_CONTROL` [Default True]: Set to False to disable panning/resizing with `ctrl+arrowkeys/ctrl+shift+arrowkeys`.\n\n- `PADDING_CONTROL` [Default True]: Set to False to disable padding with `alt+arrowkeys`.\n\n\n\n## TODO\n\nhouse cleaning:\n- clean and reorganize the code\n- set up a code formatter\n- set up a language server for development with Vim and VSCode\n- replace the facetracking model with mediapipe\n- move the config file to `$XDG_CONFIG_HOME`\n- cli support for settings currently supported by env variables\n\nfeatures:\n- [x] more stable edges for person segmentation\n- [ ] support other video feed formats from webcam eg mjpeg, h264 for higher resolution\n- including headphones in the mask \n- visualize interactive camera control settings\n- [x] zoom support. done through resizing.\n  - the controls could be more intuitive\n- [x] MacOS support\n  - disable ionotify. quartz install\n- [x] Windows support? should be there with `pyvirtualcam`\n- [ ] hot swap inputs\n- [~] add screen as an input\n- [ ] convert/migrate env variables to cli arguments\n- [ ] brightness control. (and hue, saturation?)\n- [~] smooth bounding box tracking (for facetracking and more)\n  - camera/crop size change transition\n- [ ] overlay on top of video\n\nbugs:\n- bug what?\n\na demo video showcasing the features\n\n## Contact\n\nAre you interested in helping improve this tool (hint: look at the TODO section)?\nAre you looking for a specific feature, or have you found a bug?\nUse [GitHub Issues](https://github.com/hamidzr/webcam-mods/issues/new) to reach out to me.\n\n\n## Credits\n\n- [Google/mediapipe](https://github.com/google/mediapipe) for their selfie segmentation model.\n- [fangfufu/Linux-Fake-Background-Webcam](https://github.com/fangfufu/Linux-Fake-Background-Webcam)\nFor mask post processing and automatic ondemand pause and restart.\n- [letmaik/pyvirtualcam](https://github.com/letmaik/pyvirtualcam)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidzr%2Fwebcam-mods","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamidzr%2Fwebcam-mods","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidzr%2Fwebcam-mods/lists"}