fix(container): pin mp4v2 to specific commit on main branch

v2.1.0's CMake install rules have a bug — project.h is generated
into the build dir but the install rule looks for it in the source
dir, so `cmake --install` fails after a successful build. Reported
upstream and fixed on `main`; no newer release tag exists yet.

Pin MP4V2_REF to commit 86b5aaf (current head of mp4v2/main) for
reproducibility. Switching the clone command from
`git clone --branch` (which only accepts branches/tags) to
`git init` + `git fetch --depth 1 <SHA>` so the ARG can hold any
ref shape — branch, tag, or commit SHA — without surgery later.

A comment in the Containerfile explains how to bump the pin via
`git ls-remote`. spec/external-tools.md updated to reflect the
2.1.3 CMake project version and the pinning strategy.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: warricksothr

Containerfile

@@ -27,8 +27,26 @@ FROM docker.io/library/debian:bookworm-slim AS mp4v2
 RUN apt-get update && apt-get install -y --no-install-recommends \
         git ca-certificates cmake build-essential \
     && rm -rf /var/lib/apt/lists/*
-ARG MP4V2_REF=v2.1.0
-RUN git clone --depth 1 --branch "${MP4V2_REF}" https://github.com/enzo1982/mp4v2.git /src/mp4v2
+# Pinned to a specific commit on enzo1982/mp4v2's `main` branch.
+# The v2.1.0 tag has a broken cmake install rule (project.h is
+# generated into the build directory but install rules look in the
+# source directory). `main` carries the fix; no newer tag exists yet.
+#
+# To bump (do this periodically to pick up upstream bug fixes):
+#   git ls-remote https://github.com/enzo1982/mp4v2.git refs/heads/main
+# Update both the SHA here and the note in spec/external-tools.md.
+# Bumping invalidates the GHA layer cache; the next CI build will
+# rebuild mp4v2 from scratch (~3-5 min).
+ARG MP4V2_REF=86b5aaf13d03291873608af559fe0399efe898f4
+
+# `git clone --branch` doesn't accept commit SHAs, so use init +
+# shallow-fetch instead. This pattern works for branches, tags, AND
+# commit SHAs, keeping MP4V2_REF flexible.
+RUN mkdir -p /src/mp4v2 \
+    && cd /src/mp4v2 \
+    && git init -q \
+    && git fetch --depth 1 https://github.com/enzo1982/mp4v2.git "${MP4V2_REF}" \
+    && git checkout -q FETCH_HEAD
 RUN cmake -S /src/mp4v2 -B /build -DCMAKE_BUILD_TYPE=Release \
     && cmake --build /build -j"$(nproc)" \
     && cmake --install /build --prefix /opt/mp4v2

spec/external-tools.md

@@ -24,7 +24,7 @@ or newer, and refuse older only if output format differs.
 | Tool   | Pinned version | Notes                               |
 |--------|---------------|--------------------------------------|
 | ffmpeg | 5.0.1         | Needs `silencedetect`, `-f ffmetadata`, `-f concat`, `-movflags +faststart`. |
-| mp4v2  | 2.1.0         | Supplies `mp4chaps`, `mp4art`, `mp4tags`, `mp4info`. Upstream is unmaintained and has been dropped from Debian/Ubuntu repos; the maintained continuation is [`enzo1982/mp4v2`](https://github.com/enzo1982/mp4v2), with `v2.1.0` as its latest tagged release. Build from source with `cmake`; the Docker image in Milestone 9 should clone and build it rather than relying on a distro package. |
+| mp4v2  | 2.1.3 (commit-pinned) | Supplies `mp4chaps`, `mp4art`, `mp4tags`, `mp4info`. Upstream is unmaintained and has been dropped from Debian/Ubuntu repos; the maintained continuation is [`enzo1982/mp4v2`](https://github.com/enzo1982/mp4v2). The latest tagged release is `v2.1.0` but its CMake install rules have a bug (`project.h` is generated into the build dir, install looks in source); `main` carries the fix and reports CMake project version `2.1.3`. The `Containerfile` pins `MP4V2_REF` to a specific commit on `main` for reproducibility — bump it periodically via `git ls-remote https://github.com/enzo1982/mp4v2.git refs/heads/main` to pick up upstream bug fixes. Build from source with `cmake`. |
 | fdkaac | 2.0.1         | Optional.                            |
 | tone   | 0.2.5         | Optional; min ≥ 0.0.9 checked by PHP. |