Media Setup
Coverage metadata:
crates/media/**
Overview
The media setup area is the Bun/TypeScript setup script that prepares the pinned FFmpeg dependency used by the media crate. Its entry point is crates/…/setup.ts, and its version/download metadata lives in crates/…/ffmpeg.json.
setup.ts installs FFmpeg under the repository-local cache path .cache/media/ffmpeg-<version>-<os>-<arch>, where the script comments note that the media crate build finds it. By default, moon run media:setup resolves the host platform from process.platform and process.arch; callers can pass --target <os>-<arch> to prepare another supported target or --from-source to force a local source build. Supported normalized platform keys are windows|macos|linux paired with x86_64|aarch64.
ffmpeg.json pins FFmpeg 8.1.3, declares the license as LGPL-2.1-or-later, records the upstream source tarball and SHA-256, and lists prebuilt archives for Windows x86_64/aarch64 and Linux x86_64/aarch64. The setup script verifies every downloaded archive with SHA-256 before unpacking it. If the host target has a matching prebuilt and --from-source is not present, setup.ts downloads and extracts that prebuilt. Otherwise it downloads the pinned source, configures and builds FFmpeg, installs it into a staging prefix, and then moves the completed prefix into .cache/media/.
Source builds use a deliberately narrow FFmpeg configuration in configureFlags() in crates/…/setup.ts: shared libraries are enabled, static libraries, programs, docs, avdevice, avfilter, networking, and autodetected system dependencies are disabled. Platform-specific flags keep the output usable by the app: Windows builds are cross-compiled from Linux with llvm-mingw and use Win32 threads; macOS builds require a Mac, set @rpath install names, and target macOS 11 or newer; Linux cross-architecture builds are rejected and must be built on matching architecture. On x86_64, missing nasm only disables x86 assembly and warns that decoding will be slower.
The script is idempotent through a .complete marker in the destination. The marker records either the prebuilt archive checksum or the source checksum plus a hash of the configure flags, so changing ffmpeg.json or the build recipe causes a rebuild. Work happens in a sibling .partial directory and is renamed into place only after download/build/extract succeeds, preventing interrupted runs from leaving a cache directory that appears complete. Source builds also copy COPYING.LGPLv2.1 and LICENSE.md from the FFmpeg source and write a BUILD.md containing the source URL, SHA-256, configure flags, and LGPL note beside the installed libraries.
Coupling
- If crates/…/ffmpeg.json changes the FFmpeg version, source URL, platform archive URLs, or checksums, verify crates/…/setup.ts still computes destination names and stamps that distinguish the new artifact; stale
.completemarkers are what prevent unnecessary rebuilds. - If crates/…/setup.ts changes
configureFlags(), verify the source-build BUILD.md output in the same file still records enough information for LGPL redistribution, because that file is generated from the exact flags array. - If a new target platform is added to crates/…/ffmpeg.json, update
hostPlatform(),parsePlatform(), andconfigureFlags()in crates/…/setup.ts together; an added manifest key alone is not enough for the CLI to accept or build that platform. - If the cache layout under
.cache/media/ffmpeg-<version>-<platform>changes in crates/…/setup.ts, verify the media crate build lookup mentioned in the setup script comments is updated as well; the setup script is the producer of the cached dependency path.
Risks
- crates/…/ffmpeg.json currently has no macOS prebuilt entries, so macOS setup falls back to a source build in crates/…/setup.ts; without Xcode/toolchain support, a macOS developer or CI job can fail before the media crate builds.
- crates/…/setup.ts chooses source builds whenever
--targetdiffers from the host or no prebuilt exists. Windows targets specifically require a Linux host withllvm-mingwbinaries such as<arch>-w64-mingw32-clangonPATH; otherwise cross-target setup fails immediately. - crates/…/setup.ts trusts extracted archives to contain a single top-level directory and returns the first directory entry after extraction. If a future prebuilt archive in crates/…/ffmpeg.json changes layout or includes extra top-level entries, the script can move the wrong directory into
.cache/media/.