ProMatte 1.0.2 — the macOS plugin loads

The macOS plugin failed to load in OBS in 1.0.1. This release fixes it. Windows
and Linux are unaffected — nothing in their build changed.

The macOS load failure

1.0.1 made OBS report "the following OBS plugins failed to load: promatte" on
every Mac, Apple Silicon and Intel alike. Two independent faults were baked into
the shipped binary, either of which was enough on its own:

libobs had nowhere to resolve. The module's only LC_RPATH was
@loader_path/../Frameworks, which points inside ProMatte's own bundle. Its
dependency on @rpath/libobs.framework/Versions/A/libobs therefore could not be
found: libobs lives in OBS.app/Contents/Frameworks, and the plugin sits outside
the app in ~/Library/Application Support/obs-studio/plugins. The bundle now
also carries @executable_path/../Frameworks, the pair the upstream OBS plugin
template sets.

The bundled ONNX Runtime was under the wrong filename. The binary asks for
@rpath/libonnxruntime.1.23.0.dylib, but the file vendored into
Contents/Frameworks was named libonnxruntime.dylib — the name of the
unversioned symlink in the upstream tarball rather than the name recorded in the
dependency. The install_name_tool -change that was supposed to redirect it used
that same wrong name, so it matched no load command and did nothing, without
failing or warning. The resolved file is now vendored under its real name and the
reference points straight at it.

Why CI did not catch it

The macOS job checked otool -L piped through head, that both architecture
slices existed, and that the archive was over 10 MB. All three passed on the
broken build: the load commands were printed but never resolved.

tools/check-macos-bundle.py now parses the Mach-O load commands and resolves
each one against the bundle. System libraries pass, @loader_path dependencies
must exist on disk, @rpath dependencies must be reachable through an rpath that
is actually present, and anything OBS.app supplies requires an @executable_path
rpath. It runs on the built bundle and again on the unpacked archive, so an
install rule that drops or renames a file is caught too. Run against the 1.0.1
bundle it reports six failures.

Downloads

Platform	File
Windows 10/11 x64	ProMatte-Setup-1.0.2.exe
Linux x86_64 (Debian/Ubuntu)	promatte_1.0.2_amd64.deb
Linux x86_64 (other)	promatte_1.0.2_linux-x86_64.tar.gz
macOS 11+, Intel and Apple Silicon	ProMatte-1.0.2-macos-universal.zip
macOS (alternative)	ProMatte-1.0.2-macos-universal.tar.gz

SHA256SUMS.txt covers every file. Requires OBS Studio 30.0 or newer.

Installing on macOS

If you installed 1.0.1, delete it first:

rm -rf ~/Library/Application\ Support/obs-studio/plugins/promatte.plugin

Then:

unzip ProMatte-1.0.2-macos-universal.zip
mkdir -p ~/Library/Application\ Support/obs-studio/plugins
mv ProMatte-1.0.2-macos-universal/promatte.plugin \
   ~/Library/Application\ Support/obs-studio/plugins/
xattr -dr com.apple.quarantine \
   ~/Library/Application\ Support/obs-studio/plugins/promatte.plugin

Quit OBS completely (⌘Q, not just the window) and start it again.

Installing on Linux

sudo dpkg -i promatte_1.0.2_amd64.deb

Not compatible with a Flatpak or Snap OBS, which sandbox their own plugin
directory. Full steps for both platforms are in the
README.

What is actually verified

Platform	Builds	Unit tests	Package installs	Loads in OBS	Runs with a camera
Windows x64	yes	36/36	yes	yes	yes, fully
Linux x86_64	yes	36/36	yes	dlopen succeeds and all libraries resolve	no
macOS, Apple Silicon	yes, in CI	36/36 in CI	yes	yes, OBS 32.2.2	yes — background removal confirmed at 30/30 fps
macOS, Intel	yes, in CI	not run (both CI and the test Mac are Apple Silicon)	not tried	every load command in the x86_64 slice resolves	no

This release has been confirmed working on an Apple Silicon Mac: the module
loads in OBS 32.2.2, the filter attaches to a camera, and Remove (transparent)
cuts the subject out, with OBS holding 30.00/30.00 fps at 23.6 % CPU. That also
settles the one thing the structural checks could not — that libobs 31.1.1
headers are compatible with the libobs inside OBS 32.x — at least for arm64.

Intel Macs are still unexercised. The x86_64 slice is built, lipo asserts it
exists, and every load command in it resolves, but nobody has run it: both the CI
runner and the machine that confirmed this are Apple Silicon. If you are on an
Intel Mac, this should work and no one has proven it. Windows remains the only
platform with performance measurements; there are no benchmark numbers for macOS.

If it fails to load for you, please open an issue with Help → Log Files → View
Current Log attached — dyld names the exact unresolved symbol or library there.

Full limitations are in
docs/final-verification.md.
Third-party attribution is in
THIRD_PARTY_LICENSES.md.

ProMatte is GPL-2.0-or-later.

ProMatte 1.0.1 — Intel Mac support

Warning

The macOS package in this release does not load. OBS reports "the following
OBS plugins failed to load: promatte" on both Apple Silicon and Intel. Two
faults in the bundle's link-time metadata caused it: the module had no rpath
that could reach libobs inside OBS.app, and the vendored ONNX Runtime was
written under a filename the binary never asks for. Both are fixed in
1.0.2 — use that
instead. Windows and Linux in this release are unaffected.

macOS now ships as a universal binary, so ProMatte runs on Intel Macs as well as
Apple Silicon, and a use-after-free found while making that work has been fixed.

Changes since 1.0.0

macOS supports Intel. The bundle is a universal binary carrying both an
x86_64 and an arm64 slice, so one download works on every supported Mac.
CI asserts with lipo that both slices are present in the module and in the
vendored ONNX Runtime, because a package that quietly lost one would still
install and then fail to load on the other kind of Mac. macOS pins ONNX Runtime
1.23.0, the last release with a universal2 build; 1.24 is Apple Silicon only.
Windows and Linux stay on 1.24.4.

Fixed a use-after-free reading model input shapes.
TypeInfo::GetTensorTypeAndShapeInfo() returns a non-owning view, and it was
being called on a temporary that died at the end of the statement. On ONNX
Runtime 1.24 the dangling read happened to return plausible values, so it went
unnoticed and 1.0.0 shipped with it. On 1.23 the garbage dimension count made
every model fail to load. It is undefined behaviour either way and is now fixed,
verified against both runtimes.

If you are on Windows or Linux, 1.0.0 works and this is a correctness fix rather
than a behaviour change you will notice. If you are on an Intel Mac, this is the
first release you can use at all.

Downloads

Platform	File
Windows 10/11 x64	ProMatte-Setup-1.0.1.exe
Linux x86_64 (Debian/Ubuntu)	promatte_1.0.1_amd64.deb
Linux x86_64 (other)	promatte_1.0.1_linux-x86_64.tar.gz
macOS 11+, Intel and Apple Silicon	ProMatte-1.0.1-macos-universal.zip
macOS (alternative)	ProMatte-1.0.1-macos-universal.tar.gz

SHA256SUMS.txt covers every file. Requires OBS Studio 30.0 or newer.

On macOS, move promatte.plugin into
~/Library/Application Support/obs-studio/plugins, then clear the quarantine
flag with xattr -dr com.apple.quarantine on it, since the bundle is unsigned.

What is actually verified

Platform	Builds	Unit tests	Package installs	Runs in OBS with a camera
Windows x64	yes	36/36	yes	yes, fully
Linux x86_64	yes	36/36	yes, module loads and all libraries resolve	no
macOS universal	yes, in CI	36/36 in CI, arm64 slice only	bundle inspected, not installed	no

Windows is the only platform exercised end to end against a real webcam. Linux
builds, passes its tests and produces a package whose module loads, but has
never run inside OBS. macOS is built, tested and packaged by CI and has never
been loaded in OBS on a Mac; the x86_64 slice in particular is verified
structurally with lipo, not executed, because the runner is Apple Silicon.

Full measurements and the complete limitations list are in
docs/final-verification.md.
Third-party attribution is in
THIRD_PARTY_LICENSES.md.

ProMatte is GPL-2.0-or-later.

ProMatte 1.0.0 — AI background removal for OBS Studio

Real-time AI background removal, blur and replacement for OBS Studio. Everything
runs on the local machine: no cloud service, no account, no telemetry, and no
frame ever leaves the computer.

Inference runs on its own thread with a latest-frame-wins mailbox, so OBS never
waits for the model. Edges are refined on the GPU with joint-bilateral
upsampling, feathering, edge decontamination and halo removal, and a
motion-adaptive temporal stabiliser keeps static edges from crawling while
letting moving ones respond immediately. An automatic quality controller picks
the model and AI resolution for the machine and steps down when it cannot keep
up.

Downloads

Platform	File	Notes
Windows 10/11 x64	ProMatte-Setup-1.0.0.exe	Installer. Detects the OBS folder, removes a stale copy under %ProgramData% and preserves your settings.
Linux x86_64 (Debian/Ubuntu)	promatte_1.0.0_amd64.deb	sudo dpkg -i promatte_1.0.0_amd64.deb
Linux x86_64 (other)	promatte_1.0.0_linux-x86_64.tar.gz	sudo tar xzf … --strip-components=1 -C /
macOS 11+ Apple Silicon	ProMatte-1.0.0-macos-arm64.zip	Move promatte.plugin into ~/Library/Application Support/obs-studio/plugins, then xattr -dr com.apple.quarantine it.
macOS (alternative)	ProMatte-1.0.0-macos-arm64.tar.gz	Same bundle, tar format.

SHA256SUMS.txt covers every file above. Requires OBS Studio 30.0 or newer.

After installing: right-click your webcam source → Filters → + →
ProMatte AI Background Removal. Leave Quality on Auto. Try Blur
first, since it is visible with nothing else in the scene.

What is actually verified

The three platforms are not equally tested, and the differences are real.

Platform	Builds	Unit tests	Package installs	Runs in OBS with a camera
Windows x64	yes	36/36	yes	yes, fully
Linux x86_64	yes	36/36	yes, module loads and all libraries resolve	no
macOS arm64	yes, in CI	36/36 in CI	bundle inspected, not installed	no

Windows is verified end to end on a 2017 dual-core laptop with a GeForce
940MX: a 37-step session against a real webcam covering every preset, background
mode, debug view, quality level, backend and model, plus scene switching, camera
resolution changes, a recording, and a 15-minute soak that held 30 fps while
memory fell from 726 MB to 498 MB. Details and measurements are in
docs/final-verification.md.

Linux builds against the distribution's libobs, passes the same 36 unit
tests, and the .deb installs with every shared library resolving and the
module loading. Inference was benchmarked there and lands within a few
milliseconds of the Windows figures on the same CPU. It has not been run
inside a running OBS against a camera.

macOS is built, unit-tested and packaged on a GitHub macos-15 Apple
Silicon runner against a libobs built from source. The bundle was downloaded and
inspected: binary, Info.plist, all five models, effects, locale and a vendored
libonnxruntime.dylib. It has never been loaded in OBS on a Mac, because
the author has no Mac. Treat it as a first build that compiles, links, passes
its tests and packages correctly, nothing more.

GPU acceleration

DirectML on Windows drives any D3D12 GPU (NVIDIA, AMD, Intel). CUDA, TensorRT,
CoreML and OpenVINO are selected automatically when an ONNX Runtime build
providing them is installed; none of those paths has been exercised, since the
shipped runtime contains only DirectML and CPU. CPU is always available and is
what Auto picks when a GPU turns out to be slower, which it measures per machine
and remembers.

Models

Five models ship with the plugin (MediaPipe Selfie landscape / square /
multiclass, PP-HumanSeg v2 lite and portrait), all Apache-2.0 or CC-BY-4.0. Two
more, Robust Video Matting and MODNet, are downloaded on request from the
Model Manager with a pinned SHA-256. RVM gives the best hair detail on a capable
GPU. A model with a non-commercial licence was evaluated and deliberately
excluded. Full attribution is in
THIRD_PARTY_LICENSES.md.

Known limitations

• Only Windows has been used against a real camera; see the table above.
• Single-person models: a second person is segmented only if the model happens
  to include them. The largest connected region is always kept, so the primary
  subject is never dropped.
• Robust Video Matting costs 71–96 ms per frame on the low-end test laptop, so
  Auto does not choose it there; on that class of hardware it looks excellent
  but lags fast motion.
• The first DirectML session on a given adapter compiles shaders, which took
  8 seconds on the test GPU and 30–76 seconds on an integrated Intel one. Video
  passes through untouched while that happens.
• Objects held in front of the face, such as a microphone, are treated as
  background by the person-segmentation models.
• The macOS bundle is unsigned and unnotarised, so Gatekeeper quarantines it.

ProMatte is GPL-2.0-or-later.