test(tools): pin user-facing CLI text against golden transcripts

REUSE.toml

@@ -9,6 +9,14 @@ precedence = "closest"
 SPDX-FileCopyrightText = "2026 Lusoris"
 SPDX-License-Identifier = "EUPL-1.2"
 
+# The CLI golden transcripts (ADR-3402) are diff targets: no inline SPDX
+# header may precede the pinned bytes, so their terms are annotated here
+# (ADR-3401: outside contributors name themselves as holders).
+[[annotations]]
+path = ["core/tools/test/golden/*.txt"]
+precedence = "override"
+SPDX-FileCopyrightText = "2026 luoye-cpu"
+SPDX-License-Identifier = "EUPL-1.2"
 # These six files descend from Netflix/vmaf root files.  ADR-1250 requires
 # inherited work, and every fork contribution to it, to remain on the terms it
 # already carried rather than being swept into the fork-local EUPL default.

core/tools/test/golden/vmaf_help.txt

@@ -0,0 +1,189 @@
+Usage: <app> [options]
+
+Supported options:
+ --reference/-r $path:         Reference video: a .y4m file, or raw planar .yuv
+                               together with the width, height, pixel format and
+                               bit depth.
+ --distorted/-d $path:         Distorted video, in the same form as the
+                               reference.
+ --width/-w $unsigned:         Width of raw .yuv input in pixels.
+ --height/-h $unsigned:        Height of raw .yuv input in pixels.
+ --width_ref $unsigned:        Width of the raw .yuv reference in pixels, if it
+                               differs from --width. Only models that scale
+                               their inputs accept different sizes.
+ --width_dist $unsigned:       Width of the raw .yuv distorted video in pixels,
+                               if it differs from --width. Only models that
+                               scale their inputs accept different sizes.
+ --height_ref $unsigned:       Height of the raw .yuv reference in pixels, if it
+                               differs from --height. Only models that scale
+                               their inputs accept different sizes.
+ --height_dist $unsigned:      Height of the raw .yuv distorted video in pixels,
+                               if it differs from --height. Only models that
+                               scale their inputs accept different sizes.
+ --pixel_format/-p $string:    Layout of raw .yuv input: 400 (luma only), 420,
+                               422 or 444 planar, or a layout of the input
+                               format table (semi-planar, packed, or RGB
+                               converted to Y'CbCr with the rgb_* statement,
+                               ADR-2145, ADR-2146). One of:
+                               400|420|422|444|nv12|nv16|nv24|p010|p016|p210|p216|p410|p416|yuyv422|uyvy422|v210|y210|y212|xv30|xv36|vuyx|ayuv|yuv444p16msb|rgb|rgba|bgra.
+ --bitdepth/-b $unsigned:      Bits per sample of raw .yuv input, 8 to 16
+                               (implied by a layout that fixes it).
+ --check-sample-range, --check_sample_range:
+                               Refuse a frame with a sample above 2^bpc - 1 and
+                               name the plane, row, column and value (ADR-1918).
+ --color_range_ref $string:    Colour range of the reference input. One of:
+                               unknown|limited|full.
+ --color_range_dist $string:   Colour range of the distorted input. One of:
+                               unknown|limited|full.
+ --color_primaries_ref $string:
+                               Colour primaries of the reference input. One of:
+                               unknown|bt709|bt2020.
+ --color_primaries_dist $string:
+                               Colour primaries of the distorted input. One of:
+                               unknown|bt709|bt2020.
+ --color_trc_ref $string:      Transfer characteristic of the reference input.
+                               One of: unknown|bt709|smpte2084|pq.
+ --color_trc_dist $string:     Transfer characteristic of the distorted input.
+                               One of: unknown|bt709|smpte2084|pq.
+ --color_matrix_ref $string:   Matrix coefficients of the reference input. One
+                               of: unknown|bt709|bt2020nc|ictcp.
+ --color_matrix_dist $string:  Matrix coefficients of the distorted input. One
+                               of: unknown|bt709|bt2020nc|ictcp.
+ --rgb_matrix $string:         Raw rgb, rgba and bgra input: the Y'CbCr matrix
+                               of the conversion; no default, the input is
+                               refused without it (ADR-2146). One of:
+                               bt601|bt709|bt2020ncl.
+ --rgb_range $string:          Raw RGB input: the range of the R'G'B' samples;
+                               no default. One of: limited|full.
+ --rgb_transfer $string:       Raw RGB input: the transfer characteristic of the
+                               R'G'B' samples (checked, not applied); no
+                               default. One of: bt709|srgb|pq|hlg.
+ --rgb_out_range $string:      Raw RGB input: the range of the Y'CbCr frame
+                               made; limited is the range the VMAF models are
+                               trained on; no default. One of: limited|full.
+ --model/-m $params:           Model, colon-delimited: version= a built-in
+                               model, path= a model file, name= the name in the
+                               report, disable_clip, enable_transform,
+                               <feature>.<option>=<value> overloads. Several
+                               models score in one pass (repeat the option; the
+                               filter separates them with |). (default:
+                               VMAF_DEFAULT_MODEL_VERSION)
+ --backend $name:              Backend: auto uses the available ones; any other
+                               value runs that backend alone and fails when it
+                               is not available. One of:
+                               auto|cpu|cuda|sycl|hip|metal. (default: auto)
+ --no_cuda:                    Disable the CUDA backend.
+ --no_sycl:                    Disable the SYCL (oneAPI) backend.
+ --no_hip:                     Disable the HIP (ROCm) backend.
+ --no_metal:                   Disable the Metal (Apple silicon) backend.
+ --feature $string:            Additional feature extractor,
+                               name[=key=value:...] (for example psnr or
+                               cambi=full_ref=true); several may be given (the
+                               filter separates them with |). Mutually exclusive
+                               with the CTC presets.
+ --aom_ctc $version:           AOM common test conditions preset: a fixed model
+                               and feature set. One of:
+                               v1.0|v2.0|v3.0|v4.0|v5.0|v6.0|v7.0.
+ --nflx_ctc $version:          Netflix common test conditions preset: a fixed
+                               model and feature set. One of: v1.0.
+ --tiny-model, --tiny_model $path:
+                               Tiny ONNX model to load alongside the classic
+                               models.
+ --tiny-device, --tiny_device $string:
+                               ONNX Runtime execution provider of the tiny
+                               model. One of:
+                               auto|cpu|cuda|openvino|openvino-npu|openvino-cpu|openvino-gpu|coreml|coreml-ane|coreml-gpu|coreml-cpu|rocm.
+                               (default: auto)
+ --dnn-ep, --dnn_ep $string:   Alias of the tiny-model device under the ONNX
+                               Runtime name (execution provider); both set the
+                               same setting. One of:
+                               auto|cpu|cuda|openvino|openvino-npu|openvino-cpu|openvino-gpu|coreml|coreml-ane|coreml-gpu|coreml-cpu|rocm.
+ --tiny-threads, --tiny_threads $unsigned:
+                               Intra-op threads of the CPU execution provider
+                               (0: the runtime's default).
+ --tiny-fp16, --tiny_fp16:     Request fp16 input and output where the execution
+                               provider supports it.
+ --tiny-model-verify, --tiny_model_verify:
+                               Require a Sigstore bundle verification of the
+                               tiny model (cosign verify-blob) before it loads;
+                               a missing bundle, a missing cosign or a failed
+                               verification refuses the model.
+ --tiny-codec, --tiny_codec $name:
+                               Encoder of the distorted clip, required by
+                               codec-aware tiny models (fr_regressor_v2/v3),
+                               which refuse to score without it. Must be in the
+                               model sidecar's encoder_vocab; the ffprobe names
+                               h264, hevc, av1, vp9 and vvc are accepted.
+ --tiny-preset, --tiny_preset $string:
+                               Encoder preset (medium, slow, p4, 5, ...), read
+                               as the encoder defines it. Unset: ordinal 5
+                               (medium). A model trained with one preset
+                               (fr_regressor_v3) ignores it and warns.
+ --tiny-crf, --tiny_crf $unsigned:
+                               CRF or QP used for the encode, normalised as the
+                               model sidecar declares. Required with the codec
+                               and preset.
+ --tiny-resize, --tiny_resize $string:
+                               Resize filter for NCHW tiny models whose input
+                               size differs from the frame; disabled refuses the
+                               mismatch (-ERANGE). The three filters give scores
+                               about 2% apart: record the filter with the model.
+                               One of: bilinear|nearest|bicubic|disabled.
+                               (default: disabled)
+ --no-reference, --no_reference:
+                               No-reference mode; needs a no-reference tiny
+                               model. The reference becomes a formality: only
+                               the distorted picture is scored.
+ --threads $unsigned:          Worker threads of the feature extractors, capped
+                               to the hardware threads (0: score in the calling
+                               thread).
+ --frame_cnt $unsigned:        Score at most this many frames.
+ --frame_skip_ref $unsigned:   Skip this many frames at the start of the
+                               reference.
+ --frame_skip_dist $unsigned:  Skip this many frames at the start of the
+                               distorted video.
+ --no_prediction/-n:           Extract features only; no model score.
+ --cpumask/-c $bitmask:        Bitmask of CPU instruction sets the extractors
+                               must not use.
+ --gpumask $bitmask:           Bitmask of GPU operations the extractors must not
+                               use.
+ --sycl_device $unsigned:      SYCL GPU by index (unset: selected
+                               automatically).
+ --hip_device $unsigned:       HIP GPU by index (opt-in: HIP is off unless this
+                               or --backend hip is given).
+ --metal_device $unsigned:     Metal GPU by index (opt-in: Metal is off unless
+                               this or --backend metal is given).
+ --subsample $unsigned:        Score every n-th frame (1: every frame).
+                               (default: 1)
+ --precision $spec:            Score precision: N (1 to 17) writes %.<N>g; max
+                               or full write %.17g (round-trip lossless); legacy
+                               writes %.6f (Netflix-compatible). The scoring
+                               server returns lossless scores unless asked
+                               otherwise. One of:
+                               legacy|max|full|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17.
+                               (default: legacy)
+ --output/-o $path:            Report file.
+ --xml:                        Report format; json and xml carry the backend
+                               receipt. xml (default)
+ --json:                       Report format; json and xml carry the backend
+                               receipt. json
+ --csv:                        Report format; json and xml carry the backend
+                               receipt. csv
+ --sub:                        Report format; json and xml carry the backend
+                               receipt. sub
+ --provenance-sidecar:         Also write the provenance record to
+                               <output>.provenance.json; CSV and SUB reports
+                               carry it nowhere else (RC4 WP5).
+ --netflix-compat, --netflix_compat:
+                               Restore the Netflix-upstream defaults: CPU
+                               backend, %.6f precision, vmaf_v0.6.1 model.
+ --quiet/-q:                   Disable the FPS meter when run in a terminal.
+ --version/-v:                 Print the version and exit.
+ --list-backends:              Print the scoring backends this binary was built
+                               with and which of them initialise here, as JSON,
+                               and exit (ADR-1874).
+ --help:                       Print this message and exit.
+ --verify-provenance $report:  Re-run the configuration a JSON report records
+                               and compare every configuration field and score
+                               bit for bit; exits nonzero naming the first
+                               difference (RC4 WP5).

core/tools/test/golden/vmaf_per_shot_help.txt

@@ -0,0 +1,18 @@
+Usage: vmaf-perShot --reference REF.yuv --width W --height H --pixel_format 420|422|444 --bitdepth 8 --output PLAN [options]
+
+Required:
+  -r, --reference PATH       reference YUV file
+  -w, --width    N           frame width in pixels
+  -h, --height   N           frame height in pixels
+  -p, --pixel_format 420|422|444  planar YUV subsampling
+  -b, --bitdepth 8|10|12|16  planar YUV bit depth
+  -o, --output   PATH        per-shot plan output
+
+Optional:
+  -t, --target-vmaf X        target VMAF score [default 90]
+  -m, --crf-min N            minimum CRF clamp [default 18]
+  -M, --crf-max N            maximum CRF clamp [default 35]
+  -d, --diff-threshold X     shot-detector frame-diff cutoff
+  -f, --format csv|json      output format [default csv]
+  -F, --frames   N           maximum frames to scan (0 = all) [default 0]
+  -H, --help                 print this message

core/tools/test/golden/vmaf_roi_help.txt

@@ -0,0 +1,20 @@
+usage: vmaf-roi --reference REF.yuv --width W --height H \
+                --frame N --output qpfile [options]
+
+Required:
+  --reference PATH         Raw planar YUV input.
+  --width W                Frame width in luma samples.
+  --height H               Frame height in luma samples.
+  --frame N                0-based frame index to score.
+  --output PATH            Sidecar file (use '-' for stdout).
+
+Optional:
+  --pixel_format 420|422|444   Default 420.
+  --bitdepth 8|10|12|16        Default 8.
+  --ctu-size N                 8..128, default 64 (x265 max-ctu).
+  --encoder x265|svt-av1       Default x265.
+  --strength F                 QP-offset gain, default 6.0.
+  --saliency-model PATH        Optional ONNX [1,1,H,W] luma->[0,1].
+                               If absent, a center-weighted radial
+                               placeholder is used (smoke-test only).
+  -h, --help                   Show this help.

core/tools/test/golden/vmaf_vpl_help.txt

@@ -0,0 +1,13 @@
+Usage: <app> --ref <file> --dis <file> [options]
+
+Options:
+  --ref <file>        Reference video file
+  --dis <file>        Distorted video file
+  --model <name>      VMAF model name (default: vmaf_v1.0.16_3d0h)
+  --frames <N>        Max frames to process (0 = all)
+  --device <N>        SYCL device index (default: 0)
+  --render-node <path> VA-API render node (default: /dev/dri/renderD128)
+  --fallback          Use host upload if zero-copy import fails
+  --help              Show this help
+
+Pipeline: VPL decode → VA surface → DMA-BUF → Level Zero → SYCL → VMAF

core/tools/test/meson.build

@@ -317,3 +317,56 @@ test('test_vmaf_raw_layouts', test_vmaf_raw_layouts,
          'MESON_BUILD_ROOT=' + meson.project_build_root(),
          'MESON_SOURCE_ROOT=' + meson.project_source_root(),
      ])
+
+# ADR-3402 — the user-facing text of the vmaf CLI is a contract: help, the
+# --version format, option-error transcripts and the yuv geometry refusals
+# are diffed against golden transcripts served by the real binary
+# (issue #3214 rows C15-01..C15-10). The vmafx alias is asserted to serve
+# byte-identical help and its own VMAFX version line.
+test_vmaf_cli_text_golden = find_program('test_vmaf_cli_text_golden.sh')
+test('test_vmaf_cli_text_golden', test_vmaf_cli_text_golden,
+     suite : ['fast'],
+     depends : [vmaf, vmafx],
+     workdir : meson.project_build_root(),
+     env: [
+         'MESON_BUILD_ROOT=' + meson.project_build_root(),
+         'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+     ],
+     timeout : 120)
+
+# ADR-3402 — the hand-written usage texts of the vmaf_roi / vmaf_vpl
+# sidecars are pinned the same way (issue #3214 rows C15-12/C15-13), as two
+# separate tests so the roi golden is a real PASS in every build; the vpl
+# test skips (exit 77) outside Linux SYCL builds, where its golden is
+# verified.
+test_vmaf_roi_usage = find_program('test_vmaf_roi_usage.sh')
+test('test_vmaf_roi_usage', test_vmaf_roi_usage,
+     suite : ['fast'],
+     depends : [vmaf_roi],
+     workdir : meson.project_build_root(),
+     env: [
+         'MESON_BUILD_ROOT=' + meson.project_build_root(),
+         'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+     ],
+     timeout : 120)
+test_vmaf_vpl_usage = find_program('test_vmaf_vpl_usage.sh')
+if vmaf_vpl_ok
+    test('test_vmaf_vpl_usage', test_vmaf_vpl_usage,
+         suite : ['fast'],
+         depends : [vmaf_vpl],
+         workdir : meson.project_build_root(),
+         env: [
+             'MESON_BUILD_ROOT=' + meson.project_build_root(),
+             'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+         ],
+         timeout : 120)
+else
+    test('test_vmaf_vpl_usage', test_vmaf_vpl_usage,
+         suite : ['fast'],
+         workdir : meson.project_build_root(),
+         env: [
+             'MESON_BUILD_ROOT=' + meson.project_build_root(),
+             'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+         ],
+         timeout : 120)
+endif