# MomentumTranscodeHelper

The delivery encoder for everything AVFoundation cannot write.

## Why it exists

AVFoundation and VideoToolbox cover MOV, MP4, ProRes, H.264 and HEVC well, and
on Apple silicon they encode H.264/HEVC (and ProRes, on M1 Pro and later) on the
media engine, which is faster than any software encoder. They cannot write MKV,
WebM, MXF, DNxHD/DNxHR, CineForm, FFV1, HuffYUV, VP8/VP9, AV1, JPEG 2000,
MPEG-2, VC-2, or most of the audio and subtitle formats a delivery spec asks
for. This helper covers that remainder.

It is a **separate executable**, not a library linked into cinemaOS — the same
shape as `MomentumAAFHelper`. cinemaOS spawns it and parses its progress. No
`libav*` symbol is linked into the app binary.

## Licence position

FFmpeg is built **without `--enable-gpl`**. x264, x265, xvid and every other
GPL-only library are excluded deliberately: cinemaOS is proprietary, so a GPL
component in the bundle would be a violation. We lose nothing by it — H.264 and
HEVC come from VideoToolbox hardware, which is faster than x264 anyway.

Everything vendored is LGPL or BSD:

| Component | Version | Licence |
|---|---|---|
| FFmpeg | 7.1 | LGPL-2.1-or-later |
| opus | 1.5.2 | BSD-3-Clause |
| LAME | 3.100 | LGPL-2.0-or-later |
| libvpx | 1.14.1 | BSD-3-Clause |
| SVT-AV1 | 2.2.1 | BSD-3-Clause |
| dav1d | 1.4.3 | BSD-2-Clause |
| OpenJPEG | 2.5.2 | BSD-2-Clause |

Obligations, all enforced by `verify_provenance.py`:

1. Every licence text in `licenses/` ships inside the bundle at
   `Contents/Resources/TranscodeHelper/`.
2. A written offer for the complete corresponding source of the LGPL
   components, at the pinned versions and hashes in `PROVENANCE.json`.
3. The helper is statically linked, so LGPL-2.1 §6(a) is met by publishing
   those pinned sources together with `build_helper.sh` — that pair is enough
   for anyone to build a modified helper and substitute it.

`verify_provenance.py` fails the build if a source declares a licence we may not
bundle, if a pinned hash is malformed, if a referenced licence file is missing,
or if the built binary reports `--enable-gpl`.

## Building

```bash
Packaging/TranscodeHelper/build_helper.sh
```

Requires `nasm pkg-config cmake meson ninja` and a native arm64 host. Every
source is fetched by pinned URL and checked against its SHA-256 before
compiling; a mismatch aborts the build rather than producing an unverified
binary. Output: `dist/MomentumTranscodeHelper`.

## Capabilities are resolved on the user's machine, not here

Codec availability is **hardware-dependent**, so a list baked at build time
would lie on someone else's Mac. Measured on a base M1: `h264_videotoolbox`
encodes, `prores_videotoolbox` fails with `-12908` (no encoder found) because
the base M1 has no ProRes engine — that engine arrives with M1 Pro/Max. The same
binary on an M3 Max has hardware ProRes.

So cinemaOS probes the helper on first launch, caches the result against the
helper's hash and the host's chip, and offers exactly the formats that machine
can actually produce. A format that would fail is never shown — a control that
looks available but does nothing is a defect.

## Known gaps

Two formats from the target list are not covered by this helper, and are
recorded in `PROVENANCE.json` with their resolutions:

- **Cineon** — FFmpeg has a decoder but no encoder. cinemaOS writes it natively;
  it is a documented 10-bit log format in the DPX/SMPTE 268M family. It is a
  real Cineon writer, not a DPX file with the extension changed.
- **AVC-Intra / XAVC** — conformant Class 50/100/200 needs an H.264 encoder with
  intra-class SPS/PPS conformance, which in practice means x264, which is GPL.
  cinemaOS offers all-intra H.264 in MXF and labels it exactly that. It must
  never be presented as certified AVC-Intra.