# FFmpeg in VidViewer: source, build and relinking

VidViewer uses three FFmpeg libraries to convert videos in legacy, patent-free
codecs (MPEG-4 Part 2 / Xvid / DivX 4-6, VP8, Theora, Sorenson Spark / H.263,
Vorbis audio) into cached MP4 proxies that the normal AVFoundation pipeline
then plays, and to decode Dolby TrueHD / MLP audio in MKV files to PCM as it
plays. TrueHD is the one codec outside the patent-free scope, added at the
owner's request; DTS stays out. FFmpeg only demuxes and decodes (the H.264 /
HEVC parsers only split frames for remuxing; there is no H.264 / HEVC
decoder). Encoding is done by Apple's VideoToolbox / AudioToolbox, and the
proxy is written by AVFoundation.

Only the transcoder service links them: they ship in
`VidViewer.app/Contents/XPCServices/VidViewerTranscoder.xpc/Contents/Frameworks`
(the app itself never loads FFmpeg).

| Library     | Version  | File in this directory and in the transcoder's `Contents/Frameworks` |
|-------------|----------|------------------------------------------------------------------------|
| libavutil   | 61.1.102 | `libavutil.61.dylib`   (install name `@rpath/libavutil.61.dylib`)   |
| libavcodec  | 63.1.102 | `libavcodec.63.dylib`  (install name `@rpath/libavcodec.63.dylib`)  |
| libavformat | 63.1.102 | `libavformat.63.dylib` (install name `@rpath/libavformat.63.dylib`) |

License: **GNU Lesser General Public License, version 2.1 or later**
(`COPYING.LGPLv2.1`). The libraries are built without `--enable-gpl`,
`--enable-version3` or `--enable-nonfree`, and each one reports
`LGPL version 2.1 or later` from `avutil_license()` / `avcodec_license()` /
`avformat_license()` (checked by the build; see `COMPONENTS.txt`).

## Corresponding source

- **Upstream release:** FFmpeg 9.0.2, unmodified (no patches).
  - Tarball: <https://ffmpeg.org/releases/ffmpeg-9.0.2.tar.xz>
  - Signature: <https://ffmpeg.org/releases/ffmpeg-9.0.2.tar.xz.asc>
    (issuer fingerprint `FCF9 86EA 15E6 E293 A564 4F10 B432 2F04 D676 58D8`,
    the FFmpeg release signing key)
  - SHA-256: `8c3850283eb25fa026482078a04051e0be17347b09ef81a0849bec15a96e002e`
    (also the checksum Homebrew's ffmpeg 9.0.2 formula pins)
- **Build script:** `scripts/ffmpeg/build.sh` in the VidViewer repository. It
  checks the SHA-256 above, extracts, configures, builds, verifies and installs
  into `Vendor/FFmpeg/`. `scripts/ffmpeg/ffcheck.c` is the check program it
  runs.
- **Exact configure line:** `CONFIGURE.txt` (first line). It is also compiled
  into the libraries: `avcodec_configuration()` returns it.
- **Toolchain:** Apple clang 21.0.0 (Xcode, macOS SDK 27.0), arm64, minimum
  macOS 13.0. The build runs under `env -i` with a system-only `PATH` and
  `--disable-autodetect`, so the only external libraries are the macOS
  `libSystem` and system `libz` (not shipped; part of macOS).
- **Enabled components:** `COMPONENTS.txt`. Decoders `mpeg4 h263 h263i h263p
  flv vp8 theora vp3 vorbis truehd mlp` (vp3 comes with theora); demuxers `avi
  matroska ogg flv mov mpegps`; parsers `mpeg4video h263 vp8 vorbis mpegaudio
  ac3 aac flac opus mlp h264 hevc`; bitstream filters `mpeg4_unpack_bframes aac_adtstoasc`; protocol
  `file`. No encoders, muxers, filters, devices, network code, libswscale or
  libswresample.

## Rebuilding

On an Apple Silicon Mac with Xcode installed:

```sh
curl -LO https://ffmpeg.org/releases/ffmpeg-9.0.2.tar.xz
scripts/ffmpeg/build.sh ./ffmpeg-9.0.2.tar.xz
```

This rewrites `Vendor/FFmpeg/{include,lib}` and `CONFIGURE.txt` /
`COMPONENTS.txt` / `COPYING.LGPLv2.1` / `LICENSE.md`, and deletes its temporary
build tree. Set `KEEP_BUILD=1` to keep the tree, `FFMPEG_BUILD_ROOT` to choose
where it goes, or `DEVELOPER_DIR` to pick an Xcode. To build a modified FFmpeg,
make your changes to the extracted source and run the same `./configure` line
from `CONFIGURE.txt`, or edit the component lists at the top of `build.sh`.

## Replacing the libraries in VidViewer (relinking)

VidViewer's transcoder service (`VidViewerTranscoder.xpc`, inside the app)
links these libraries dynamically and loads them from its own
`Contents/Frameworks` via `@rpath`. To use your own build of them (below,
`XPC` = `VidViewer.app/Contents/XPCServices/VidViewerTranscoder.xpc`):

1. Build FFmpeg 9.0.x (your modified version if you like) as shared libraries
   with the same major versions (`libavutil.61`, `libavcodec.63`,
   `libavformat.63`) and `--install-name-dir=@rpath`. The build script does
   this.
2. Copy your `libavutil.61.dylib`, `libavcodec.63.dylib` and
   `libavformat.63.dylib` over the files of the same names in
   `XPC/Contents/Frameworks/`.
3. Re-sign, since macOS will not load modified code under the original
   signature. An ad-hoc signature works for your own use:

   ```sh
   codesign --force --sign - "$XPC"/Contents/Frameworks/libav*.dylib
   codesign --force --sign - --entitlements VidViewerTranscoder.entitlements "$XPC"
   codesign --force --sign - --entitlements VidViewer.entitlements VidViewer.app
   ```

   `VidViewerTranscoder.entitlements` (the App Sandbox, nothing else) is
   `VidViewerTranscoder/VidViewerTranscoder.entitlements` in the repository;
   `VidViewer.entitlements` (sandbox, user-selected file access, app-scope
   bookmarks, Photos) is `VidViewer/Resources/VidViewer.entitlements`. Both
   can also be extracted from the installed app with
   `codesign -d --entitlements - <bundle>`. Leave out
   `--options runtime`: under the hardened runtime, macOS only loads
   libraries signed by the same team as the app, and an ad-hoc signature has
   no team.

## Where the source is offered (LGPL 2.1 section 6)

Owner decisions (approved for this release):

- **Equivalent access from a designated place** (section 6(d)): the complete
  corresponding source is hosted at <https://vidviewer.app/oss/ffmpeg/>, next
  to where the app is offered. Files to upload there:
  - `ffmpeg-9.0.2.tar.xz` (SHA-256
    `8c3850283eb25fa026482078a04051e0be17347b09ef81a0849bec15a96e002e`), and
    optionally its `.asc` signature
  - `build.sh` (this repository's `scripts/ffmpeg/build.sh`) and
    `ffcheck.c` (`scripts/ffmpeg/ffcheck.c`, the check program it runs)
  - `CONFIGURE.txt` and `COMPONENTS.txt` (this directory)
  - `COPYING.LGPLv2.1` (this directory)
- **Contact** for questions about the source or the license: ssg@shough.io
  (the company address; no personal contact details appear anywhere).
- **EULA**: VidViewer relies on Apple's Standard Licensed Application End
  User License Agreement, whose open-source carve-out leaves the terms of
  open-source components such as FFmpeg in force (so modifying the FFmpeg
  libraries and reverse engineering for debugging such modifications stay
  allowed, as LGPL 2.1 section 6 requires). No custom EULA.
- **Credit** (Help and About): "This app uses FFmpeg (ffmpeg.org) under the
  LGPL v2.1. FFmpeg is a trademark of Fabrice Bellard." with a pointer to
  vidviewer.app/oss/ffmpeg and the full notice + license text in the app.

## Distribution checklist (for whoever ships a release)

From FFmpeg's own LGPL guidance (<https://ffmpeg.org/legal.html>):

- Before release, make sure <https://vidviewer.app/oss/ffmpeg/> serves the
  files listed above, for the FFmpeg version this build ships.
- The notice (`THIRD_PARTY_NOTICE.txt`) and the license text ship in the app
  and show from About and Help (FFmpeg License sheet).
- Keep the library file names (`libavcodec...`): renaming FFmpeg libraries to
  obscure names is not allowed.
- App Store Connect warns that the FFmpeg dylibs have no dSYMs; expected.
- libavutil / libavformat contain crypto and DRM-decryption code paths
  (AES etc., Audible / CENC options of the mov demuxer) that VidViewer never
  reaches (custom I/O only, those options never set);
  `ITSAppUsesNonExemptEncryption = NO` stays correct.