OpenFilter

OpenFilter is an open-source runtime and framework for building image and video processing pipelines out of small, composable components called filters. It handles the setup, serialization, and communication between filters — including frame synchronization, side-channel paths, load balancing, and telemetry — so you can focus on the processing itself, in plain Python.

A filter is a component that originates, processes, or exports a stream of frames and/or data. You chain filters into a pipeline (with many-to-many topologies), and the runtime keeps frames that enter together synchronized through to the output. Develop and test filters locally as ordinary Python processes, then ship each one as a Docker image.

Pipeline diagram: rendered on the GitHub README.

Homepage: openfilter.io · Package: PyPI · Images: Docker Hub

Jump to:

• Features
• Requirements
• Installation
• Quick Start
• Built-in filters
• Examples
• Documentation
• Telemetry & privacy
• Ecosystem
• Contributing
• License

Features

• Pluggable, reusable filters that you compose into pipelines
• Develop and test filters locally, in pure Python
• Automatic frame synchronization across many-to-many pipeline topologies
• Built-in I/O and visualization filters (VideoIn/VideoOut, ImageIn/ImageOut, Webvis, REST, MQTTOut, Recorder)
• Parallel processing via load-balanced filter branches and unsynchronized side-channel paths
• Built-in observability: OpenTelemetry tracing, OpenLineage lineage events, and per-frame metrics

Requirements

• Python 3.10 or newer (tested on 3.10, 3.11, 3.12, and 3.13)

Installation

Install OpenFilter with all built-in utility-filter dependencies:

pip install openfilter[all]

Install directly from GitHub:

pip install "openfilter[all] @ git+https://github.com/PlainsightAI/openfilter.git@main"

Install a specific version:

pip install "openfilter[all] @ git+https://github.com/PlainsightAI/openfilter.git@v1.1.2"

Editable install for development:

git clone https://github.com/PlainsightAI/openfilter.git
cd openfilter
make install

Run a published Docker image

Each built-in filter is also published as a Docker image (see Built-in filters):

docker run -e FILTER_SOURCES="file:///video.mp4!loop" \
           -e FILTER_OUTPUTS="tcp://*:5550" \
           -v ./video.mp4:/video.mp4:ro \
           plainsightai/openfilter-video-in:latest

Quick Start

Here is a minimal example that plays a video and visualizes it in the browser:

from openfilter.filter_runtime.filter import Filter
from openfilter.filter_runtime.filters.video_in import VideoIn
from openfilter.filter_runtime.filters.webvis import Webvis

if __name__ == '__main__':
    Filter.run_multi([
        (VideoIn, dict(sources='file://video.mp4', outputs='tcp://*')),
        (Webvis,  dict(sources='tcp://localhost')),
    ])

Run it with:

python script.py

Then open http://localhost:8000 to see your video stream.

Alternatively, use the CLI:

openfilter run - VideoIn --sources 'file://video.mp4!loop' - Webvis

These examples expect a video.mp4 in the current directory. A sample video ships with the repository at examples/hello-world/example_video.mp4 — copy it to video.mp4, or point --sources at that path.

Built-in filters

OpenFilter ships a set of ready-to-use filters. Run openfilter info <Filter> for a filter's configuration options.

Each I/O filter is also published as a Docker image at plainsightai/openfilter-<name> (multi-arch amd64 + arm64), tagged with both the version (for example 1.1.2) and latest. Each installs openfilter[extra]=={version} from PyPI:

Examples

Explore real-world examples covering:

• Frame-by-frame video processing
• Writing frames to JPEG or output video
• Dual-video pipelines with multiple topics
• Load balancing using multiple filter processes
• Publishing data over MQTT
• Ephemeral side-channel processing
• S3 integration for cloud video processing
• Fully declarative and class-based configuration

Runnable demos live in the examples/ directory, and every topic above is walked through in the Overview.

Documentation

• Overview — concepts, pipeline topologies, and a tour of the examples
• Your First Filter — build your own filter
• Declarative configuration — configure pipelines declaratively
• Monitoring and metrics architecture — telemetry and observability
• Migration guide — upgrading between versions
• Built-in filter references: VideoIn · VideoOut · ImageIn · ImageOut · Webvis · REST · MQTTOut · Recorder · Util
• Contributing guide — development setup, conventions, DCO sign-off, and the release process

Telemetry & privacy

When a filter starts, OpenFilter emits a single anonymous usage-analytics event — the filter's class name — via Scarf, which helps the maintainers understand adoption. Beyond that class name, OpenFilter sends no frame data, pipeline configuration, or personal information. Opt out at any time by setting an environment variable:

export DO_NOT_TRACK=true

Ecosystem

OpenFilter is the open-source runtime and filter framework, released under Apache 2.0. Related projects:

• openfilter-pipelines-controller — a Kubernetes operator for running filter pipelines.
• Additional open-source filters and tools are published across the PlainsightAI organization.

Plainsight (plainsight.ai) offers a commercial managed platform built on OpenFilter for teams that want hosted deployment and support.

Contributing

We welcome contributions of all kinds — new filters, bug fixes, or documentation improvements.

See the contributing guide for development setup, coding conventions, DCO sign-off, and the release process. If you run into a problem, open an issue.

License

Apache License 2.0. See LICENSE for the full text.