ffmpeg-patches

One shared FFmpeg patch series for VMAFx projects: fixes tracked against FFmpeg master and sent upstream; consumers carry only their own feature patches.

Praetor manages this repository's declared governance policy. This managed block records adoption state; it is not a verification certificate.

Verification: make verify-all runs the repository's configured verification cascade.

HISS Audit: praetorctl audit enforces policy, generated-surface integrity, and the debt ratchet.

Context Sync: praetorctl compile-context --verify verifies every generated agent context against AGENTS.md.

Debt Baseline: .standards-baseline.json anchors the debt ratchet at 0 recorded infractions; audit forbids growth.

How it works

The series is a list of FFmpeg fixes in git format-patch form, applied in order onto one pinned FFmpeg release. Every fix is also sent upstream. When upstream merges it and a release containing it is pinned, the patch is dropped.

Consumers apply this series first and their own feature patches on top:

• VMAFx/vmafx
• VMAFx/pelorus

A fix lives here once. A consumer does not carry its own copy.

Layout

Path	Role
base.env	Pinned FFmpeg release: remote, tag and the commit the tag must peel to
series.txt	Patch order; the series is cumulative
patches/NNNN-slug.patch	One fix, generated by git format-patch
patches/NNNN-slug.toml	Its metadata: status, upstream link, consumers, origin
scripts/series.py	check, apply, export, the coverage and warnings gates and release notes

Metadata keys:

• status: unsubmitted, submitted, merged or rejected
• upstream: link to the FFmpeg pull request or patch; required unless unsubmitted
• consumers: projects that need the fix; every consumer still applies the whole series
• origin, notes: where the patch came from, and anything a maintainer must know

The series carries one form of each patch: the one for the pinned release. The pull request linked in upstream is the FFmpeg master form.

Apply the series

. ./base.env
git clone --branch "$FFMPEG_TAG" --depth 1 "$FFMPEG_REMOTE" ffmpeg
test "$(git -C ffmpeg rev-parse HEAD)" = "$FFMPEG_COMMIT"
python3 scripts/series.py apply --expect-base ffmpeg

apply runs git am --3way per patch without your git configuration and prints one result per patch:

• applied: the patch applied
• conflict: it did not; the run stops unless --keep-going is given
• upstream: its added lines are already in the tree, so it is a drop candidate; on the pinned release this is an error

Change a patch

1. Apply the series onto the pinned release, as above.
2. Commit, amend or reorder in that checkout. Keep FFmpeg's commit message style and add a Signed-off-by trailer.
3. Regenerate: python3 scripts/series.py export ffmpeg. Metadata follows its patch when the number changes.
4. Write or update patches/NNNN-slug.toml and run make test.

Checks

Every pull request runs:

• make test: series check, ruff, REUSE and the unit tests of scripts/series.py
• apply on the pinned release, byte-identical regeneration, an FFmpeg build with the GPL components, Vulkan, NVENC and VAAPI enabled and the FATE tests that need no samples
• a coverage gate: every C file the series changes must appear as compiled (CC line) in the build log, so a file in a component the configuration leaves out fails the run instead of passing the warning gate unseen; included *_template.c files are not checked, and zero checked files fail
• a warning gate: any compiler warning in a file the series changes fails the run; warnings elsewhere in FFmpeg are counted in the summary. On a tree that applies the series to another upstream commit, such as FFmpeg master, series.py warnings TREE LOG --base <commit> names that commit, so upstream changes are not counted as the series' own

A nightly run applies the series onto FFmpeg master. It reports conflicts and drop candidates, and fails only when the tool itself cannot run.

Releases

A tag vX.Y.Z publishes a release; vX.Y.Z-rc.N publishes a prerelease. release.yml first runs the full gate on the tagged commit, then release-build.yml builds and signs these files:

• ffmpeg-patches-<tag>.tar.gz: make dist output, the series as committed, with scripts/series.py; the same commit always gives the same bytes
• ffmpeg-patches-<tag>.spdx.json: SPDX SBOM of the tarball
• ffmpeg-patches-<tag>.provenance.sigstore.json: SLSA build provenance, signed by the reusable workflow's identity
• SHA256SUMS and SHA256SUMS.sigstore.json: checksums, signed keyless with cosign

The release notes list the base and every patch with its upstream state, and show the verify commands. A consumer pins the tag and the tarball's sha256.

Versions follow SemVer and start below 1.0.0:

• v0.MINOR.PATCH while vmafx and Pelorus adopt the series: MINOR moves when the FFmpeg base moves or a patch is added or dropped, PATCH for metadata or tooling
• v1.0.0 once both consume it; from then on MAJOR moves with the FFmpeg base (consumers rebase their own patches), MINOR when a patch is added or dropped, PATCH for metadata or tooling

Licence

The patches change FFmpeg's sources and keep FFmpeg's LGPL-2.1-or-later. The tooling and documentation are EUPL-1.2. REUSE.toml records both.