obs-backgroundremoval: Portrait Segmentation Inside OBS Studio
An OBS plugin for removing background in portrait images (video), making it easy to replace the background when recording or streaming.
At a glance
- What is it?
- A GPL-3.0 OBS plugin that replaces the background behind a person using ONNX segmentation models, with CoreML, CUDA, ROCm and MIGraphX paths and a CPU fallback. The judgement: it is the mature option for Linux and Apple Silicon, and the README is honest about where it still is not finished.
- Who is it for?
- Adopt it if you stream from OBS on Debian Forky, Apple Silicon with CoreML, or a Linux box with CUDA, ROCm or MIGraphX, and you want the background handled inside OBS rather than in a separate virtual-camera app. Do not adopt it if you need a supported Windows or macOS source build, or if you run OBS on Apple Silicon through Rosetta 2, which the README says will crash.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: background replacement without leaving OBS
Most people who stream or record from a laptop have a background they do not want on camera. The usual workarounds are a physical green screen, a virtual-camera app that sits between the webcam and OBS, or a webcam vendor utility with its own compositor. The first costs space and lighting discipline. The other two add a hop in the video pipeline and a second place to configure scenes.
obs-backgroundremoval takes a different position: the segmentation runs as an OBS source filter, so the mask and the replacement happen inside the scene graph the streamer already manages. The README describes the plugin as replacing the background in portrait images and video, and notes that it composes with other OBS plugins to swap in an image or a transparent colour. That composability is the actual product. The plugin does not ship a background editor, a scene designer or a virtual camera; it produces a masked portrait and hands it back to OBS.
It is aimed at one-person productions: a streamer, a tutor recording lessons, a developer on a call. It is not aimed at multi-camera studios that already own hardware keyers, and it is not a general-purpose video editor effect.
How the segmentation pipeline works
The plugin is written in C++ and links against libobs, the OBS plugin API, which is why it installs as a filter rather than as a standalone application. The neural network inference is handled by ONNX Runtime, and the repository carries a vcpkg manifest and triplets, so the runtime and its dependencies are resolved at build time rather than vendored by hand.
The model weights are not original to this project. The README lists the sources for portrait foreground segmentation: SINet, PP-HumanSeg from PaddleSeg, the MediaPipe Meet segmentation model via PINTO_model_zoo, and RobustVideoMatting. A separate set of models handles low-light enhancement: TBEFN, URetinex-Net and a semantic-guided low-light model, again through PINTO_model_zoo. The Models/ directory in the repository holds the ONNX files, and the release notes for 1.4.0 refer to supply chain security, which is consistent with a project that ships third-party model files and wants them traceable.
Execution providers are the interesting design axis. On macOS the plugin uses CoreML, which the README calls efficient on Apple Silicon. On Linux, CUDA, ROCm and MIGraphX are available if the plugin is built from source and the ONNX Runtime installation has matching support. ROCm is marked deprecated because ONNX Runtime 1.23.0 removed it, and MIGraphX is recommended for AMD GPUs instead. Windows acceleration via WinML is described as planned, not shipped. Where no GPU path exists, inference falls back to CPU, and the README states the goal plainly: to be available for everyone on every system, even if they do not own a GPU.
That fallback is the mechanism that decides whether the plugin is usable for you. CPU inference on a segmentation model is a real cost per frame, and the only tuning knob the README documents is the thread count in the UI settings, where it says a 2-thread setting works best. It does not document a resolution or frame-skip control, so on a weak machine there is no documented way to trade quality for headroom beyond the thread count.
Installing it and adding the filter
The README points to a download and install page on the project site, and to the releases page for browsing versions. For a normal install, take a package from the releases page that matches your platform and OBS version; release 1.5.0 is titled for OBS 32+ and for fixing deb packages, so older OBS builds should look at 1.4.x instead. The README does not document a rollback procedure for a bad plugin install, so keep the installer you used.
If you are building from source, the README only officially supports Debian Forky on x86_64 and arm64, and says build scripts for Windows, macOS and other Linux distributions are planned. The documented sequence clones the repository, runs the bootstrap script, then setup, then build, then installs the resulting deb:
git clone https://github.com/royshil/obs-backgroundremoval.git
cd obs-backgroundremoval
sudo ./bin/bootstrap
./bin/setup
./bin/build
sudo dpkg -i release/obs-backgroundremoval-*-linux-gnu.debThe bootstrap step needs root because it installs build dependencies; the build itself does not. After the deb installs, restart OBS so the plugin is loaded.
Once OBS is running, add the effect the way you would add any other filter. The README does not spell out the click path; it points to the usage guide page and to a YouTube playlist for the walkthrough. The filter is applied to the camera source, and the result is a portrait with the background removed, which you can then composite over an image or a solid colour in the scene. If you want to check the model actually loaded before troubleshooting anything else, look at the filter properties after adding it; a filter that reports the model is not initialized has not found its ONNX files, which is a different failure from poor edge quality.
Where it breaks: architecture, platform and packaging
The sharpest limitation in the README is architectural, not algorithmic. On macOS, the plugin does not support cross-architecture translation. Intel binaries on Apple Silicon, or Apple Silicon binaries on Intel, will crash. That is an unusual failure mode: it is not a warning about quality, it is a hard stop, and it means a user who installs the wrong package gets a crash rather than a slow filter. If you run OBS under Rosetta 2 on an Apple Silicon Mac, this plugin is the wrong tool.
The second limitation is packaging coverage. The README states that the officially supported build-from-source platforms are Debian Forky on x86_64 and arm64, and that scripts for Windows, macOS and other Linux distributions are planned. Users on those platforms depend on prebuilt releases, which means they are exposed to whatever OBS version each release targets. The 1.5.0 release title ties it to OBS 32+, so a user on an older OBS who grabs the newest package may find it does not load.
The third is GPU support on Linux. CUDA, ROCm and MIGraphX require a source build and a matching ONNX Runtime. A prebuilt package will not silently give you GPU inference, and the ROCm path is deprecated because upstream removed it. For AMD users this means MIGraphX or CPU.
Finally, the README itself acknowledges the plugin does not always work and points to the Lite version, Live Background Removal Lite, as an alternative when it does not. A maintainer writing that sentence is telling you the segmentation quality or stability is not uniform across hardware, and that the fallback is a different project rather than a setting.
How it differs from Live Background Removal Lite
The README's own pointer is to Live Background Removal Lite, developed by Kaito Udagawa, one of the contributors to this plugin. The two projects come from overlapping authorship, which makes the comparison more useful than a generic alternative list, because the split is deliberate.
The difference in approach is scope. obs-backgroundremoval carries a set of segmentation models plus a separate set of low-light enhancement models, exposes execution-provider choices across CoreML, CUDA, ROCm and MIGraphX, and includes extras such as a depth-of-field effect, which the README links as a tutorial video. That breadth is why it needs a vcpkg build, a model directory and per-platform packaging. The Lite version is positioned in the README as the thing to try when this plugin is not working, which implies a smaller surface: fewer models, fewer providers, less to go wrong.
If you want background removal and nothing else, and you are hitting instability, the Lite project is the documented escape hatch. If you want low-light enhancement or the depth-of-field effect alongside segmentation, the Lite version is not described as covering that ground, and you are back to this plugin's model set and its GPU configuration.
Licence and the cost of keeping it current
The plugin is GPL-3.0, and the source files carry SPDX headers naming GPL-3.0-or-later along with the copyright holders. The repository also has a LICENSES/ directory, a NOTICE file and a REUSE.toml, which is the REUSE compliance convention for declaring per-file licensing. For a streamer, GPL-3.0 on an OBS plugin is unremarkable; OBS itself is GPL-2.0, and you are loading the plugin, not linking your own proprietary code against it. If you redistribute a build, or ship a product that bundles it, the GPL obligations are yours to read. This is not legal advice, and the licence text is the authority.
One detail worth separating from the code licence: the model weights come from several upstream projects, each with its own terms. The README lists the model repositories but does not restate their licences, so anyone redistributing the Models/ directory should check those upstream repositories rather than assume the plugin's GPL-3.0 covers them.
Upgrade cost is mostly a function of the OBS version, not the plugin. The last push to the repository was on 2026-09-10, and the release cadence over 2026 has been roughly every two to four months: 1.4.0 in April, 1.4.1 in July, 1.5.0 in August. Each release has carried a platform or dependency fix rather than a new model family, which suggests the maintenance work is largely keeping pace with OBS, OpenCV and ONNX Runtime. That is the cost you inherit: when OBS ships a new major version, you wait for a matching plugin release, and the 1.5.0 title shows that gap is real.
Editorial conclusion
Adopt it if you stream from OBS on Debian Forky, Apple Silicon with CoreML, or a Linux box with CUDA, ROCm or MIGraphX, and you want the background handled inside OBS rather than in a separate virtual-camera app. Do not adopt it if you need a supported Windows or macOS source build, or if you run OBS on Apple Silicon through Rosetta 2, which the README says will crash. Before installing, check the release page for a package matching your OBS version, since 1.5.0 is titled for OBS 32+, and confirm the model files under Models/ are present after the install. If the filter reports the model is not initialized, that is a model-loading problem, not a segmentation-quality problem.
Frequently asked questions
What is OBS background removal?
It is an OBS Studio plugin that removes the background behind a person in a portrait image or video, so the background can be replaced inside OBS. It uses a neural network to predict the portrait mask and runs through ONNX Runtime, with a CPU fallback when no GPU path is available.
How do I install obs-backgroundremoval?
The README points to the project's download and install page and to the releases page for browsing versions. Building from source is officially supported only on Debian Forky for x86_64 and arm64, using the bootstrap, setup and build scripts in the bin directory followed by installing the generated deb.
How do I set up OBS background removal?
It installs as an OBS source filter, so you add it to the camera source in your scene. The README does not give the click path itself; it points to the usage guide page and to a YouTube playlist for the walkthrough.
How do I use the OBS background removal plugin?
The plugin produces a masked portrait and hands it back to OBS, where it composes with other plugins to swap in an image or a transparent colour. The README's usage guide page and tutorial videos cover the recommended settings.
Is there an alternative to the OBS background removal plugin?
The README points to Live Background Removal Lite, developed by one of the same contributors, as the thing to try when this plugin is not working. It is a smaller project without the low-light enhancement and depth-of-field features described here.
How do I add OBS background removal?
It is added as a filter on the camera source, not as a separate application or virtual camera. The README directs users to the usage guide page and the tutorial videos rather than documenting the menu path itself.
Community notes