- Qt 6.12
- Qt Multimedia
- Building Qt Multimedia from sources
- Qt 6.12.0 Reference Documentation

Advanced FFmpeg Configuration ◦ Building FFmpeg

# Building Qt Multimedia from sources

This page describes the process of configuring and building Qt Multimedia. This description assumes familiarity with Building Qt Sources which specifies build requirements for your platform, as well as an overview of Qt Configure Options. For platform-specific considerations related to the Qt Multimedia module, see Platform Notes below.

## Building from source

Building Qt Multimedia with full feature support depends on FFmpeg headers and libraries on most platforms. It is possible to build Qt Multimedia without the Qt Multimedia FFmpeg media backend, but this is only recommended when building for platforms where the FFmpeg backend is not supported.

FFmpeg development libraries required to build Qt Multimedia can be built from sources or downloaded as binary packages. Qt Multimedia can use either static linking or dynamic linking to FFmpeg libraries. We recommend using the same major version of FFmpeg that is listed in Target platform and backend notes. For information on how to build the FFmpeg development libraries, see Building FFmpeg from source.

To build Qt Multimedia with FFmpeg support, specify the `-ffmpeg-dir` option on the configure command line when building Qt.

     qt-source/configure -ffmpeg-dir <FFMPEG_DIR>

Here, `<FFMPEG_DIR>` is the directory containing the FFmpeg include, lib, and bin directories. To build Qt Multimedia without FFmpeg, omit the `<FFMPEG_DIR>` variable and specify the `-no-feature-ffmpeg` configure option.

To build Qt Multimedia without native media backends, use `-no-feature-xxx` to exclude the corresponding features, such as `gstreamer`, `native_windows_backend`, `native_darwin_backend` or `native_android_backend`.

     qt-source/configure -no-feature-gstreamer

If you prefer not to build all Qt's submodules, you can reduce configure and build times using the `-submodules` configure option. This will configure a build that only builds Qt Multimedia and its dependencies.

     qt-source/configure -submodules qtmultimedia -ffmpeg-dir <FFMPEG_DIR>

If you configure Qt Multimedia against FFmpeg built with shared libraries (dynamic linking), the FFmpeg shared libraries must be in the module loader's search path to run tests or use examples.

Note: Qt Multimedia requires the FFmpeg avformat, avcodec, swresample, swscale, and avutil libraries during runtime to be able to use the FFmpeg media backend. If one or more of these dynamic libraries are not found during application startup, the FFmpeg media backend will fail to load, and the system will attempt to load the native backend. Qt Multimedia doesn't support as many features on native backends.

If you don't already have these libraries in the `path`, specify the `-ffmpeg-deploy` configure option. With this option enabled, the necessary FFmpeg binaries will be copied to Qt's install directory during the build and install steps:

     qt-source/configure -submodules qtmultimedia -ffmpeg-dir <FFMPEG_DIR> -ffmpeg-deploy

After configuring Qt Multimedia, carefully review the configure summary (found in the config.summary file). You can verify that FFmpeg is found under the "Plugin" section. Then follow the regular build and install steps described in Building Qt Sources.

Note: When building Qt Multimedia statically, the path to the FFmpeg libraries is baked into `libQt6FFmpegMediaPluginImpl.prl`. You will need to patch the path if your Qt is supposed to be used on a different machine.

## Platform Notes

### iOS

- When configuring Qt Multimedia with FFmpeg support, the CMake configuration process looks for `.xcframework` files in the supplied FFmpeg directory. Using `.dylib` binaries directly is not supported. See Building FFmpeg from source for iOS on macOS and https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle for details on how to package FFmpeg build artifacts into `.xcframework` files.

### Linux

- When configuring Qt Multimedia with FFmpeg enabled, the pipewire or the pulseaudio development package is required. Without one of these packages, FFmpeg will not be recognized.
- When using a version of FFmpeg that is built with VAAPI support, we recommend building Qt Multimedia with VAAPI support as well to make hardware texture conversion possible. To configure Qt Multimedia with VAAPI support, VAAPI developer libraries must be installed on your system. Review the config.summary file to verify that VAAPI support is enabled under the "Hardware acceleration and features" section.
- When configuring Qt Multimedia with the GStreamer backend, GStreamer v1.20 is the minimum requirement. However, we recommend using the latest stable GStreamer upstream release if possible.

Advanced FFmpeg Configuration ◦ Building FFmpeg