Pelorus interop ABI (vendored) — libvmaf/pelorus/¶

The Pelorus GPU pre-encode pipeline and vmafx share a small, versioned data-plane interop ABI: a self-describing per-frame metadata blob that Pelorus filters (vf_pelorus_*) write and vmafx reads for perceptually-weighted scoring. The blob rides each AVFrame as an AV_FRAME_DATA_SEI_UNREGISTERED payload, prefixed by a fixed project UUID so it round-trips a filtergraph and never collides with codec side data.

This ABI is single-sourced in Pelorus (Pelorus ADR-0103). vmafx carries a verbatim, pinned, read-only mirror of it so the two repos can build, test, and evolve independently without a submodule or a shared package. The vendoring decision is recorded in ADR-1113; the current safety re-pin and exact-mirror guard rails are recorded in ADR-1276.

What is vendored¶

The five .c files compile straight into libvmaf (CPU-only, dependency-free; registered in core/src/meson.build). deband_params.c, denoise_params.c, qp_report_csv.c, and version.c are vendored alongside interop.c because the shared conformance fixture links the deband / denoise parameter contracts, the x265 CSV QP-report reader, and the version / result-string accessors — vendoring them keeps the fixture byte-identical to Pelorus's. (qp_report_csv.c is required to link: the ABI-1.3 fixture exercises pel_x265_csv_parse.)

The only local edits¶

1. A VENDORED FROM VMAFx/pelorus@11e183ec0aedf6b3e6447fda64acbb6072a1ae60 — DO NOT EDIT banner inserted after the (unchanged) Pelorus license header.
2. Intra-Pelorus #include "pelorus/<x>.h" rewritten to #include "libvmaf/pelorus/<x>.h" so the headers resolve under core/include/. Nothing else changes.

The conformance test additionally carries a vmafx-authored (Copyright 2026 Lusoris) header instead of cloning Pelorus's. From its first vendored #include onward, its body is exact Pelorus source apart from the same include rewrite. The sync script renders that prefix canonically from the pin and ABI version, then appends the transformed body. VMAFx format and tidy scopes exclude only the manifest-owned fixture path; lint-policy changes belong in VMAFx tooling, never in the fixture.

The blob, in brief¶

A blob is a flat, pointer-free, little-endian byte image:

[16-byte UUID][PelorusSideData header (48 B)][PelorusSectionDir dir[count] (16 B each)][section payloads, each 8-byte aligned]

• Magic / identity: 8-byte "PELOR1\0\0" magic, a fixed 16-byte routing UUID (e1d7c4a2-6b93-4f08-9a55-0f3c2db17e64), and an ABI major/minor.
• Sections (append-only bits, never reused): BANDING, VARIANCE, DENOISE, FILMGRAIN, MOTION, and (ABI ≥ 1.3) QPREPORT (1.1, encoder QP / bit readback), MOTION_CONF (1.2, per-block MV confidence), and COMPLEXITY (1.3, per-frame complexity scalar — consumed by perceptual weighting, see perceptual-weight.md). Each is independently optional and gated by section_mask.
• Directory: one PelorusSectionDir{section_id, offset, size, struct_minor} per present section, so an older consumer can locate and tail-skip a newer producer's larger section.

The full struct layout lives in interop.h. Its _Static_assert size locks are compiled in every translation unit that includes the header, including the conformance test, so an accidental layout change is a build failure, not a silent corruption.

Pack / parse API (interop.h)¶

Pelorus v0.2.2 accepts a blob at any caller-buffer base alignment. The parser and packer move wire headers and directory entries through aligned local objects with memcpy; they never cast an untrusted byte address to a structured pointer.

Framing still requires header_size and each directory offset to be 8-byte aligned relative to the blob. Malformed values return PEL_ERR_ABI.

vmafx is a reader only: it never mutates a blob (single-writer invariant, Pelorus is the sole writer). The reader side ships as the perceptual pooling weights in perceptual-weight.md.

Forward / backward compatibility (R1–R6)¶

The ABI is normative; both repos depend on these rules (verbatim from interop.h):

• R1 — Append-only. New fields are added at the END of a section struct, or as a NEW section with a new bit. Never reorder, resize, or repurpose a field.
• R2 — Never remove a section bit or a field. Deprecate by documentation; the slot stays reserved forever.
• R3 — Every section is independently optional, gated by section_mask. A consumer MUST ignore bits it does not understand (forward-compat) and MUST tolerate absence of bits it does understand (back-compat).
• R4 — Explicit offsets/sizes (PelorusSectionDir) let an older consumer parse a newer producer's larger section: read min(known_size, dir.size) bytes and ignore the tail.
• R5 — Flat, pointer-free, little-endian byte image. A byte-swap path is a future, additive change gated on PELORUS_ABI_MINOR.
• R6 — PELORUS_ABI_MAJOR bumps only on a breaking change (which R1/R2 forbid for additive evolution) — in practice it never bumps. PELORUS_ABI_MINOR bumps when a new section bit or appended field lands.

The current library release is 0.2.2 and the ABI remains 1.3 (PELORUS_ABI_MAJOR=1, PELORUS_ABI_MINOR=3). Minor 1.1 added PEL_SEC_QPREPORT, 1.2 added PEL_SEC_MOTION_CONF, 1.3 added PEL_SEC_COMPLEXITY — all append-only, so the major stayed at 1 and the mirror re-pin (ADR-1120) was non-breaking. The 0.2.2 re-pin changes parser safety semantics only; it does not add or alter an ABI field or section.

Conformance fixture — the byte-compat proof¶

core/test/test_pelorus_interop.c is the same fixture both repos run. It exercises the following vectors against the vendored parser (the ABI-1.3 fixture grew the original seven to sixteen):

Run the fixture¶

A green run here proves vmafx's vendored parser is byte-identical to Pelorus's writer: a blob packed by Pelorus parses in vmafx and vice versa. The fixture is wired into the fast suite:

meson setup core/build-cpu core -Denable_cuda=false -Denable_sycl=false
ninja -C core/build-cpu
python3 scripts/ci/run_meson_test.py -- \
  -C core/build-cpu test_pelorus_interop   # all vectors, must pass

Re-syncing the mirror¶

The pin and the drift guard live in scripts/sync-pelorus-interop.sh. It reads the vendored sources from the pinned commit's git tree object (git show 11e183ec0aedf6b3e6447fda64acbb6072a1ae60:libpelorus/…), so it stays accurate even when the local Pelorus checkout's HEAD has moved past the pin. A directory that is not a Git checkout, or a checkout that lacks the exact object, fails closed.

Check and re-vendor¶

Check for drift (the CI gate). The path defaults to $PELORUS_DIR or ../pelorus:

scripts/sync-pelorus-interop.sh /path/to/pelorus

The output is OK - mirror matches pelorus@11e183ec0aedf6b3e6447fda64acbb6072a1ae60, or FAIL - mirror has drifted with a diff and exit code 1.

To re-vendor after a reviewed Pelorus ABI addition or a released parser correctness or security fix (an ABI-minor bump is not required):

1. Bump PELORUS_VENDOR_SHA in the script, in this page and in the ADR. The banners are rewritten automatically by --update.
2. Add any new Pelorus source or header to the script's render manifest and to scripts/ci/pelorus-mirror-paths.txt, plus core/src/meson.build and the test target if it must compile or link. The guard requires both path sets to match exactly.
3. Re-vendor:

scripts/sync-pelorus-interop.sh --update /path/to/pelorus

1. Confirm the mirror is clean:

scripts/sync-pelorus-interop.sh /path/to/pelorus

1. Rebuild and run the conformance fixture; it must stay green.

What the guard enforces¶

--update re-vendors both the manifest files and the complete conformance fixture:

• It regenerates the canonical Lusoris-authored prefix from the pinned commit and ABI version, then appends the Pelorus body with the pelorus/ to libvmaf/pelorus/ include rewrite.
• The drift check compares every complete rendered file byte for byte through end of file. A prefix mutation, a stale fixture pin or a missing or extra final newline is drift.
• It rejects any added or missing tracked file in the exact-mirror lint namespaces unless the manifest owns that path.

Local formatting or tidy edits therefore fail the guard instead of becoming a second implementation or silently gaining a lint exemption.

A re-sync that changes the ABI is an ADR-worthy event (a new section bit or an appended field bumps PELORUS_ABI_MINOR); ADR-1120 records the 1.0 → 1.3 re-pin as a follow-up to ADR-1113. A released parser-only correctness/security fix keeps the ABI number intact and is recorded in a new follow-up decision plus research evidence; ADR-1276 records the v0.2.2 safety re-pin while preserving ADR-1113's immutable body.