Using Multiple FFmpeg Implementations In The Same Application on Apple Platforms

On Apple platforms (iOS, iPadOS, macOS, tvOS and visionOS), FFmpegKitNext builds FFmpeg as a separate set of frameworks/xcframeworks.

A typical Apple xcframework output contains:

ffmpegkit.xcframework
libavcodec.xcframework
libavdevice.xcframework
libavfilter.xcframework
libavformat.xcframework
libavutil.xcframework
libswresample.xcframework
libswscale.xcframework

These files are generated locally under folders such as:

prebuilt/bundle-apple-xcframework-ios-12.1/
prebuilt/bundle-apple-xcframework-macos-10.15/
prebuilt/bundle-apple-xcframework-tvos-11.0/
prebuilt/bundle-apple-xcframework-visionos-1.0/
prebuilt/umbrella-apple-xcframework-.../

ffmpegkit.xcframework belongs to FFmpegKitNext. The libav* xcframeworks belong to FFmpeg.

You can use the libav* frameworks without ffmpegkit if you only need FFmpeg's C APIs. You cannot use ffmpegkit alone; it is built and linked against the generated libav* frameworks.

Adding a second FFmpeg implementation to the same Apple app can cause link failures, runtime loader failures, wrong-symbol resolution, ABI/configuration mismatches, or crashes. Whether it works depends on how the second implementation is packaged and linked. In some cases, there is no reliable fix other than using only one FFmpeg implementation.

1. Recommended approach

Use one FFmpeg implementation in the final app whenever possible.

• If another dependency can be built without its bundled FFmpeg, disable FFmpeg there and use the FFmpegKitNext frameworks.
• If you need FFmpeg APIs directly, use the libav* frameworks generated by FFmpegKitNext instead of adding another FFmpeg build.
• Do not mix ffmpegkit from one FFmpegKitNext build with libav* frameworks from another FFmpegKitNext build, version, profile or feature set.
• Do not replace the generated libav* frameworks with a different FFmpeg build unless you are prepared to debug ABI and configuration differences yourself.

2. Second FFmpeg embedded in one framework or library

Some libraries package FFmpeg inside a single framework or library instead of exposing separate libav* frameworks. MobileVLCKit is a common example of this packaging style.

If you must use one of those libraries together with FFmpegKitNext, link and embed the complete FFmpegKitNext framework set first, then link the other framework/library after it.

Keep the FFmpegKitNext frameworks together:

-framework "ffmpegkit"
-framework "libavcodec"
-framework "libavdevice"
-framework "libavfilter"
-framework "libavformat"
-framework "libavutil"
-framework "libswresample"
-framework "libswscale"

Then place the second FFmpeg-containing framework after them, for example:

-framework "MobileVLCKit"

Where to check this depends on your integration method:

• Manual Xcode integration: check the app target's Build Phases > Link Binary With Libraries order and Build Settings > Other Linker Flags.
• Swift Package Manager: inspect the linked products and generated linker invocation if there is a conflict.
• CocoaPods for the other dependency: inspect the generated Pods-<App>.xcconfig files and the app target's final OTHER_LDFLAGS.

This order can avoid some symbol-resolution problems, but it is not a guarantee. Test every platform and architecture you ship.

3. Second FFmpeg packaged as separate libav* frameworks

If the second implementation also packages FFmpeg as separate frameworks such as libavcodec, libavformat, libavutil, and so on, do not embed both framework sets.

Apple apps should not contain two independent copies of frameworks with the same names and overlapping FFmpeg symbols. One set will need to be removed, ignored or replaced.

The practical options are:

• Use FFmpegKitNext's generated libav* frameworks and remove the second implementation's FFmpeg frameworks, if that library can link against them.
• Use the second implementation's FFmpeg frameworks and remove FFmpegKitNext, if you do not need the FFmpegKitNext wrapper API.
• Rebuild one of the libraries so both dependencies use the same FFmpeg framework set.

ffmpegkit is built against the libav* frameworks produced by the same FFmpegKitNext build. Replacing those frameworks with another FFmpeg distribution may compile or link but still fail at runtime because of different enabled libraries, symbol versions, struct layouts, or compile-time configuration.

4. Second FFmpeg statically linked into another library

Some dependencies include FFmpeg object files inside a static .a library or package them into a larger static library. This can fail at link time with duplicate symbols, especially when -all_load, -force_load or broad Objective-C/static-library loading flags are used.

When that happens:

• Prefer rebuilding the dependency without its embedded FFmpeg.
• Avoid -all_load or -force_load for the FFmpeg-containing static library unless the dependency explicitly requires it.
• Use nm or Xcode's link map to confirm which library contributes the duplicate FFmpeg symbols.
• Keep only one FFmpeg implementation in the final link whenever possible.

5. Debugging checklist

When multiple FFmpeg implementations are involved, verify the final app rather than only the dependency declarations.

• Confirm which ffmpegkit and libav* frameworks are embedded in the final .app.
• Use otool -L to inspect the dynamic libraries loaded by the app and by each framework.
• Check Xcode's final OTHER_LDFLAGS and link order.
• Check whether the second dependency statically embeds FFmpeg symbols.
• Test on a real device and simulator for every platform you support.

If the app still fails with undefined symbols, duplicate symbols, dyld loader errors or unexplained crashes, remove one FFmpeg implementation. That is usually safer than trying to make two unrelated FFmpeg builds coexist in the same process.