FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

FFmpegBuild

Slim FFmpeg xcframeworks for Apple platforms.
Demux, decode, and a thin HLS-fMP4 mux path for AVPlayer bridging. No network stack, no CLI binaries.

Why

Full FFmpeg builds for iOS land at 40-70 MB because they bundle a TLS stack, encoders, filters, and a dozen protocols your app will never use. For a player, most of that is dead weight. Apple already ships HTTP/3, URLSession, Network.framework, VideoToolbox and AVFoundation. So this build strips out everything you don't need and keeps what you do.

~10 MB per architecture, zero network dependencies, one build script.

In

Library	What it does
libavformat	Demux MKV, MP4, WebM, MPEG-TS, MPEG-PS (VOB / DVD), HLS, AVI, OGG, FLV, plus raw elementary streams
libavcodec	Decode video + audio (with VideoToolbox bridge)
libavutil	Shared primitives
libswresample	Audio resampling / channel remap / format convert
libswscale	Pixel-format convert (YUV → NV12 / P010) for the SW-decode path
libavfilter	Trimmed filter set: zscale + tonemap + colorspace for HDR → SDR still extraction, bwdif + yadif for CPU deinterlacing on the SW-decode path, yadif_videotoolbox + hwupload for GPU (Metal) deinterlacing of VideoToolbox frames
dav1d	Fast AV1 software decoder (separate xcframework)
zimg	zscale's resampling / colorspace backend (separate xcframework, link-only)
libzvbi	DVB teletext decoder backend for `libzvbi_teletext` (separate xcframework, link-only)

Out

Anything the app layer should already handle or doesn't need:

Network / TLS: FFmpeg reads from an avio_alloc_context callback, you wire URLSession to it
Encoders, except FLAC and EAC3 (kept for the audio bridge that re-encodes non-streamable sources like TrueHD / DTS / DTS-HD MA. FLAC for the lossless 7.1 path, EAC3 5.1 for the default soundbar-compat path that surfaces surround via HDMI bitstream tunnel)
Muxers, except MP4 / MOV / HLS (kept for the HLS-fMP4 producer that wraps streams for AVPlayer)
libavdevice (libavfilter is included but trimmed to a handful of filters, see In)
Most filters: libavfilter ships only buffer / buffersink / format / scale / zscale / tonemap / colorspace / bwdif / yadif / yadif_videotoolbox / hwupload
Programs (ffmpeg, ffplay, ffprobe)
Hardware accel layers other than VideoToolbox
Text subtitle rendering (do that in SwiftUI)

Build

./build.sh # all platforms, dynamic frameworks (the shipped shape)
./build.sh static # static variant, for apps that can meet LGPL 6(a) themselves
./build.sh package # repackage frameworks without recompiling
./build.sh clean # wipe everything

Needs Xcode 16+ and roughly 10-30 minutes depending on your machine. All sources (FFmpeg, dav1d, zimg, libzvbi) clone on first run.

Output lands in Sources/ as xcframeworks, ready to consume via Swift Package Manager. The shipped xcframeworks contain dynamic frameworks (dylib-in-framework, @rpath install names); Xcode embeds and signs them in the app bundle automatically when you link the package. That is what keeps the LGPL relink requirement satisfiable for closed-source apps, see License below.

Use

// Package.swift
dependencies:[.package(url:"https://github.com/superuser404notfound/FFmpegBuild", from:"3.0.0")]
// Target:
.product(name:"AetherFFmpegBuild",package:"FFmpegBuild")

Pin branch: "main" instead of a version if you want to track the latest rebuilds (that is how AetherEngine consumes it).

Then import the modules you need: AetherLibavformat, AetherLibavcodec, AetherLibavutil, AetherLibswresample, AetherLibswscale, AetherLibavfilter, AetherLibdav1d. (AetherLibzimg is a link-only backend for zscale, and AetherLibzvbi a link-only backend for the teletext decoder; you don't import either directly.) The umbrella AetherFFmpegBuild product links all of them plus the system frameworks (AudioToolbox, CoreMedia, CoreVideo, VideoToolbox) in one shot.

The FFmpeg API itself is unchanged: avformat_open_input, avcodec_send_packet and the rest keep their names. Only the module and framework names carry the prefix.

Sitting next to another FFmpeg

Every FFmpeg packaged for Apple platforms declares the same target names, so before 3.0.0 this package could not resolve in an app that also had one. A fallback ladder with KSPlayer, mpv or MobileVLCKit in it is exactly such an app:

error: multiple similar targets 'Libavcodec', 'Libavfilter', 'Libavformat' and 3 others
appear in package 'ffmpegbuild' and 'ffmpegkit'

moduleAliases does not reach this: it renames Swift source targets, not binary ones. Two things had to change, and 3.0.0 changes both:

SwiftPM target and product names are unique across the whole dependency graph. AetherLibavcodec no longer meets Libavcodec.
Framework bundle and install names, because two Libavcodec.framework bundles cannot both live at App.app/Frameworks/ under one @rpath/Libavcodec.framework/Libavcodec. The shipped install name is now @rpath/AetherLibavcodec.framework/AetherLibavcodec.

What the rename does not change is the C symbols: _avcodec_open2 is still _avcodec_open2 in every FFmpeg on earth. Distinct dynamic frameworks are enough on their own, because the two-level namespace records per reference which dylib it came from. A static FFmpeg in the same executable is the case that still bites: its symbols become definitions inside the executable and win for every object linked beside them. The fix there is to link the code that calls this build into its own dynamic framework, so its _av* bind at that framework's link. AetherEngine documents the recipe in docs/api.md.

Decoder support

Video (hardware via VideoToolbox): H.264, HEVC up to Main10 (HDR10 / DV Profile 8)
Video (software): AV1 (dav1d), VP9, VP8, MPEG-2, MPEG-4, VC-1, QuickTime RLE (qtrle), and the legacy Microsoft tail: MS-MPEG4 v1 / v2 / v3 (DivX 3.x in pre-2005 AVI rips), WMV1 / WMV2, WMV3 (WMV9, inside Matroska or MPEG-TS; the asf demuxer and the WMA decoders a native .wmv also needs are not built, see build.sh)
Audio: AAC, AC3, EAC3 (incl. JOC detection for Atmos), FLAC, MP2, MP3, Opus, Vorbis, TrueHD, MLP, DTS, ALAC, PCM (incl. Blu-ray LPCM via pcm_bluray)
Subtitles: SRT, ASS, SSA, WebVTT, PGS, DVB subtitle, DVB teletext (via libzvbi), DVD

HDR metadata (BT.2020, SMPTE ST 2084 / PQ, HLG, DV RPU) is preserved end-to-end so the decode pipeline can tag frames correctly.

Size

Release configuration, dynamic framework binaries as embedded in the app (all six FFmpeg libraries plus the dav1d, zimg and zvbi backend frameworks):

Target	FFmpeg	dav1d	zimg	zvbi	Total
iOS / tvOS / visionOS arm64	~8.7 MB	~0.8 MB	~0.3 MB	~0.5 MB	~10.5 MB
macOS universal (arm64 + x86_64)	~18.3 MB	~2.5 MB	~0.9 MB	~1.0 MB	~22.7 MB

Assembly-optimized paths are enabled where the Apple toolchain permits.

Local FFmpeg patches

build.sh applies four small patches to the FFmpeg source after checkout (each documented in place):

patch_ffmpeg: balances autoreleased Metal objects in vf_yadif_videotoolbox.m (upstream over-release crashes host apps whose GCD queues pop their last-resort autorelease pool at session teardown).
patch_ffmpeg_pgssub: pgssubdec.c no longer flushes retained palettes/objects on an Epoch-Continue PCS (composition_state 3). An Epoch Continue set marks a seamless connection between two clips: a conformant set re-conveys everything it references (so skipping the flush is output-neutral), while a non-conformant bare PCS+WDS+END set relies on retained state and was dropped whole with "Invalid palette id 0" under the upstream flush (AetherEngine issue 142). Error resilience, not a spec requirement; Acquisition Point and Epoch Start keep flushing. Proposed upstream as FFmpeg PR 23851.
patch_ffmpeg_visionos: videotoolbox.c skips kCVPixelBufferOpenGLESCompatibilityKey on visionOS, where the key is unavailable because the platform has neither OpenGL ES nor OpenGL. Upstream selects it on TARGET_OS_IPHONE, which is 1 on visionOS (TARGET_OS_IOS is the one that is 0), so the hardware-decode path does not compile for xros without this. Nothing is lost: the attribute only asks CoreVideo to make the buffer bindable as a GL texture, and on visionOS every consumer is Metal, which the IOSurface properties set alongside it already cover.
patch_ffmpeg_matroska_tts: matroskadec.c logs a warning when a Matroska track carries a TrackTimestampScale other than 1.0. Timestamp behavior stays exactly as upstream implements it, which is what RFC 9559 specifies (block timestamps and BlockDuration are Track Ticks). The element is deprecated (maxver 3) and many readers ignore it, so a file carrying it may have been authored against such readers and mistime silently; the warning surfaces that condition (AetherEngine issue 145). Until 2.1.x this patch clamped TTS to 1.0; the clamp rested on a wrong reading of the RFC and was dropped after upstream review (FFmpeg PR 23852).

Keeping the pins current

The versions this package builds are shell variables in build.sh, not a manifest, so no dependency bot sees them. Scripts/check-upstream.py compares all five (FFmpeg, dav1d, zimg, libzvbi, and dolby_vision over in LibDovi) against what upstream has published:

python3 Scripts/check-upstream.py --libdovi ../LibDovi/build.sh

It exits 1 when something is behind and prints why, with any published security advisory for that project attached as context. FFmpeg is compared against the newest patch on the pinned minor line rather than the newest tag overall: moving off 8.1 is a deliberate decision, not a weekly reminder.

The Upstream watch workflow runs it every Monday and keeps exactly one issue: opened when a pin falls behind, rewritten while it stays behind, and closed by the run that finds everything current again. Nothing is posted when there is nothing to do.

Built with

This package is vibe-coded, assembled and maintained by Vincent Herbst in close pair-programming with Claude (Anthropic). The commit log is the receipt: nearly every commit carries a Co-Authored-By: Claude trailer.

License

LGPL-2.1-or-later (LICENSE), matching upstream FFmpeg's default license. The build enables neither --enable-gpl nor --enable-version3, so no GPL or LGPL-3.0 components are compiled in. Per component:

Component	License
FFmpeg (all six libraries)	LGPL-2.1-or-later
dav1d	BSD-2-Clause
zimg	WTFPL
libzvbi (library sources)	LGPL-2.0-or-later, `ure.c` MIT
Build scripts / SPM stubs (this repo)	LGPL-2.1-or-later

libzvbi's three GPL-2 source files (packet-830.c, pdc.c, exp-vtx.c) are excluded from the build and the two referenced entry points are replaced with LGPL stubs (build.sh, patch_zvbi), so the shipped binaries contain no GPL code. All license texts live in LICENSES/.

Shipping in an App Store app

The xcframeworks are dynamic frameworks on purpose: LGPL section 6 requires that end users can swap in a modified version of the library. With dynamic linking your app binary stays yours (closed source is fine) and the obligations reduce to:

Link the package normally; Xcode embeds the frameworks in YourApp.app/Frameworks/. Do not merge them into the app binary (no mergeable-library trickery), that would recreate static linking.
Reproduce the license texts from LICENSES/ somewhere reasonable (acknowledgements screen, bundled file).
State that your app uses FFmpeg and friends, and link to the source of the exact build you ship (a tagged release of this repo, or your fork if you modified it).

If you build the static variant instead, those steps are not sufficient: LGPL 6(a) then requires you to provide your app's object files (or full source) so users can relink. That is realistic for open-source apps and rarely anything else, which is why static is not the shipped shape.

_{Used by AetherEngine.}

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
Scripts		Scripts
Sources		Sources
Tests/FFmpegBuildTests		Tests/FFmpegBuildTests
.gitignore		.gitignore
.spi.yml		.spi.yml
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
build.sh		build.sh

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
Scripts		Scripts
Sources		Sources
Tests/FFmpegBuildTests		Tests/FFmpegBuildTests
.gitignore		.gitignore
.spi.yml		.spi.yml
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
build.sh		build.sh

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
Scripts		Scripts
Sources		Sources
Tests/FFmpegBuildTests		Tests/FFmpegBuildTests
.gitignore		.gitignore
.spi.yml		.spi.yml
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
build.sh		build.sh

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
Scripts		Scripts
Sources		Sources
Tests/FFmpegBuildTests		Tests/FFmpegBuildTests
.gitignore		.gitignore
.spi.yml		.spi.yml
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
build.sh		build.sh

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
Scripts		Scripts
Sources		Sources
Tests/FFmpegBuildTests		Tests/FFmpegBuildTests
.gitignore		.gitignore
.spi.yml		.spi.yml
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
build.sh		build.sh

Latest commit

History

Folders and files

Repository files navigation

FFmpegBuild

Why

In

Out

Build

Use

Sitting next to another FFmpeg

Decoder support

Size

Local FFmpeg patches

Keeping the pins current

Built with

License

Shipping in an App Store app

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

FFmpegBuild

Why

In

Out

Build

Use

Sitting next to another FFmpeg

Decoder support

Size

Local FFmpeg patches

Keeping the pins current

Built with

License

Shipping in an App Store app

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

FFmpegBuild

Why

In

Out

Build

Use

Sitting next to another FFmpeg

Decoder support

Size

Local FFmpeg patches

Keeping the pins current

Built with

License

Shipping in an App Store app

About

Topics

Resources

Stars

Watchers

Forks