MatteLoop

MatteLoop cuts the background out of a video on your own machine and gives you back a transparent animated WebP that loops.

Your video, model weights, every intermediate frame and the finished loop stay on your disk. MatteLoop makes no network request except the update check, the update package download, and the model download on first use. The segmentation runtime's own telemetry is switched off on macOS and Linux; on Windows it is switched off after the runtime loads, but a startup diagnostic event is written to Windows' event tracing before that and may be collected under the device's diagnostic data policy.

What it is for

You have a clip of a subject — a person, a pet, a product — and you want it without its background, as a loop you can drop onto any page or into any composite. MatteLoop is the whole path from that clip to that loop:

• Open a local video and scrub to the part you want.
• Pick the frames with IN and OUT points on the timeline.
• Preview a single frame to judge the cutout before committing to a render.
• Trim, crop and resize the finished cut, and watch it loop on screen until it is right.
• Render a lossless transparent animated WebP.
• Choose or clear the output directory in the inspector's Output section.
• Replace the open clip by dropping another video onto the window, or with the Replace button. Unsaved transform edits are never discarded without asking first.
• Reset the render parameters to their defaults when a setting has drifted and you would rather start from the top.

The interface is available in English and German. Change the language in Preferences from the gear button; the choice applies after restarting MatteLoop. Preferences also holds compute acceleration, which describes this machine's graphics hardware rather than the clip, so it stays out of the inspector.

The result is lossless and genuinely transparent — an alpha channel, not a matte painted onto a colour.

Judge the loop before you render it

The transform stage works on the cut you already have. Trimming, cropping and resizing never touch the stored frames; they are a specification applied when the file is encoded, so you can change your mind as often as you like without segmenting anything again.

Choose the model that suits the shot

Different subjects want different weights. MatteLoop ships a catalog of them and downloads only what you ask for, so a first run costs one model rather than the whole set. The manager shows what is on disk, what a weight costs, and which weights are left over from an earlier version of the segmentation runtime.

Weights are not bundled with the application. They download on first use and are cached locally; birefnet-portrait alone is about 928 MiB and the complete catalog is about 6.35 GiB, which is exactly why you fetch them one at a time.

Built on rembg

The segmentation in MatteLoop is rembg by Daniel Gatis. The model catalog, the session classes that run each architecture, and the whole approach to background removal come from that project, and the weights MatteLoop downloads are its release artifacts, listed with their checksums in resources/model-manifest.json. MatteLoop is the desktop application around it: the timeline, the preview, the transform stage and the WebP encoder.

The authors of the individual model architectures behind those weights are credited in THIRD_PARTY_NOTICES.md, along with every other component and its licence.

Getting it

Native builds for macOS 15+ arm64 and Windows x64 are published on the releases page. The release assets are MatteLoop-v<version>-macos-arm64.zip, MatteLoop-v<version>-windows-x64-Setup.exe, and MatteLoop-v<version>-windows-x64.zip; Windows therefore offers both an installer and a portable archive. The portable archive extracts to a versioned folder, so two downloads never look alike. They are unsigned by decision: Windows warns through SmartScreen, so choose More info, then Run anyway; macOS refuses the first launch, so open System Settings → Privacy & Security, find the message naming MatteLoop, and choose Open Anyway. Linux artifacts are deferred, and the current native qualification covers macOS 15+ arm64 only.

Use one MatteLoop instance per installation. The installer and portable archive update their own current installation in place.

On macOS, ~/Applications is a legitimate install location and the better choice for a user without administrator rights: it ends translocation just as /Applications does and always belongs to the user.

MatteLoop never needs administrator rights to update itself. If such a prompt appears, the application is installed somewhere the user cannot write — cancel it and install the new version by hand.

MatteLoop tells you when a new release is available: it checks once at startup and opens an update offer with the version and download action. Dismissing the offer leaves an update arrow beside the Preferences gear so it can be reopened. Preferences carries a manual check and the switch that turns the startup one off. It can also opt into beta releases. Turning beta off never downgrades the installation: it stays on its beta until a stable release overtakes it.

Run from source

Use CPython 3.13 and install the locked environment with:

uv sync --frozen --all-groups
uv run matteloop

For quick diagnostics, uv run matteloop --version avoids Qt and model access; uv run matteloop --smoke-test exercises the local runtime without downloading weights; and uv run matteloop --providers reports which ONNX Runtime execution providers the installed runtime actually offers.

Run the checks with:

uv run ruff check .
uv run mypy src
QT_QPA_PLATFORM=offscreen uv run pytest -q

Model weights and generated workspaces are intentionally local and are never committed. Durable cut sets and scratch live under MatteLoop's user cache at <platformdirs.user_cache_dir("matteloop")>/workspace/.

If an older output folder still contains cut sets in its legacy workspace, MatteLoop offers to move them into the cache from Manage Workspaces. The move is optional and is performed one set at a time after each copy is verified.

The screenshots above are generated rather than collected, so a layout change never leaves them quietly out of date. Regenerate them with:

QT_QPA_PLATFORM=offscreen uv run python scripts/screenshots.py

It decodes assets/demo/golden-retriever.mp4, segments it with birefnet-general-lite — which has to be in the local model cache already — and rewrites assets/screenshots/.

Native builds automatically compile or reuse a source-pinned, verified LGPL FFmpeg/libwebp/PyAV wheel; the stock PyAV wheel is not an eligible packaging fallback. They also create a checksum-verified Qt/PySide 6.10.3 source companion containing the exact official Qt Base, Qt Image Formats, and PySide Setup archives, package inventory, complete GPL/LGPL texts, and replacement instructions. See docs/building.md for local and manual Actions commands, the five inseparable distribution outputs, unsigned-artifact launch warnings, and current platform qualification status.

Notes for people writing decoder tests live in docs/testing-fixtures.md.

Comparing models

To see how every model handles the same clip, set up the range, crop and settings in the app, then choose Copy render settings from the Render button's context menu (Ctrl/⌘+Shift+C). The benchmark renders those exact settings once per model and writes one WebP each, a results.json with timings, and an index.html that shows all of them side by side:

uv run python scripts/benchmark_models.py --out benchmark-run

• It reads the settings from the clipboard. On Linux or a headless machine, save them to a file and pass --request <file>.
• By default it renders the 13 models the app offers, about 6.8 GB of weights on a first run. bria-rmbg (own licence terms) and u2net_cloth_seg (needs a clothing-category input) run only when named with --models.
• Renders share the app's cut cache. A model whose cuts already exist for these settings is reused rather than segmented again, and flagged in the report — its tile may show hand-edited cuts, and its time is not a real measurement.
• To rebuild index.html and each model's still-image fallback from an existing run's results.json and WebPs — after a report change, without rendering again — pass --report-only <dir> instead of --out.

License

MatteLoop's original source code, documentation, and visual assets are licensed under the Zero-Clause BSD license, to the extent copyright or related rights exist. You may use, copy, modify, and distribute them for any purpose, with or without fee or attribution.

MatteLoop does not reserve separate project-controlled trademark restrictions for its name or logo; they may be reused with the same freedom.

Third-party libraries, fonts, and model weights keep their own licenses. Model weights download on first use and are not part of the MatteLoop distribution. See THIRD_PARTY_NOTICES.md for the component and native-release details. The full third-party GPL version 3 and LGPL version 3 texts, prominent Qt/PySide notice, and practical replacement instructions are kept in the repository and inside every native app; they do not change MatteLoop's 0BSD license.