ifm3d FFmpeg builds

This repository builds the minimal shared FFmpeg libraries used by ifm3d's native H.264 decoder integration. ifm3d performs RTSP, RTP, and depacketization itself and gives complete Annex-B access units to FFmpeg. The build therefore contains only shared libavcodec and libavutil, the native H.264 decoder, and the H.264 parser.

Release targets

Target	Build environment	Wheel tag
Windows x86_64	Windows 2022, MSYS2 UCRT64, w32threads	py3-none-win_amd64
Linux x86_64	pinned PyPA manylinux_2_28 image	py3-none-manylinux_2_28_x86_64
Linux aarch64	native ubuntu-24.04-arm, pinned PyPA manylinux_2_28 image	py3-none-manylinux_2_28_aarch64

Linux requires glibc 2.28 or newer, which includes Ubuntu 20.04 and newer. No macOS, Windows ARM, or 32-bit build is produced.

ifm3d loader compatibility: current ifm3d Linux releases recognize libavcodec/libavutil majors through FFmpeg 7. The nightly workflow still builds newer stable FFmpeg releases, but FFmpeg 8 or newer Linux artifacts require a corresponding ifm3d loader update. Windows uses version-suffixed DLL names and supports current majors.

Dispatching a release

Only exact numeric upstream versions are accepted:

gh workflow run build-dispatch.yml \
  --field ffmpeg_version=7.1.3 \
  --field build_revision=1

The immutable identity is ffmpeg-7.1.3-r1; the PyPI version is 7.1.3.post1. A complete existing release is validated and treated as a no-op. A partial or conflicting release fails and requires a new revision.

The workflow:

1. rejects malformed input and preflights the exact release identity;
2. downloads one official source archive and detached signature;
3. verifies the vendored FFmpeg release key fingerprint and signature;
4. records a canonical source digest and source-derived SOURCE_DATE_EPOCH;
5. gives those exact source bytes to all three native build jobs;
6. verifies the minimal configure surface, architecture, all 13 required exports, dependency closure, and H.264 decoder registration;
7. creates deterministic development archives and platform wheels;
8. validates the exact aggregate and sorted checksums;
9. creates a draft GitHub release, uploads exact assets, then publishes it;
10. publishes missing wheels to the validated PYPI_TARGET using OIDC.

The native gate verifies H.264 decoder registration. It does not currently perform a real frame decode, and the release notes state that explicitly.

Assets

Every release contains exactly:

• ifm3d-ffmpeg-<version>-r<revision>-linux-x64.tar.gz
• ifm3d-ffmpeg-<version>-r<revision>-linux-aarch64.tar.gz
• ifm3d-ffmpeg-<version>-r<revision>-windows-x64.zip
• three matching ifm3d_ffmpeg-<version>.post<revision>-py3-none-*.whl files
• ffmpeg-<version>.tar.xz and .asc
• ffmpeg-<version>.tar.xz.sha256
• source-manifest.json
• RELEASE_NOTES.md
• SHA256SUMS

Linux archives preserve complete SONAME chains. Development archives also contain libavcodec/libavutil headers, pkg-config files, Windows import libraries, actual FFmpeg LGPL texts, configure output, build/source manifests, and dependency inventories. Wheels contain only the target runtime libraries, package-local metadata, Python discovery code, and license files. The Windows FFmpeg DLLs remain shared, but required GCC/winpthreads runtime code is linked statically into them. Release gates reject any libwinpthread-1.dll import or payload. Archives and wheels still include the authoritative mingw-w64 winpthreads MIT/BSD license and record the embedded dependency explicitly.

Python API

Install the wheel before ifm3d performs decoder discovery:

python -m pip install ifm3d-ffmpeg==7.1.3.post1

from ifm3d_ffmpeg import abi_info, activate, lib_files, lib_path, version

print(version())       # "7.1.3"
print(abi_info())      # version, revision, ABI majors, source digest, target
print(lib_path())      # package-local library directory
print(lib_files())     # exact avcodec and avutil paths
activate()             # call before ifm3d searches for bare FFmpeg ABI names

Metadata and both ABI-matching libraries are mandatory. Import fails for a missing or malformed manifest, unsupported host, wrong-platform wheel, or incomplete library set; there is no unknown fallback.

activate() registers the package directory on Windows and keeps avutil then avcodec loaded globally on Linux, allowing ifm3d's subsequent bare version-suffixed library lookup to reuse the packaged runtime.

Source authenticity and LGPL compliance

scripts/ffmpeg-release.gpg is the exact public key published at https://ffmpeg.org/ffmpeg-devel.asc. The resolver asserts fingerprint FCF986EA15E6E293A5644F10B4322F04D67658D8, creates an isolated keyring, uses gpgv, checks its exit status and machine-readable VALIDSIG status, and fails closed.

Every release attaches the exact corresponding official source and signature. Actual FFmpeg LICENSE.md, COPYING.LGPLv2.1, and COPYING.LGPLv3 files are copied from that verified source into archives and wheels. Repository-authored Python and build tooling is MIT licensed; bundled FFmpeg libraries remain LGPL-2.1-or-later. See https://ffmpeg.org/legal.html.

Nightly discovery

.github/workflows/nightly-check.yml runs nightly and manually. It discovers only exact stable numeric releases from the official download page, runs the candidate through the same signed-source resolver, and dispatches build-dispatch.yml for revision 1 only when the exact tag is absent. The built-in GITHUB_TOKEN is sufficient for workflow_dispatch; no PAT or repository secret is required.