API generation¶

One definition, core/api/vmafx.toml, describes the VMAFx C API, and a generator writes every surface from it (ADR-1852): the public headers, the linker version script and export lists, the ABI layout test, the libvmaf compatibility shims, the Python binding and the reference pages. The generated files are committed; a test fails when any of them differs from what the definition produces, so a hand edit of a generated file fails the build's tests.

A second definition, api/vmafx-platform.toml, describes the gRPC services and messages of the controller and the scoring server, and the Kubernetes custom resources of the platform (ADR-2350 D13); the same generator writes their protobuf files, Go types and the Helm chart's values and schema (Platform definition, Kubernetes resources, Helm chart values).

Change the API¶

1. Edit core/api/vmafx.toml. A new entry names its header (header) and the ABI minor that introduces it (since); raise [api] abi_version (see ABI rules for which part).

2. Regenerate:

   python3 scripts/codegen/vmafx-api.py --write
   

3. Implement what the definition declares (hand-written C lives in core/src/vmafx/; ADR-1906 records the rules it follows for logging, struct sizes and references), build, and run the tests:

   python3 scripts/ci/run_meson_test.py -- -C build test_vmafx_abi_layout \
       test_vmafx_api_slice test_vmafx_api_generated_current \
       test_vmafx_api_abi_append_only test_vmafx_api_generator \
       test_vmafx_python_binding check_exported_symbols \
       test_vmafx_context test_vmafx_model test_vmafx_frame test_vmafx_score \
       test_vmafx_bitexact test_vmafx_lifetime test_vmafx_sha256
   

4. Check that the new definition is an append-only successor of the one you started from, and draft the changelog fragment:

   python3 scripts/codegen/vmafx-api.py --abi-check --against-ref origin/master
   python3 scripts/codegen/vmafx-api.py --changelog origin/master
   

   --changelog prints the text of changelog.d/added/api-<slug>.md (the symbols, types, fields, constants and options the definition gained) and of changelog.d/changed/api-<slug>.md (entries newly deprecated); pick the slug, edit the wording and commit the fragments yourself.

The generator needs Python 3.11 or newer and nothing else (tomllib from the standard library). It never runs during a normal build.

ABI rules¶

• Append-only within an ABI major (HISS-14): new functions, new fields at the end of a struct with sized = true, new constants, new flag bits and new options. Removing or renaming anything, changing a parameter list or a callback signature, reordering, retyping or resizing a field, renumbering a constant or a bit, changing since, changing an option's type or proto field number, or growing a struct that another struct embeds by value is a break.
• Before v1.0.0 the ABI is 0.x (ADR-1852 decision D2): a break needs a higher minor (0.1.0 to 0.2.0), and the pull request lists every break --abi-check reports as accepted. From 1.0.0 a break needs a higher major, ! in the pull request title and a Migration: footer.
• Additions raise abi_version. A function's since selects its linker version node (VMAFX_0.1, VMAFX_0.2, ...). Within 0.x an addition may join the current minor's node (a patch bump such as 0.1.0 to 0.1.1 is enough), so work packages that add functions in parallel do not each claim a minor; it may never join an older node. From 1.0.0 a node that shipped is frozen: an addition's since is a newer minor than the ABI it is compared with. ADR-1897 records this rule and the alternative of a new minor per addition.
• Deprecation: deprecated = { since, replacement, removal } adds the VMAFX_DEPRECATED("...") attribute to a function (define VMAFX_NO_DEPRECATION_WARNINGS to silence it), an @deprecated line to the header documentation and a note to the reference page. replacement must name a declared function, type, constant, field (Struct.field) or option.

What the definition holds¶

Every top-level entry carries header (except status codes and option groups) and since. Enum values, flag bits, struct fields and options inherit their parent's since unless they name a later one. Each header includes the headers whose types its declarations use, computed from the definition; an include cycle stops generation.

Parameter pass modes: in (value; const T * for a struct; T * for a handle), in_const (const T *), out (T *), out_handle (T **), error (VmafxError **). Scalar types: u32, u64, i32, i64, f32, f64, uptr (uintptr_t), size (size_t), ptr (void *), cstr (const char *), status.

scripts/codegen/tests/fixtures/full.toml uses every feature of the format; the generator tests render it and compile its C output.

Outputs¶

Every generated C file is already in the repository's clang-format style (long *_INIT macros sit between clang-format off / on markers) and the Python file in black's style, so formatter hooks never rewrite them.

Since the library split (ADR-1852 decision D3, ADR-2094), hide_unlisted = true: libvmafx.so.1 exports the vmafx_* functions and nothing the script does not list. The libvmaf functions live in libvmaf.so.3, generated (shim, glue) or hand-written (manual, in core/src/compat/libvmaf/) from the [[compat]] table; a backend's functions that still live in the engine are engine entries, exported through core/src/vmafx_legacy_<backend>.map in builds with that backend.

The compat table¶

Every engine translation unit is compiled with the generated core/src/vmafx/engine_names_gen.h (vmaf_engine_name_args), which names the engine's own libvmaf bodies vmaf_engine_<stem>; code that uses the libvmaf API (the compat library, the tools, black-box tests) defines VMAF_PUBLIC_NAMES. test_compat_conformance compares every compat function with its engine body.

Option groups¶

Every scoring option of every surface is one entry of an option group (ADR-2044). Groups and options are TOML array tables:

[[option_groups]]
name = "threads"
since = "0.1"
doc = "Worker threads of the feature extractors."
surfaces = ["cli", "ffmpeg", "mcp", "proto"]
mcp_tools = ["vmaf_score", "vmaf_score_encoded"]

[[option_groups.options]]
name = "threads"
type = "uint"
doc = "Worker threads of the feature extractors, capped to the hardware threads (0: score in the calling thread)."
cli = ["--threads"]
ffmpeg = "threads"
aliases = ["n_threads"]
mcp = "threads"
proto = { field = 14 }

Order matters: vmaf --help lists options in definition order and both MCP servers append the extra flags in that order. A struct with proto = "Name" becomes a proto message and an OpenAPI schema with one field per struct field (numbers in field order, so they never change); a field with no proto form (a handle, a pointer, a callback) stops generation.

The generated proto needs buf generate proto afterwards (the template in buf.gen.yaml, then python3 scripts/proto/postprocess_gen_go.py) and the OpenAPI change needs the server stubs regenerated (gen/go/AGENTS.md). buf breaking proto --against '.git#ref=refs/remotes/origin/master,subdir=proto' must stay clean.

Platform definition¶

api/vmafx-platform.toml holds the services of the platform: the scoring service VmafxScoring (package vmafx.v1) and the controller VmafxController (package vmafx.controller.v1), and the custom resources of the operator (Kubernetes resources). The generator writes one protobuf file per [[files]] entry, and buf turns those into the Go bindings under gen/go:

A field's type is a protobuf scalar (string, double, int64, bytes, ...), map<K, V> (K an integer, bool or string), a message or enum of the platform definition, or a message the core definition generates: an option group's proto_message (ScoreOptions) or a struct's proto (Provenance). A type from another file is imported, a type from another package is written with its package. Documentation keeps its own line breaks and is wrapped at 96 columns.

Names and numbers are the wire contract. Within a v1 package a change only adds: a message, an RPC, a field or an enum value with a new number. Renaming or renumbering is a break, which buf breaking refuses (see below); a break needs a v2 package beside v1. Names that predate these rules and do not follow buf's style (the service names without Service, JobStatus values without the JOB_STATUS_ prefix, Job as the answer of two RPCs) are exempted by name in buf.yaml and stay as they are.

Change a service or message¶

1. Edit api/vmafx-platform.toml.

2. Regenerate the protobuf files, then the Go bindings:

   python3 scripts/codegen/vmafx-api.py --write
   python3 scripts/codegen/proto_generate.py --write
   

   proto_generate.py runs one buf generate with the repository's buf.yaml and buf.gen.yaml. buf is the release BUF_VERSION in build-config.env, run through go run so the Go module checksum database verifies it; the protoc-gen-go and protoc-gen-go-grpc plugins are the versions go.mod pins as tools. It then adds the // SAFETY: proofs (scripts/proto/postprocess_gen_go.py) and writes every *.pb.go under gen/go, removing stale ones. The module= option puts each binding under the path of its go_package: gen/go for vmafx.v1, gen/go/controller for vmafx.controller.v1.

3. Check wire compatibility against the branch you started from:

   python3 scripts/codegen/proto_generate.py --check --breaking-against origin/master
   

   buf breaking runs with the WIRE_JSON rules: what clients send and receive in binary and JSON form must stay readable. Moving a file or its Go package is not a break; a removed or renumbered field, a changed type or a renamed enum value is.

Kubernetes resources¶

The same file declares the custom resources of the vmafx.dev/v1 API group: VmafxJob, VmafxNode, VmafxModelTraining and VmafxTenant. A [[messages]] or [[enums]] entry that names a group instead of a protobuf file is a Kubernetes type.

A field's type is string, bool, int, int32, int64, float64, Time (*metav1.Time), map<string, string>, or an enum or message of the same group. The Go name is derived from the JSON name (tenantId becomes TenantID; id, gpu, uri, url, oidc and rbac are written in capitals); go overrides it. pointer = true makes a single value a pointer, so that an explicit false or 0 survives a default. A field with a default must be optional. The validation keys become kubebuilder markers and from those the CRD schema: enum, items_enum, minimum, min_length, items_min_length, max_items, pattern, format. An enum type carries its own values, so a field of that type takes no enum.

Within v1 a resource only grows. Adding a resource, an optional field, an enum value or a short name, or widening a bound, is compatible; removing a field, version, short name or the status subresource, adding a required field, narrowing an enum, a bound, a type or a format, or changing a pattern or a default is not, and needs a new version.

Change a custom resource¶

1. Edit api/vmafx-platform.toml.

2. Regenerate the Go types, then the deepcopy code, the CRDs and the RBAC role:

   python3 scripts/codegen/vmafx-api.py --write
   python3 scripts/codegen/crd_generate.py --write
   

   vmafx-api.py writes api/vmafx/v1/groupversion_info.go and one <kind>_types.go per resource, gofmt-clean. crd_generate.py runs controller-gen, the version go.mod pins as a tool, three times: object writes api/vmafx/v1/zz_generated.deepcopy.go, crd writes deploy/helm/vmafx/crds/vmafx.dev_<plural>.yaml (the only CRD tree: the chart installs it and the operator's envtest suite loads it), and rbac writes config/rbac/role.yaml from the +kubebuilder:rbac markers of cmd/vmafx-operator. It adds the SPDX header and removes stale files.

3. Check compatibility against the branch you started from:

   python3 scripts/codegen/crd_generate.py --check --compat-against origin/master
   

4. A new RBAC marker on a reconciler changes config/rbac/role.yaml; the chart's deploy/helm/vmafx/templates/operator-rbac.yaml must then grant it too, which scripts/ci/tests/test_helm_operator_rbac.py checks.

Helm chart values¶

The same file holds the chart's values: one [[chart]] entry per key of deploy/helm/vmafx/values.yaml, in the order of that file. The generator writes values.yaml and values.schema.json from them; neither is edited by hand.

[chart_root] holds the schema's root keywords ([chart_root.schema]), the order of the top-level properties and the comment lines after the last key (values_tail); [[chart_defs]] are the schema's own $defs. The schema file has one layout: an object or array that fits on its line within 100 columns is written on one line, any other is expanded.

A $ref of k8s:<name> refers to a Kubernetes type, such as k8s:io.k8s.api.core.v1.Toleration, as the chart's minimum supported Kubernetes minor defines it. build-config.env pins that release (K8S_SCHEMA_VERSION, the last patch of the minor the deployment guide names) and the SHA-256 of each OpenAPI v3 file of its tag. scripts/codegen/k8s_openapi.py --write downloads them, checks the digests, and writes every type the definition names, and every type those reach, to api/kubernetes/openapi-subset.json, without descriptions and x-kubernetes-* extensions. The generator copies the types a schema reaches into its $defs. Kubernetes accepts fields it does not know in these types, so the schema does too; a known field must have its type, and a required field must be there.

To change a value or its schema:

1. Edit the entry in api/vmafx-platform.toml. A new key gets a new entry at its place in the file.
2. If the entry names a Kubernetes type the subset does not hold yet, run python3 scripts/codegen/k8s_openapi.py --write.
3. Regenerate: python3 scripts/codegen/vmafx-api.py --write.

Environment of the Go binaries¶

The same file lists every environment variable the Go binaries read and how the chart sets it.

The generator writes:

• cmd/<binary>/config_keys.gen.go: the binary's golusoris CompoundKeys, every key with an underscore inside a segment. golusoris turns each underscore of a VMAFX_ name into the key delimiter except in these keys.
• One table per binary, with the same columns everywhere, into the binary's page and into the Go services section of the environment reference. The chart value column lists the values the chart's entries read.
• deploy/helm/vmafx/templates/_config.gen.tpl: a helper vmafx.env.<workload> per workload holding its VMAFX_* entries with their comments and conditions at the list's indentation, and the value helpers. A template includes the helper where its environment list holds them; no other template writes a VMAFX_* entry.

To add or change a variable: edit its [[config]] entry (and the [[chart_env]] entry when the chart sets it), then run python3 scripts/codegen/vmafx-api.py --write. A variable a binary reads but the definition lacks is a missing row in every table; the binary's environment tests (env_test.go, main_test.go) read the generated compoundKeys.

Gates¶

The compiler, clang-format and linker cases of the generator tests skip, with the reason, when the tool is not installed.

The format case compares against one clang-format major only: the one the clang-format hook pins in .pre-commit-config.yaml, because other releases align macros differently (clang-format 18.1.3, the ubuntu-24.04 runner's, and 17 reject output that 18.1.8 and 19 to 23 accept). It uses VMAFX_CLANG_FORMAT when set, which must be that major or the test fails, else clang-format-<major> or clang-format on PATH; any other major makes it skip and name the version it found. The Tooling Tests job installs the pinned release from requirements/locks/tooling-tests.txt and sets VMAFX_CLANG_FORMAT, so the case always runs there. To run it locally with another system version:

python3 -m venv /var/tmp/cf && /var/tmp/cf/bin/pip install clang-format==23.1.2
VMAFX_CLANG_FORMAT=/var/tmp/cf/bin/clang-format \
    python3 -m pytest scripts/codegen/tests/test_vmafx_api_layout.py