Introducing a new way to review your PRs.

Read the announcement

opencut-app / opencut

The open-source CapCut alternative

View on GitHub

12 documents · Updated Nov 16, 2026

docs / media-setup

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 .complete markers 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(), and configureFlags() 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 --target differs from the host or no prebuilt exists. Windows targets specifically require a Linux host with llvm-mingw binaries such as <arch>-w64-mingw32-clang on PATH; 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/.