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.