GIF

PureFrame

Inspiration

Families share movie files, and the options for watching them with kids are all bad: keep a hand on the seek bar, trust a rating label, or hunt for a "cleaned" copy of unknown origin and quality. The ideas that became PureFrame came from two places. First, the feeling that a tool which runs entirely on my own machine, works on files I legally own, and blurs exactly the moments I choose - without cutting anything or uploading a byte - simply should exist. Second, IMDb's Parents Guide: fans have already documented where the explicit scenes are in almost every show, so a local tool should be able to accept that knowledge instead of discovering everything cold. The line I would not cross was scraping: PureFrame reads marks you author locally, and it never fetches anything.

What it does

PureFrame takes a local video file (MP4, MKV, WebM, AVI) and produces the same file with explicit visuals blurred. No scene cutting, no audio changes - the audio track is stream-copied byte for byte, and clean video segments are copied, not re-encoded.

Three local models do the watching: NudeNet finds explicit body regions, CLIP reads the scene context, PANNs scores the audio. A fusion engine combines those signals into per-shot verdicts, an IoU tracker follows flagged regions across frames, and the renderer draws smooth tracked blur (or boxes, pixelation, or emoji markers).

The workflow is review-first: process does everything in one pass, or you split it - plan writes a plain JSON plan, preview renders a contact sheet, plan-whitelist strikes out anything you disagree with, and only then does apply render. Nothing is censored until you approve.

Highlights:

Fully offline after install. Models are bundled; nothing leaves the machine.
Scene-context gate: confident beach, gym, museum or medical contexts raise the nudity bar, so swimwear, shirtless athletes, classical paintings and surgical footage stop flagging while real explicit scenes still flag.
Content profiles for live-action, animation, anime, low-light, art and medical material.
A bounded second pass for the hard cases: flash frames, small or distant figures, screen-in-screen, and extreme close-ups get a denser rescan and a tiled zoom.
Automatic fixes for hostile inputs: variable frame rate converts to constant, AV1 re-encodes as AV1, HDR10 metadata survives the render.
Parental guide marks: hand it a timestamps file from a saved guide page and it covers shots the models missed.
A plugin API so other detectors can add box categories without touching the core.
A Tauri desktop GUI with a plan editor and before/after preview, a CLI on PyPI, and standalone builds for Windows, macOS and Linux with a signed auto-updater.

How we built it

The pipeline is Python. ffmpeg-python handles every media read and write, PySceneDetect finds shot boundaries, ONNX Runtime runs NudeNet (int8-quantized on CPU for a 2-4x speedup, gated by a parity check), HuggingFace transformers runs CLIP, and PANNs scores audio. The fusion engine applies strictness presets, content-type multipliers, per-shot scene factors and guide windows to one threshold bar, and every downstream stage (densify, rescan, render) reads the same bar so verdicts and blur boxes can never disagree. The smart renderer re-encodes only censored segments with source-matched encoders (x264, x265, VP8, VP9, SVT-AV1 or libaom) and concatenates them with the stream-copied rest inside the original container.

Quality is enforced, not hoped for. A synthetic eval corpus of 55 scenarios has a committed baseline; a parity gate fails the build if any detection score drifts. 584 fast tests and 14 slow end-to-end tests run on every pull request across Linux, macOS and Windows. The known-limitations document is part of the definition of done: every fix names its test, and anything not fixable in code is listed as accepted, with the reason.

Challenges we ran into

NudeNet does not fire on flat synthetic shapes, so proving detection changes required honest fixtures: mocked detector sessions with strict visibility bars, plus real-encoder clip generation for everything around the model.
CLAHE, the obvious fix for dark scenes, does nothing on flat frames - the histogram has no room to equalize. A percentile stretch worked and stayed predictable.
Keeping models frozen meant every accuracy gain had to come from preprocessing, sampling, fusion or rendering. That constraint produced better engineering than fine-tuning would have.
Encoder reality: AV1 builds differ wildly per platform. Some Windows libsvtav1 builds reject higher presets at encode time, a macOS build hung on a full fixture after passing a small probe, and OpenCV builds without software AV1 decode cannot even feed scene detection. The code now probes, falls back from SVT to libaom, and skips cleanly where the machine cannot cope.
Fusion bugs live one layer down: the verdict bar and the box-building bar silently diverged once, and a flagged shot lost its blur. Every factor now flows through one shared helper.
Small stuff bites: Python 3.11 refuses float formatting on Fractions, Windows consoles choke on unicode arrows, and the GitHub releases API flaked for hours on asset uploads during the release.

Accomplishments that we're proud of

The review-first contract: a plain JSON plan you can read, whitelist, and only then render. Trust is the product.
Eleven known limitations closed with engineering in one offensive - each with a regression test or an eval-corpus pin that fails without it - and the limitations document restructured into fixed, improved and accepted-with-reason. Nothing claims more than the tests show.
A release that ships like software: 21 signed assets with checksums, an auto-updater serving the latest version to every desktop install, and a PyPI package verified by installing it in a throwaway environment.
The whole thing stays offline. No account, no cloud, no telemetry, no scraping.
A clean security scan on the final tree, and CI that treats detection parity as a gate rather than a suggestion.

What we learned

Detection quality in production is a systems problem. Sampling density, threshold fusion, encoder choice and container rules move the needle as much as the models do.
Every threshold needs guards in both directions and a stated reason. A gate that can only raise a bar is easy to trust; one that can also lower it needs an explicit switch and a test for each context pair.
Config changes that alter verdicts must invalidate caches, or users keep old results and lose trust silently.
The bugs that ship are one layer below the verdict: the plan can be right while the boxes disappear. Test the layer under the decision.
Honest documentation is a feature. The accepted-limitations list earns more trust than pretended completeness.

What's next for PureFrame

Real-footage evaluation at scale: the scoring harness exists, so the next step is accumulating real-world numbers across many movies and genres and letting those guide the next tuning pass.
A 10-bit HDR render path: HDR10 metadata already survives the re-encode, but the frame pipe is 8-bit, and true 10-bit fidelity is the honest next move.
Hardware AV1 encode paths alongside the software SVT/libaom pair, and broader codec coverage as containers allow.
Growing the plugin ecosystem: the API takes any box-provider detector; audio-adjacent and language-specific detectors are the interesting frontier.
Windows code signing through Azure Trusted Signing and Apple notarization, so the installers stop scaring smart-screen and Gatekeeper.
GUI deepening: richer plan editing, side-by-side timeline scrubbing, and per-profile presets saved with the library.