Research-0752: Phase 4b.8 — libvmaf C ABI Break Scoping¶

Status: Draft Date: 2026-05-29 Companion ADR: ADR-0767

1. Current C ABI surface — complete symbol inventory¶

1.1 Core context + lifecycle (libvmaf.h)¶

Struct VmafConfiguration: {VmafLogLevel, unsigned n_threads, unsigned n_subsample, uint64_t cpumask, uint64_t gpumask} — pass-by-value; adding fields is a binary break.

Struct VmafPictureConfiguration: anonymous sub-struct {w,h,bpc,pix_fmt} + pic_cnt — same pass-by-value break risk.

1.2 Picture surface (picture.h)¶

1.3 Model surface (model.h)¶

1.4 Feature dictionary surface (feature.h)¶

1.5 CUDA backend (libvmaf_cuda.h)¶

1.6 SYCL backend (libvmaf_sycl.h)¶

1.7 Vulkan backend (libvmaf_vulkan.h)¶

1.8 HIP backend (libvmaf_hip.h) — scaffold only¶

1.9 Metal backend (libvmaf_metal.h)¶

1.10 DNN surface (dnn.h)¶

1.11 MCP surface (libvmaf_mcp.h)¶

2. FFmpeg-patches entry points consumed¶

The 15 patches (0001–0015) in ffmpeg-patches/ consume the following public symbols:

Any rename, signature change, or removal in the v4 break requires a corresponding patch update.

3. Proposed breaking changes for libvmaf.so.4 / v4.0.0¶

3.1 Remove vmaf_write_output (superseded by vmaf_write_output_with_format)¶

vmaf_write_output is functionally subsumed by vmaf_write_output_with_format (ADR-0119). In v4 it should be removed, with a trivial inline wrapper available for the transition window if desired (deprecated header shim in the v4.0 series).

3.2 Remove vmaf_model_load by version-string lookup¶

vmaf_model_load(model, cfg, "vmaf_v0.6.1") is a magic-string look-up into the built-in model registry. For v4, replace with:

int vmaf_model_load_builtin(VmafModel **model, VmafModelConfig *cfg, const void *handle);

where handle comes from vmaf_model_version_next. This makes the API self-consistent (iterate, then load) and removes the fragile string→path resolution in the library. The iterator API already exists; v4 removes the bypass.

3.3 Change configuration structs from pass-by-value to pass-by-pointer¶

VmafConfiguration, VmafPictureConfiguration, VmafCudaPictureConfiguration, VmafSyclPictureConfiguration, VmafVulkanPictureConfiguration, and VmafVulkanConfiguration are all passed by value. Adding any field to any of these structs is a silent binary break even in a minor version. In v4:

int vmaf_init(VmafContext **vmaf, const VmafConfiguration *cfg);
int vmaf_preallocate_pictures(VmafContext *vmaf, const VmafPictureConfiguration *cfg);
/* … same for all GPU configuration structs */

This is the standard convention used by every GPU backend added after the original API (SYCL state, Vulkan state, HIP state all take config by value but their *Configuration structs were small enough to avoid immediate pain). The v4 break is the forcing function to fix all of them atomically.

3.4 Normalize destroy/free/close return types¶

vmaf_model_destroy, vmaf_model_collection_destroy, vmaf_dnn_session_close, vmaf_sycl_profiling_disable, vmaf_sycl_profiling_print, vmaf_sycl_dmabuf_free all return void. All other lifecycle functions return int. In v4, align to int returns everywhere so callers can detect partial cleanup failures (double-free detection, CUDA stream drain failure, etc.).

3.5 Rename vmaf_sycl_picture_fetch → vmaf_sycl_fetch_preallocated_picture¶

Naming inconsistency vs the CPU and CUDA equivalents (vmaf_fetch_preallocated_picture, vmaf_cuda_fetch_preallocated_picture). Low risk, trivially scripted sed-patch for all consumers.

3.6 Remove vmaf_read_pictures_sycl and vmaf_flush_sycl from libvmaf.h namespace¶

These SYCL-specific entry points (vmaf_read_pictures_sycl, vmaf_flush_sycl) reside conceptually in the SYCL backend but were placed in the base header namespace. Move them to libvmaf_sycl.h for consistency.

3.7 Introduce VMAF_MODEL_FLAG_DEPRECATED_CLIP and remove VMAF_MODEL_FLAG_DISABLE_CLIP¶

The DISABLE_CLIP flag was introduced for SVM model tuning. Under the DNN surface (ADR-0519), score clipping is irrelevant. For v4, merge clip control into a single VmafModelOptions struct attached to VmafModelConfig, rather than a bitmask, enabling boolean clarity and future fields without bit-width pressure.

3.8 Expose VmafPicture.priv size contract¶

VmafPicture.priv is typed void* and currently opaque. In v4, rename to _reserved and add a size_t priv_capacity field to the struct to make the contract visible to embedders (e.g. ffmpeg allocates its own LIBVMAFContext which embeds VmafPicture objects directly).

3.9 Add vmaf_context_get_backend query¶

Currently there is no public way to ask a live VmafContext which GPU backend (if any) is active. v4 adds:

typedef enum VmafBackend {
    VMAF_BACKEND_CPU     = 0,
    VMAF_BACKEND_CUDA    = 1,
    VMAF_BACKEND_SYCL    = 2,
    VMAF_BACKEND_VULKAN  = 3,
    VMAF_BACKEND_HIP     = 4,
    VMAF_BACKEND_METAL   = 5,
} VmafBackend;

int vmaf_context_get_backend(const VmafContext *vmaf, VmafBackend *out);

This is a v4 addition (not a removal), but it replaces the current pattern where callers must track the backend externally.

4. Major version bump: libvmaf.so.4 / VMAFx v4.0.0¶

• soname changes from libvmaf.so.3 → libvmaf.so.4.
• meson.build version block changes to 4.0.0; VMAF_API_VERSION_MAJOR macro becomes 4.
• release-please already targets v3.x.y-lusoris.N; in the v4 PR it must be bumped to v4.0.0-lusoris.1 with a commit message feat!: (BREAKING CHANGE footer) to trigger the major release.
• The library continues to install as libvmaf.so (unversioned symlink) and libvmaf.so.4; the .3.x.y versioned file disappears from new builds. Distro packagers must declare Breaks: libvmaf3.

5. ffmpeg-patches rewrite plan¶

Per CLAUDE.md §12 r14, all 15 patches must be updated in the same PR as the ABI break.

Approach: the patches are applied as a stack against the n8.2 base (per ADR-0717 / PR #36 which pinned ffmpeg n8.2). A v4 ABI break triggers a rebase of the entire stack:

1. scripts/ffmpeg-patches/rebase-onto-n8.2.sh (existing helper) — used to verify the current state.
2. Each changed symbol listed in §2 must be updated in the relevant patch: renamed functions, pointer-ified config structs, void→int return types.
3. 0001 and all filters that call vmaf_write_output directly switch to vmaf_write_output_with_format.
4. 0003 / 0005 adapt to the moved vmaf_read_pictures_sycl / vmaf_flush_sycl include path.
5. All config-by-pointer changes require &cfg on the callsite.
6. After rebase, run the series-replay gate (git am --3way in a clean n8.2 checkout) — per CLAUDE.md §12 r14, git apply --check is an insufficient gate.

The /refresh-ffmpeg-patches skill is the correct tool to execute this once the v4 header changes are committed to master.

6. Migration guide outline (libvmaf.so.3 → libvmaf.so.4)¶

Compile-time detection: callers can #if VMAF_API_VERSION_MAJOR >= 4 for dual-version source compatibility.

Symbol-level migration script (to be provided in scripts/migration/v3-to-v4.sed):

s/vmaf_write_output(\([^,]*\), \([^,]*\), \([^)]*\))/vmaf_write_output_with_format(\1, \2, \3, NULL)/g
s/vmaf_sycl_picture_fetch/vmaf_sycl_fetch_preallocated_picture/g
s/vmaf_model_destroy(/vmaf_model_destroy(/g  # int return — add (void) cast for ignored return

7. Test plan¶

7.1 Netflix golden assertions — unaffected¶

The 3 Netflix golden-data test pairs (src01, checkerboard_1px, checkerboard_10px) are CLI tests exercised by make test-netflix-golden. They go through the CLI binary, not the C ABI directly. A correct v4 implementation with the CLI adapted will continue to produce identical scores. These assertions are never modified.

7.2 C unit tests in core/test/¶

The existing C unit tests in core/test/ call the public C API directly. Each test file that calls any renamed/removed entry point will fail to compile against the v4 headers — this is the intended compile-time signal that the PR is complete. Test files must be updated in the same PR.

7.3 New v4 ABI smoke tests¶

A new test suite core/test/test_vmaf_v4_api.c should cover:

• vmaf_init with pointer-style config.
• vmaf_write_output_with_format replaces the v3 vmaf_write_output path.
• vmaf_model_version_next + vmaf_model_load_builtin round-trip.
• vmaf_context_get_backend returns VMAF_BACKEND_CPU on a default-init context.
• void→int return paths return 0 on success.

7.4 ffmpeg-patches series replay gate¶

git -C /path/to/ffmpeg-8 reset --hard n8.2
for p in ffmpeg-patches/0001-*.patch ffmpeg-patches/0002-*.patch ...; do
    git -C /path/to/ffmpeg-8 am --3way "$p" || break
done
make -C /path/to/ffmpeg-8 -j$(nproc) libavfilter/vf_libvmaf.o

Must compile clean against the v4 header install path.

7.5 Cross-backend parity gate¶

After the ABI break, run /cross-backend-diff on the Netflix golden 576x324 pair across all backends (CPU, CUDA, SYCL, Vulkan). The per-frame per-feature ULP divergence must remain within the tolerances established by ADR-0214. The config-by-pointer change must not introduce any numeric delta vs the v3 baseline.

8. Scope exclusions (DO NOT implement in this PR)¶

• No changes to internal (non-VMAF_EXPORT) symbols.
• No changes to the Python harness (compat/python-vmaf/); it calls the CLI, not the C ABI.
• No changes to .onnx model files or the model registry format.
• No changes to meson_options.txt build flags — those are addressed in a separate Phase 4b PR.
• The vmaf_mcp_* surface is young enough that the config-by-pointer rule is already followed internally; no MCP symbol renames are needed.
• The HIP backend is scaffold-only; no HIP-specific changes beyond config-ptr alignment.