An open-source, privacy-first VLC plugin for local AI sensitive-content detection and frame blocking with ONNX Runtime.
Important
icop is a best-effort content filter. Detection models can produce false positives and false negatives, so test your configuration before relying on it for child-safety or accessibility needs.
icop is an open-source AI content filtering plugin for VLC media player. It uses local ONNX Runtime inference to classify buffered video frames before display, then shows the original frame or applies a black, blur, or warning treatment. Processing stays on your device; video frames are not uploaded to a service.
The plugin targets Windows and Linux today, with experimental macOS build and installation support. It is designed for privacy-conscious playback, offline video filtering, and developers exploring ONNX-based computer vision in VLC.
Watch the full ICOP VLC walkthrough
Plugin setup, blocking styles, muted playback, and the detection debug overlay.
The public Git repository is source-only. Models, ONNX Runtime binaries, build trees, portable VLC copies, and release archives are downloaded or generated locally and are not committed.
| Platform | Status | GPU inference |
|---|---|---|
| Windows x86_64 | Tested | CUDA (NVIDIA) / D3D12 (GPU fallback) |
| Linux x86_64 | Tested | CUDA (NVIDIA) / MIGraphX (AMD) |
| Linux ARM64 | Tested | CPU only |
| macOS x86_64 | Tested | CPU / CoreML |
| macOS ARM64 | Tested | CPU / CoreML |
GPU runtimes are detected automatically at plugin load. Contributions that improve GPU support or validate the macOS path are welcome.
-
Buffers frames so playback does not intentionally outrun classification
-
Runs inference locally with ONNX Runtime
-
Supports multiple model profiles and automatic model-sized preprocessing
-
Provides black, blur, and warning block styles
-
Can mute audio while blocked output is shown
-
Supports precomputed decision maps for scan-ahead playback
-
Includes a D3D11 processing path for supported Windows hardware decoding
-
On Linux opaque VAAPI/VDPAU-style inputs, analyzes via VLC image conversion and drops blocked frames fail-closed when in-place masking is not available
-
Produces versioned, platform-specific packages with checksums and metadata
-
Includes unit, integration, and benchmark targets
-
Local and offline sensitive-content filtering in VLC media player
-
Best-effort parental controls and safer shared-screen playback
-
Privacy-first video moderation without cloud uploads
-
ONNX Runtime, CUDA, and D3D11 video-filter development
-
Cross-platform computer-vision research and prototyping
-
VLC decodes a video frame.
-
icop holds the frame before presentation.
-
The detector converts and resizes a sample for the selected model.
-
ONNX Runtime classifies the sample and applies the configured block window.
-
The plugin releases the original or masked frame to VLC.
The central safety invariant is simple: a frame that requires analysis should not be shown before its decision is available.
Ask an AI assistant to install icop using the INSTALL.md guide. Give it the file and it will handle down, copying, enabling the filter, and applying best-practice settings for your platform.
Requirements:
- CMake 3.16 or newer
- Ninja or another supported CMake generator
- A C compiler and a C++17 compiler
- VLC 3.0 development files for the target platform
Configure, build, and package:
make build
make test
make release
On Windows, use mingw32-make
instead of make
when that is the installed GNU Make command. Direct CMake commands remain available in CONTRIBUTING.md.
The package is written to releases/v<version>/<os>/
. See INSTALL.md for end-user installation steps.
When upgrading from VLC iClean, remove libnsfw_filter_plugin
and
nsfw_filter_core
files before regenerating the plugin cache. The runtime
files are named libicop_plugin
and icop_core
.
Build the host release, detect the installed VLC, copy the matching x86/x64/ARM64 payload, and regenerate VLC's plugin cache:
make install_plugin
Use mingw32-make install_plugin
on Windows when GNU Make is installed under
that name. The target selects the PowerShell installer on Windows and the POSIX
installer on Linux/macOS. Both validate release checksums, remove legacy VLC
iClean files, roll back failed copies, and regenerate the plugin cache. Windows
requests administrator access when needed; Linux and macOS use sudo
only for protected plugin directories.
Preview the operation or select a specific installation directly:
powershell -ExecutionPolicy Bypass -File .\tools\install_icop_plugin.ps1 -WhatIf
powershell -ExecutionPolicy Bypass -File .\tools\install_icop_plugin.ps1 -VlcRoot "C:\Program Files\VideoLAN\VLC"
sh tools/install_icop_plugin.sh --dry-run
sh tools/install_icop_plugin.sh --vlc-root /usr
Close VLC before installation. To stop it explicitly, pass
INSTALL_ARGS=-StopVlc
on Windows or INSTALL_ARGS=--stop-vlc
on Linux/macOS.
See CONTRIBUTING.md for lightweight Windows, Linux, and WSL build and test commands. See docs/releasing.md for package versioning, checksums, and release verification.
| Profile | Input | Upstream project | Upstream license |
|---|---|---|---|
marqo |
|||
| 384x384 | |||
adamcodd
AdamCodd/vit-base-nsfw-detectorfalconsai
Falconsai/nsfw_image_detectionlegacy
iola1999/nsfw-detect-onnxModel and runtime files retain their upstream licenses. Review THIRD_PARTY_NOTICES.md before redistributing a binary package.
The VLC module settings cover the most common choices:
| Setting | Purpose |
|---|---|
| Model profile and path | Select a bundled profile or custom ONNX model |
| ONNX provider | Choose CPU, CUDA, or automatic provider selection |
| Processing backend | Choose portable CPU or supported Windows D3D11 processing |
| Detection threshold | Control the model score that triggers blocking |
| Analysis stride and buffer | Balance coverage, latency, and throughput |
| Block style and padding | Choose the mask and extend detections around unsafe frames |
| Audio muting | Mute playback while blocked frames are presented |
| Decision map | Reuse precomputed blocked time ranges |
See INSTALL.md Step 4 for
best-practice values. The marqo
profile at threshold 0.17
prioritises sensitivity and can produce more false positives than the default. Adjust threshold upward if false alarms are too frequent. No single profile is right for every video — validate with representative, legally shareable media.
Build the plugin, detector core, tests, and benchmark:
cmake --build build-ninja --target icop_plugin icop_core icop_test icop_benchmark -j 8
ctest --test-dir build-ninja --output-on-failure
CI also supports a lightweight source build with model downloads disabled. The full integration suite requires locally downloaded ONNX models. Runtime testing requires a VLC installation or portable VLC tree compatible with the package.
- Classification runs locally and does not require up video frames.
- Optional debug dumps can write frame data to disk and should stay disabled for private media.
- Logs may contain local paths and should be reviewed before sharing.
- Detection quality depends on the model, threshold, source material, and processing configuration.
- Public issues and tests must use synthetic or redistributable media, never private or explicit personal content.
icop accepts sponsorship only through GitHub Sponsors. Sponsorship does not affect issue priority, security handling, or project licensing.
icop is licensed under GPL-2.0-or-later. See LICENSE for the full license text.
VLC and VideoLAN are trademarks of VideoLAN. This independent project is not affiliated with or endorsed by VideoLAN.