# FFmpeg source/relink kit — local engineering procedure

This tooling is promoted from `swarm-report/lgpl5-source-kit-technical/raw/ffmpeg-relink-kit-final.py` and its regression suite. The historical 2026-10-27 proof is not evidence that today's binary has corresponding source. This procedure creates a new local source deliverable and evidence; it is not a public source offer, legal approval, Apple-signed export or permission to publish. The installed app never fetches code. Keep the kit outside `.app`.

## Correspondence and boundaries

`Engine/sources.sha256` has eight active FFmpeg input pins: six complete archives (FFmpeg 9.0.2, LAME 3.100, Ogg, Opus, Vorbis and libvpx 1.15.0), FFmpeg's detached release signature and its public release key. Comment-only archive/WebP pins are unrelated to this kit. The tool verifies every active SHA-256 and verifies FFmpeg's signature against primary fingerprint `FCF986EA15E6E293A5644F10B4322F04D67658D8` in a temporary isolated GnuPG home, without consulting user keyrings or retrieving keys. The other five archives have pinned hashes, not an asserted upstream signature.

The source builder retains the existing unpatched LGPL-profile configure options and static closure: external `libogg.a`, `libopus.a`, `libvorbis.a`, `libvorbisenc.a`, `libmp3lame.a`, `libvpx.a`, and in-tree `avcodec`, `avformat`, `avutil`, `avfilter`, `swresample`, `swscale`. A receipt must establish actual final-link evidence and hash those products; declarations alone do not establish a binary's provenance. The capability inventory checks arm64, minOS 15, file-only protocols, required codecs/filters, no GPL/nonfree switches, and system-only dynamic dependencies. These are build observations, not clean-machine or hardware-encoder acceptance.

The packer includes the complete source archives, seven recipe/notice/entitlement/documentation files, generated configuration/link evidence, build receipt, extracted licence/notice/PATENTS texts, and a top-level copy of this README. Keeping the procedure at its original `scripts/ffmpeg-relink.md` path also lets the portable recipe be packed again without relying on the developer checkout. Required texts include FFmpeg `LICENSE.md`/`COPYING.LGPLv2.1`, LAME/Ogg/Vorbis `COPYING`, Opus `COPYING`/`LICENSE_PLEASE_READ.txt`, and libvpx `LICENSE`/`PATENTS`. Other named licence/notice texts are inventoried. Source-header copyrights and compiled-in subcomponents still need review. The kit does not include the binary, Apple SDK, signing keys, unrelated cache contents, archive helper sources or WebP helper sources. Those other shipped helpers need their own exact-source/notice delivery.

On promotion, this checkout had no `Engine/.cache`, FFmpeg source tree, static prefix, build receipt or signed receipt. `Engine/build/SweetchFFmpeg` existed alone. No exact-source claim can be attached retroactively to that opaque helper; preserve it until a new helper has been proven. The archived proof's kit hash is not the hash of any newly produced kit.

Before publishing a kit, audit its generated receipt and build/configuration logs: they contain absolute build paths, and `gpg --version` includes its home directory. Build a public candidate under a neutral task-owned root with separate neutral `HOME` and `TMPDIR`, using only the verified pinned cache. Do not run the builder against the owner's home or redact an already-hashed receipt in place. Re-pack, independently freeze the candidate's new digest and prove the exact public kit; preserve the original private provenance separately. A clean path audit is not a licence or legal clearance.

## Independent verification commands

Run only after integration is frozen, on an arm64 macOS builder with the existing Xcode/compiler, CMake, pkg-config, make, curl, GnuPG and Python 3 prerequisites. These commands are instructions, not an assertion they ran. Do not install prerequisites or download sources implicitly to work around a missing input. No command below removes or overwrites the shared baseline helper/cache/build tree.

From the repository root, allocate a unique task-owned directory:

```sh
ROOT="$PWD"
TASK_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/sweetch-ffmpeg-source.XXXXXX")"
CACHE="$TASK_ROOT/cache"
WORK="$TASK_ROOT/build"
KIT="$TASK_ROOT/ffmpeg-source-relink.tar.gz"
mkdir "$CACHE"
```

First stage all eight exact pinned files into `$CACHE` from an authorized source. Their basenames are the eight non-comment rows in `Engine/sources.sha256`. If they are unavailable, stop: offline production cannot succeed. The source builder's separate online mode (omit `--offline`) can fetch only its pinned sources into this private cache; using it requires authorization for that fetch. It does not install dependencies. Never repin a hash to accept different bytes.

Then execute in order, stopping on any failure:

```sh
python3 -m unittest discover -s scripts/tests -q
python3 scripts/ffmpeg-relink-kit.py verify-inputs --root "$ROOT" --cache "$CACHE"
bash scripts/build-ffmpeg.sh --offline --cache-dir "$CACHE" --work-dir "$WORK" --jobs 2
python3 scripts/ffmpeg-relink-kit.py check-build --root "$ROOT" --cache "$CACHE" \
  --work "$WORK" --build-receipt "$WORK/build-receipt.json"
python3 scripts/ffmpeg-relink-kit.py pack --root "$ROOT" --cache "$CACHE" --work "$WORK" \
  --build-receipt "$WORK/build-receipt.json" --output "$KIT"
shasum -a 256 "$KIT"
```

`build-ffmpeg.sh` automatically executes `record-build` in its actual compiler environment after all capability gates. Do not execute `record-build` again: receipts are exclusive-create. It records the source/recipe hashes, post-build source-tree inventory, all twelve static-library products, actual link command, selected build variables, toolchain observations and compiler-produced helper digest. The new executable is `$WORK/ffmpeg-build/ffmpeg`. It has not replaced the shared `Engine/build/SweetchFFmpeg`.

Independently freeze the `kitSha256` printed by `pack`, cross-check it with the `shasum` output, and assign that exact trusted 64-character digest to `KIT_SHA256`. Do not derive a recipient's expected digest from the kit's own manifest. Preserve the kit, receipt, printed size/hash and verification evidence together; retain the baseline bytes separately.

```sh
python3 scripts/ffmpeg-relink-kit.py verify-kit --kit "$KIT" --expected-kit-sha256 "$KIT_SHA256"
python3 scripts/ffmpeg-relink-kit.py prove-relink --kit "$KIT" --expected-kit-sha256 "$KIT_SHA256" \
  --work-root "$TASK_ROOT/proof-work" --evidence "$TASK_ROOT/proof-evidence" --jobs 2
```

The proof work/evidence destinations must not already exist or overlap. The driver uses only the verified portable kit and performs three cold offline builds: A unmodified, B with the exact single-line `libavutil/version.c` configuration-return mutation, C with unmodified source again. It verifies the pinned banner caller, runtime linked-library marker, original-binary substitution negative controls, changed source/helper digests, static closure and normalized capability/licence profile. A and B encode PCM to MP3 with `libmp3lame` and decode it. C must lose the marker and differ from B; C need not be byte-identical to A. `proof-evidence/proof.json` records those results. A successful proof establishes this new kit's local rebuild/relink path, not a legal finding or recipient ability to run a modified Store app.

Build/proof commands do not impose a process deadline. The supervising QA runner must supply finite wall-clock/process-group cleanup bounds and sufficient disk; never start concurrent builds in one work directory. Retain failed evidence without treating it as accepted. The proof deletes only its own A work subtree before C, never shared `Engine/build`.

## Existing signing consumers are unchanged

`sign-local-helper.sh`, `sign-embedded-ffmpeg.sh`, `build-channel.sh` and Xcode phases are not migrated by this source-kit promotion. The current local wrapper signs from default `Engine/build/ffmpeg-build/ffmpeg`; it does not automatically create a signed receipt. Xcode's existing phases verify signatures/identifiers, not these new source receipts. Do not claim otherwise.

The retained historical commands `record-signed`, `check-helper`, `check-embedded` and `record-bundle --mode local` are explicit, restrictive local-only gates, using the default `Engine/build` and `Engine/.cache`. `record-signed` compares disposable signature-stripped copies of compiler and signed helper. `check-embedded` additionally requires exact local signed-helper byte equality and the exact sandbox+inherit entitlement pair. `record-bundle` requires that chain, the verified kit, matching current recipe/sources and app signature/version metadata; it always records `local-only` and `sourceOfferUrl: null`, and refuses `--mode release`.

The direct-channel embed script intentionally re-signs the copied helper with empty entitlements. Thus it cannot satisfy the retained exact sandbox+inherit/byte-equality mapping. Apple re-sign/export similarly cannot be grandfathered in. Do not weaken these gates or call re-signed bytes identical. A separate reviewed correspondence stage would have to compare normalized code on disposable copies after removing signatures, preserve both actual signed hashes, and independently verify each artifact's declared channel entitlement policy, identifier, runtime, Team/signature chain and source-receipt linkage. No such release-stage proof is supplied by this tool.

## Delivery, legal and signing prerequisites

The kit's manifest remains `local-only`, with no source-offer URL and no external-review approval. Actual recipient delivery requires an owner-approved versioned source/kit delivery location or accompanying-media route, retention/access policy, exact published/received hash proof, release-artifact-to-kit mapping and recipient rehearsal. Do not invent an offer URL or label a local archive as delivered.

Qualified counsel must review the exact FFmpeg/LAME/transitive terms, static-link source/object/relink sufficiency, modification/reverse-engineering terms, codec/patent rights by territory, Store/signing restrictions and recipient use of a modified helper. Archive-helper ZIP/Deflate64 and WebP rights/source/notice obligations are separate, still relevant to the app, and not discharged by this FFmpeg kit.

The current Xcode Release configuration declares ad-hoc identity `-`, manual signing, provisional `org.sweetch.mac.local`, display/product name `Sweetch`, version/build `1.0`/`1`, arm64 and minOS 15.0. It declares no Development Team or app-icon asset setting. Owner-confirmed branding/bundle IDs, authorized Apple identities and channel-specific archive/export/review work remain external prerequisites; no accounts, credentials or identities are inspected or selected here.