feat(api): split libvmaf into libvmafx.so.1 and a compat libvmaf.so.3 on the VMAFx API (RC4 WP6)

.config/clang-tidy/measured-sources.txt

@@ -11,6 +11,16 @@ compat/python-vmaf/matlab/strred/matlabPyrTools/MEX/range2.c
 compat/python-vmaf/matlab/strred/matlabPyrTools/MEX/upConv.c
 compat/python-vmaf/matlab/strred/matlabPyrTools/MEX/wrap.c
 core/src/arm/cpu.c
+core/src/compat/libvmaf/backend_absent_hip.c
+core/src/compat/libvmaf/backend_absent_metal.c
+core/src/compat/libvmaf/context.c
+core/src/compat/libvmaf/dnn.c
+core/src/compat/libvmaf/libvmaf_gen.c
+core/src/compat/libvmaf/mcp.c
+core/src/compat/libvmaf/model.c
+core/src/compat/libvmaf/picture.c
+core/src/compat/libvmaf/score.c
+core/src/compat/libvmaf/status_errno_gen.c
 core/src/compat/path_utf8.c
 core/src/conversion_context.c
 core/src/conversion_policy.c
@@ -321,8 +331,11 @@ core/src/sycl/picture_sycl.cpp
 core/src/sycl/scratch_check.cpp
 core/src/thread_locale.cpp
 core/src/thread_pool.c
+core/src/vmafx/bridge.c
 core/src/vmafx/compat_libvmaf_gen.c
 core/src/vmafx/context.c
+core/src/vmafx/context_frames.c
+core/src/vmafx/convert.c
 core/src/vmafx/device.c
 core/src/vmafx/device_context.c
 core/src/vmafx/error.c
@@ -334,6 +347,7 @@ core/src/vmafx/frame_import.c
 core/src/vmafx/frame_import_admit.c
 core/src/vmafx/frame_import_hooks.c
 core/src/vmafx/frame_pool.c
+core/src/vmafx/mcp_server.c
 core/src/vmafx/model.c
 core/src/vmafx/options.c
 core/src/vmafx/provenance.c
@@ -348,8 +362,10 @@ core/src/vmafx/sha256.c
 core/src/vmafx/sized.c
 core/src/vmafx/status_gen.c
 core/src/vmafx/submit.c
+core/src/vmafx/tiny_model.c
 core/src/x86/cpu.c
 core/test/barten_csf_cxx.cpp
+core/test/compat_conformance_table_gen.c
 core/test/dnn/test_dnn_session_api.c
 core/test/dnn/test_ep_fp16.c
 core/test/dnn/test_mobilesal_run.c
@@ -407,6 +423,9 @@ core/test/test_cli_parse.c
 core/test/test_cli_parse_long_only_args.c
 core/test/test_collector_owns_mounted_model.c
 core/test/test_compat_clz.c
+core/test/test_compat_conformance.c
+core/test/test_compat_conformance_api.c
+core/test/test_compat_conformance_scoring.c
 core/test/test_context.c
 core/test/test_conversion_policy.c
 core/test/test_convolution_edge_small.c
@@ -784,6 +803,7 @@ core/test/test_vmafx_bitexact.c
 core/test/test_vmafx_context.c
 core/test/test_vmafx_exactness.c
 core/test/test_vmafx_frame.c
+core/test/test_vmafx_frame_input.c
 core/test/test_vmafx_import_api.c
 core/test/test_vmafx_import_bitexact.c
 core/test/test_vmafx_import_fence.c

.github/workflows/go-ci.yml

@@ -35,7 +35,7 @@ jobs:
     env:
       # pkg/libvmaf intentionally has no implicit -lvmaf fallback: every build
       # selects the just-built fork library instead of a runner's distro copy.
-      CGO_LDFLAGS: -L${{ github.workspace }}/core/build-cpu/src -lvmaf -lm
+      CGO_LDFLAGS: -L${{ github.workspace }}/core/build-cpu/src -lvmaf -lvmafx -lm
       LD_LIBRARY_PATH: ${{ github.workspace }}/core/build-cpu/src
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

.github/workflows/tests-and-quality-gates.yml

@@ -862,7 +862,8 @@ jobs:
         # Meson's object directory libvmaf.so.<version>.p/.
         working-directory: core/build-mcp
         run: |
-          find src -maxdepth 1 -name 'libvmaf.so*' \( -type f -o -type l \) > "${RUNNER_TEMP}/vmaf-cli.list"
+          find src -maxdepth 1 \( -name 'libvmaf.so*' -o -name 'libvmafx.so*' \) \( -type f -o -type l \) \
+            > "${RUNNER_TEMP}/vmaf-cli.list"
           tar -cf "${RUNNER_TEMP}/vmaf-cli.tar" tools/vmaf -T "${RUNNER_TEMP}/vmaf-cli.list"
 
       - name: Upload the vmaf CLI for the vmaf-tune suite
@@ -879,10 +880,15 @@ jobs:
         # silently wire a transport without flipping the expectations.
         # The test is registered as `test_mcp_smoke` in core/test/
         # meson.build (no suite tag — it lands in the default suite).
+        # The libvmaf compat checks run here too, because only this build
+        # has the vmaf_mcp_* compat functions (ADR-2094): their conformance
+        # against the engine's bodies and the export list with them.
         working-directory: core
         run: >-
           python3 ../scripts/ci/run_meson_test.py --
-          -C build-mcp test_mcp_smoke --print-errorlogs
+          -C build-mcp test_mcp_smoke test_compat_conformance
+          check_exported_symbols check_exported_symbols_libvmaf
+          --print-errorlogs
 
       - name: Set up Python venv + install vmaf-mcp[dev]
         # The pyproject ships a `dev` extras group (pytest +

.github/workflows/upstream-consumers.yml

@@ -0,0 +1,146 @@
+name: Upstream Consumers
+
+# Unpatched upstream FFmpeg and GStreamer built against the freshly installed
+# libvmaf (the compat library libvmaf.so.3 on libvmafx.so.1, ADR-1852 decision
+# D3) must give the same scores as the vmaf CLI and, on a pull request, as the
+# base commit's library. See docs/development/upstream-consumers.md.
+on:
+  push:
+    branches: [master]
+    paths:
+      - "core/**"
+      - "build-config.env"
+      - "scripts/ci/upstream-*.sh"
+      - "scripts/ci/upstream_consumer_scores.py"
+      - ".github/workflows/upstream-consumers.yml"
+  pull_request:
+    branches: [master]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "core/**"
+      - "build-config.env"
+      - "scripts/ci/upstream-*.sh"
+      - "scripts/ci/upstream_consumer_scores.py"
+      - ".github/workflows/upstream-consumers.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: upstream-consumers-${{ github.event_name }}-${{ github.ref == 'refs/heads/master' && github.sha || github.ref }}
+  cancel-in-progress: true
+
+env:
+  DEBIAN_FRONTEND: noninteractive
+
+jobs:
+  # ADR-2169: the tier decides; the consumers build upstream FFmpeg and GStreamer
+  # like the FFmpeg lanes, so they run at the full tier only (master push,
+  # dispatch, fork pull request, `ci: full`).
+  tier:
+    name: CI tier (Upstream Consumers)
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    permissions:
+      contents: read
+      pull-requests: read
+    uses: ./.github/workflows/ci-tier.yml
+
+  consumers:
+    needs: tier
+    if: needs.tier.outputs.full == 'true'
+    name: Upstream Consumers
+    runs-on: ubuntu-26.04
+    timeout-minutes: 45
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: 3.14.8
+
+      - name: Install meson and ninja
+        run: python -m pip install --require-hashes -r requirements/locks/build.txt
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo -E apt-get -yq install --no-install-recommends \
+            nasm pkg-config git libglib2.0-dev \
+            libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
+            gstreamer1.0-tools gstreamer1.0-plugins-base gstreamer1.0-plugins-bad
+
+      # The 576x324 Netflix pair (D24), fetched the way the Python harness
+      # fetches its fixtures (compat/python-vmaf/config.py, VMAF_RESOURCE_ROOT).
+      - name: Fetch the 576x324 test pair
+        run: |
+          set -euo pipefail
+          root="https://github.com/Netflix/vmaf_resource/raw/master/python/test/resource/yuv"
+          mkdir -p python/test/resource/yuv
+          for name in src01_hrc00_576x324.yuv src01_hrc01_576x324.yuv; do
+            curl --fail --location --silent --show-error --max-time 300 \
+              -o "python/test/resource/yuv/$name" "$root/$name"
+          done
+
+      # CPU build, no ONNX Runtime and no LTO: the consumers only need the C API.
+      - name: Build and install libvmaf (this commit)
+        run: |
+          set -euo pipefail
+          meson setup build core --buildtype release --prefix "$RUNNER_TEMP/prefix" \
+            -Denable_dnn=disabled -Db_lto=false -Denable_cuda=false \
+            -Denable_sycl=false -Denable_hip=false -Denable_metal=disabled
+          ninja -C build -j"$(nproc)"
+          ninja -C build install
+
+      # A pull request is also scored against the base commit's library by the
+      # same consumer binaries: ABI and score identity across the change.
+      - name: Build and install libvmaf (base commit)
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          set -euo pipefail
+          git worktree add --detach "$RUNNER_TEMP/base-src" "$BASE_SHA"
+          meson setup "$RUNNER_TEMP/base-build" "$RUNNER_TEMP/base-src/core" --buildtype release \
+            --prefix "$RUNNER_TEMP/prefix-base" \
+            -Denable_dnn=disabled -Db_lto=false -Denable_cuda=false \
+            -Denable_sycl=false -Denable_hip=false -Denable_metal=disabled
+          ninja -C "$RUNNER_TEMP/base-build" -j"$(nproc)"
+          ninja -C "$RUNNER_TEMP/base-build" install
+
+      - name: Upstream FFmpeg
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          args=(--prefix "$RUNNER_TEMP/prefix" --against-cli --work "$RUNNER_TEMP/consumers")
+          if [ "$EVENT_NAME" = pull_request ]; then
+            args+=(--reference-prefix "$RUNNER_TEMP/prefix-base")
+          fi
+          scripts/ci/upstream-ffmpeg-compat.sh "${args[@]}"
+
+      - name: Upstream GStreamer
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          args=(--prefix "$RUNNER_TEMP/prefix" --against-cli --work "$RUNNER_TEMP/consumers")
+          if [ "$EVENT_NAME" = pull_request ]; then
+            args+=(--reference-prefix "$RUNNER_TEMP/prefix-base")
+          fi
+          scripts/ci/upstream-gstreamer-compat.sh "${args[@]}"
+
+      - name: Upload score files
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: upstream-consumer-scores
+          path: |
+            ${{ runner.temp }}/consumers/*.json
+            ${{ runner.temp }}/consumers/*.log
+          if-no-files-found: ignore

Dockerfile.go-server

@@ -96,9 +96,10 @@ RUN meson setup /build core \
 # The SONAME chain only: the glob would also take Meson's object directory
 # libvmaf.so.3.0.0.p/.
 RUN mkdir -p /dist/lib/pkgconfig /dist/bin /dist/model \
-    && find /build/src -maxdepth 1 -name 'libvmaf.so*' \( -type f -o -type l \) \
-        -exec cp -a {} /dist/lib/ \; \
+    && find /build/src -maxdepth 1 \( -name 'libvmaf.so*' -o -name 'libvmafx.so*' \) \
+        \( -type f -o -type l \) -exec cp -a {} /dist/lib/ \; \
     && cp /build/meson-private/libvmaf.pc /dist/lib/pkgconfig/libvmaf.pc \
+    && cp /build/meson-private/libvmafx.pc /dist/lib/pkgconfig/libvmafx.pc \
     && cp /build/tools/vmaf /dist/bin/ \
     && ln -s vmaf /dist/bin/vmafx \
     && cp -r model/. /dist/model/
@@ -139,7 +140,7 @@ COPY . .
 RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
     --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
     CGO_ENABLED=${CGO_ENABLED} \
-    CGO_LDFLAGS="-L/usr/local/lib -lvmaf -lm" \
+    CGO_LDFLAGS="-L/usr/local/lib -lvmaf -lvmafx -lm" \
     go build \
         -trimpath \
         -ldflags "-s -w -X github.com/VMAFx/vmafx/pkg/version.version=${VMAFX_VERSION}" \

Makefile

@@ -847,13 +847,13 @@ node-bpf:
 
 go-build: node-bpf
 	@command -v go >/dev/null || { echo "go not found — install the version declared by go.mod (https://go.dev/dl/)"; exit 1; }
-	CGO_LDFLAGS="-L$(CURDIR)/core/build-cpu/src -lvmaf -lm" \
+	CGO_LDFLAGS="-L$(CURDIR)/core/build-cpu/src -lvmaf -lvmafx -lm" \
 	LD_LIBRARY_PATH="$(CURDIR)/core/build-cpu/src$${LD_LIBRARY_PATH:+:$$LD_LIBRARY_PATH}" \
 	go build ./...
 
 go-test: node-bpf
 	@command -v go >/dev/null || { echo "go not found — install the version declared by go.mod (https://go.dev/dl/)"; exit 1; }
-	CGO_LDFLAGS="-L$(CURDIR)/core/build-cpu/src -lvmaf -lm" \
+	CGO_LDFLAGS="-L$(CURDIR)/core/build-cpu/src -lvmaf -lvmafx -lm" \
 	LD_LIBRARY_PATH="$(CURDIR)/core/build-cpu/src$${LD_LIBRARY_PATH:+:$$LD_LIBRARY_PATH}" \
 	go test ./...
 
@@ -874,7 +874,7 @@ go-fix-check:
 
 go-ort-runner:
 	@command -v go >/dev/null || { echo "go not found — install the version declared by go.mod (https://go.dev/dl/)"; exit 1; }
-	CGO_LDFLAGS="-L$(CURDIR)/core/build-cpu/src -lvmaf -lm" \
+	CGO_LDFLAGS="-L$(CURDIR)/core/build-cpu/src -lvmaf -lvmafx -lm" \
 	LD_LIBRARY_PATH="$(CURDIR)/core/build-cpu/src$${LD_LIBRARY_PATH:+:$$LD_LIBRARY_PATH}" \
 	go build -o vmafx-ort-runner ./cmd/vmafx-ort-runner