qtmultimedia-building-FFmpeg-ios.qdoc

Go to the documentation of this file.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtmultimedia-building-ffmpeg-ios.html
\title Building FFmpeg from source for iOS on macOS
\brief This document describes how to build FFmpeg from source code.
 
\include building-FFmpeg-contents.qdocinc {ios}
\include building-FFmpeg-source.qdocinc {ios}
\include building-FFmpeg-prerequisites.qdocinc {ios}
\include building-FFmpeg-configure.qdocinc {ios}
 
\section1 Creating iOS frameworks from FFmpeg libraries
 
To work in iOS applications, FFmpeg dynamic libraries have to
be converted into frameworks and embedded into application bundles.
A framework is a hierarchical directory that encapsulates resources
such as a dynamic library, image files, localized strings, header files,
and reference documentation in a single package. In our case, FFmpeg frameworks
only contain dynamic libraries and corresponding Info.plist files.
For example, libavcodec converted to framework becomes \c libavcodec.framework
directory with these contents:
 
\list
\li Info.plist (containing the description of the framework)
\li libavcodec (dynamic library)
\endlist
 
Unlike dynamic libraries we built in the previous step, dynamic libraries
inside iOS frameworks are unversioned and have no 'dylib' extensions. This requires
fixing library identification names and dependencies in our dynamic libraries.
The \c otool utility helps us to find such names. For example:
 
\badcode
otool -L ../installed/lib/libavcodec.dylib
\endcode
 
gives us these names (we only show FFmpeg-related names):
 
\badcode
@rpath/libavcodec.61.dylib (compatibility version 61.0.0, current version 61.19.100)
@rpath/libswresample.5.dylib (compatibility version 5.0.0, current version 5.3.100)
@rpath/libavutil.59.dylib (compatibility version 59.0.0, current version 59.39.100)
\endcode
 
 To fix these names, use the \c install_name_tool utility. The utility options are:
 
 \list
 \li \c {-id} - allows changing the shared library identification name.
 \li \c {-change} - allows changing the dependent shared library install name.
 \endlist
 
This script converts the previously built dynamic libraries to frameworks. The code assumes
that you run it from the \c build directory and the frameworks are located in
\c{~/ffmpeg/installed/framework}:
 
\badcode
#!/usr/bin/env bash
 
# Creates an Info.plist file for a given framework:
build_info_plist() {
    local file_path="$1"
    local framework_name="$2"
    local framework_id="$3"
 
    # Minimum version must be the same we used when building FFmpeg.
    local minimum_version_key="MinimumOSVersion"
    local minimum_os_version="16.0"
 
    local supported_platforms="iPhoneOS"
 
    info_plist="<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">
<plist version=\"1.0\">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleExecutable</key>
    <string>${framework_name}</string>
    <key>CFBundleIdentifier</key>
    <string>${framework_id}</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>${framework_name}</string>
    <key>CFBundlePackageType</key>
    <string>FMWK</string>
    <key>CFBundleShortVersionString</key>
    <string>9.0.1</string>
    <key>CFBundleVersion</key>
    <string>9.0.1</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>${minimum_version_key}</key>
    <string>${minimum_os_version}</string>
    <key>CFBundleSupportedPlatforms</key>
    <array>
        <string>${supported_platforms}</string>
    </array>
    <key>NSPrincipalClass</key>
    <string></string>
</dict>
</plist>"
    echo $info_plist | tee ${file_path} 1>/dev/null
}
 
dylib_regex="^@rpath/.*\.dylib$"
 
# Creates framework from a dylib file:
create_framework() {
    local framework_name="$1"
    local ffmpeg_library_path="../installed"
    local framework_complete_path="${ffmpeg_library_path}/framework/${framework_name}.framework/${framework_name}"
 
    # Create framework directory and copy dylib file to this directory:
    mkdir -p "${ffmpeg_library_path}/framework/${framework_name}.framework"
    cp "${ffmpeg_library_path}/lib/${framework_name}.dylib" "${ffmpeg_library_path}/framework/${framework_name}.framework/${framework_name}"
 
    # Change the shared library identification name, removing version number and 'dylib' extension;
    # \c Frameworks part of the name is needed since this is where frameworks will be installed in
    # an application bundle:
    install_name_tool -id @rpath/Frameworks/${framework_name}.framework/${framework_name} "${framework_complete_path}"
 
    # Add Info.plist file into the framework directory:
    build_info_plist "${ffmpeg_library_path}/framework/${framework_name}.framework/Info.plist" "${framework_name}" "io.qt.ffmpegkit."${framework_name}
    otool -L "$framework_complete_path" | awk '/\t/ {print $1}' | egrep "$dylib_regex" | while read -r dependency_path; do
        found_name=$(tmp=${dependency_path/*\/}; echo ${tmp/\.*})
        if [ "$found_name" != "$framework_name" ]
        then
            # Change the dependent shared library install name to remove version number and 'dylib' extension:
            install_name_tool -change "$dependency_path" @rpath/Frameworks/${found_name}.framework/${found_name} "${framework_complete_path}"
        fi
    done
}
 
ffmpeg_libs="libavcodec libavformat libavutil libswresample libswscale"
 
for name in $ffmpeg_libs; do
    create_framework $name
done
 
\endcode
 
\section1 Creating a multiplatform binary framework bundle
 
An XCFramework bundle is a package that includes frameworks and libraries
necessary to build for multiple platforms, for example, iOS and iOS simulator.
To create such a framework, use the \c xcodebuild utility. For example, if
you have frameworks for iOS and simulator located in \c {~/ffmpeg/installed/arm64}
and \c {~/ffmpeg/installed/arm64-simulator} directories, the utility arguments look
like follows:
 
\badcode
xcodebuild -create-xcframework -framework ../installed/arm64/libavcodec.framework -framework ../installed/arm64-simulator/libavcodec.framework -output ../installed/framework/libavcodec.xcframework
\endcode
 
\section1 Embedding frameworks
 
Embed the FFmpeg frameworks into an application bundle. For information on how to
embed frameworks using XCode, refer to
 
\l{https://developer.apple.com/library/archive/technotes/tn2435/_index.html}{Embedding Frameworks In An App}.
 
*/