zit — Inverse Telecine for VapourSynth (Zig port)

A Zig port of the VapourSynth-IT plugin (3:2-pulldown removal for NTSC), with the Avisynth-original parameters restored, high-bit-depth and 4:2:2/4:4:4 support, full frame-property support, and @Vector-based SIMD.

Verified bit-exact against the upstream --c reference path across the integration test grid (8-bit 4:2:0, the only format upstream supports) and on real-world telecined NTSC VOB samples.

Status

Quick start

import vapoursynth as vs
core = vs.core

clip = core.bs.VideoSource("source.vob")
clip = core.zit.IT(clip)          # default: fps=24, ref="TOP", diMode=3
clip.set_output()

Plugin reference

Plugin namespace: zit. Function: IT.

Full signature:

core.zit.IT(
    clip,
    fps=24,
    threshold=20,
    pthreshold=75,
    ref="TOP",
    blend=0,
    diMode=3,
)

Parameters

In fps=24 mode, decimation carries the cadence forward from earlier blocks. Seeking and parallel prefetch produce the same output as linear playback. The first seek ahead analyzes any missing predecessors in small batches; later requests reuse those decisions. This can add latency to the first seek.

ref values

diMode values

Frame properties on output

Standard (always set)

Diagnostic (set for inspection/scripting)

Convention follows VFM/VDecimate (camelCase, plugin-name prefix, no dots — VS API 4 silently rejects keys with dots).

Building from source

Requires Zig 0.17.0 (also used by CI and release builds). The VapourSynth API 4 bindings come from the vapoursynth-zig package pinned in build.zig.zon, explicitly configured for API 4.0 (VapourSynth R55+).

zig build --release=fast            # native shared library -> zig-out/lib/libzit.so
zig build test                       # unit tests (also run with --release=fast in CI)
zig build cross                      # release artefacts for all five targets

Cross-compile produces (ReleaseFast, stripped):

• zig-out/linux-x86_64/libzit.so, zig-out/linux-aarch64/libzit.so
• zig-out/macos-x86_64/libzit.dylib, zig-out/macos-aarch64/libzit.dylib
• zig-out/windows-x86_64/zit.dll

Release binaries target glibc 2.17+, macOS 10.9+ (Intel), and macOS 11.0+ (Apple Silicon). scripts/build_pypi_wheels.py checks binary deployment requirements against the wheel tags before packaging. Run the compatibility regressions after cross-compiling with python -m unittest discover -s tests/packaging -v.

Installation

Via pip (recommended)

pip install vapoursynth-zit

The wheel installs the platform-matched binary into VapourSynth's auto-discovery path (site-packages/vapoursynth/plugins/), so core.zit.IT(...) is available without any further LoadPlugin calls.

Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64).

Manual install (zip from a release)

If you'd rather not pull in pip, grab the matching *.zip from the Releases page and drop the binary into a VapourSynth plugin directory:

• Linux: /usr/local/lib/vapoursynth/
• macOS: ~/Library/ApplicationSupport/VapourSynth/plugins/
• Windows: vapoursynth64/plugins/ next to vsedit.exe

Performance

Measured 2026-10-03 on an AMD Ryzen 5 9600X, VapourSynth R81RC1 / API 4.3, Python 3.14.7, Zig 0.17.0 ReleaseFast/native (fmUnordered), and the vapoursynth-vivtc 2.0 wheel. Both VOBs are 720×480 YUV420P8 at 30000/1001 fps. VIVTC was refreshed with uv pip; 2.0 remains the latest PyPI release. The zit and VIVTC binary hashes are identical to the earlier R76 benchmark.

Median output frames/second over five runs. Each run uses a fresh filter chain and processes 3000 input frames after a 250-input-frame warmup, starting at input frame 9000. Source frames are predecoded and held in a fixed cache; the benchmark asserts that no source evaluation occurs during the runs. Timing includes bounded asynchronous frame requests (prefetch equals the worker count), without encoding, pixel copying, or hashing. Run order is randomized. These are filter-throughput measurements, not encode speeds.

VFM uses order=1, field=1, otherwise defaults; VDecimate uses defaults. The main zit columns include its default deinterlacing fallback (diMode=3). VFM has no such postprocessing. With zit's fallback disabled (fps=30, diMode=0), the eight-worker results are 8051 fps (eye) and 7870 fps (gb), respectively 1.69× and 1.87× VFM. This is a throughput comparison between different algorithms, not an image-quality or pixel-equivalence claim.

Both plugins run on the CPU. VFM uses fmParallel and scales substantially with multiple workers; zit's processing remains serialized. With eight workers, default zit field matching is 1.70× VFM on eye and 1.07× on gb. The full zit IVTC pipeline is 2.01× / 1.23× VFM → VDecimate on these clips. The cached-source control measured 57–59k fps, well above the filter rates.

Compared with the R76 measurements, the median throughput changed as follows (same input interval, parameters, plugin binaries, Python version, and request scheduling in the harness):

These are observations from two benchmark batches, not isolated kernel measurements. Small changes, particularly the multi-worker VFM results, overlap the observed run ranges. All 200 integration tests also pass on R81RC1.

R81RC1 raw measurements, ranges, and binary hashes are recorded alongside the reproducible harness. To use the same runtime (Python 3.12+ required):

zig build --release=fast
uv pip install --python .venv/bin/python --upgrade "VapourSynth==81rc1" vapoursynth-vivtc
.venv/bin/python scripts/bench_vivtc.py /path/to/eyeVTS_01_1.VOB /path/to/gbVTS_01_1.VOB \
  --json build/bench_vivtc_r81rc1.json

VIVTC is autoloaded from the environment. For a separate binary, pass --vivtc-plugin /path/to/vivtc.so; the harness records the loaded file's hash and rejects an explicit path that differs from an already loaded plugin.

Differences from the VapourSynth upstream

The VapourSynth upstream (HomeOfVapourSynthEvolution/VapourSynth-IT) ported only a subset of the Avisynth original. This port reintroduces everything plus fixes a few latent bugs:

1. Avisynth-original parameters back: ref (TOP/BOTTOM/ALL/NONE), blend, diMode (0/1/2/3). The upstream hardcoded ref="TOP"/blend=false/diMode=3 and removed the parameters.
2. Frame properties (_FieldBased, _Combed, _Duration*, inheritance of source props, plus IT* diagnostics). Upstream calls newVideoFrame(propSrc=null) so output frames carry no metadata, which breaks downstream core.resize.* colorspace handling.
3. Threading: registered as fmUnordered to serialize state access and request planning. Decimation blocks are analyzed in source order, making seeking and prefetch deterministic. Upstream uses fmParallel despite sharing mutable per-instance state across calls.
4. Frame request range: widened to cover what the algorithm actually reads ([base-2, base+6] for fps=24, [n-2, n+2] for fps=30 — plus [base-3, base+7] when blend=true). Upstream relied on the API 3 sync getFrame to retrieve neighbours, which is no longer permitted from inside getFrameFilter under API 4.
5. Edge clamping of frame indices passed to getFrameFilter. The upstream algorithm fetches n-1 even at n=0; under API 3 the core silently clamped, under API 4 it returns null and dereferences crash.

The reference build under reference/vapoursynth-cpp-api4/ applies the same framework-level fixes (otherwise it would segfault under VS R76) and is what the bit-exact comparison test runs against.

Repository layout

src/
├── plugin.zig    # VapourSynth plugin entry (VapourSynthPluginInit2)
├── filter.zig    # Filter instance + getFrame lifecycle + frame-prop setting
├── state.zig     # CFrameInfo, CTFblockInfo, CallState
├── plane.zig     # syp/dyp accessors, adjPara, clipFrame/X/Y
├── edge.zig      # makeDeMap                (SIMD)
├── eval_iv.zig   # evalIv                    (SIMD)
├── motion.zig    # makeMotionMap, makeMotionMap2Max/Min, makeSimpleBlurMap (SIMD)
├── scene.zig     # checkSceneChange          (SIMD)
├── decide.zig    # compCp / compCn / decide / setFt
├── output.zig    # copyCPNField / deintOneField / simpleBlur / deinterlace
├── blend.zig     # BlendFrame_YV12 port
├── simd.zig      # @Vector helpers (pavgb, absDiff, subSat, expandPairs)
└── scalar.zig    # scalar twins of the SIMD helpers (pavgbScore, toMapByte)

reference/
├── avisynth/                # original IT_YV12 0.1.03 source (read-only)
├── vapoursynth-cpp/         # upstream VS-IT @ 6fc9be8 (read-only)
└── vapoursynth-cpp-api4/    # mechanical API3→API4 port of upstream; build for bit-exact comparison

tests/integration/           # pytest suite — properties, golden hashes, upstream-compare, determinism, bit depth
scripts/                     # gen_testclip / param_grid / regen_golden / compare_upstream / compare_vivtc / ...
docs/upstream_reference.md   # design notes

Credits

• Original IT 0.051 — thejam79 (2002)
• Avisynth IT_YV12 0.1.03 — minamina (2003)
• 64-bit / 8k mod — poodle
• VapourSynth port — msg7086 (2014)
• Zig port — this repo

License

GPL-2.0-or-later (inherited from upstream). See LICENSE.