FFmpeg stub libraries on Linux and Android

Overview

To support dynamic linking of FFmpeg in compliance with the LGPL license, Qt Multimedia uses stub libraries to handle optional external dependencies on Linux and Android platforms.

On these platforms, FFmpeg may require additional shared libraries that are not shipped with Qt:

• OpenSSL - required for secure network streaming.
• VAAPI (Linux only) - enables hardware-accelerated video decoding and encoding.

These libraries are often not available or cannot be bundled due to licensing constraints. To ensure FFmpeg-based features remain functional (excluding the unsupported parts), Qt delivers stub libraries as fallbacks.

Why Stubs Are Needed

If these dependencies are not present at runtime, FFmpeg will fail to load or function properly. The stub mechanism allows:

• Successful loading of FFmpeg even when OpenSSL or VAAPI are missing.
• Graceful degradation of functionality (e.g., lack of VAAPI results in no hardware acceleration, but playback still works).
• Users to opt-in to using their own system-provided versions of these libraries if available.

What Stubs Are

Stub libraries mimic the interfaces of the real libraries (e.g., libssl.so, libva.so) but do not implement full functionality. Instead, they:

• Provide dummy implementations that return safe fallback values or no-ops.
• Dynamically attempt to resolve real symbols via QLibrary::load / QLibrary::resolve.
• Fail gracefully if real libraries are not found.

Qt ships these stubs under the names:

• libQt6FFmpegStub-ssl.so.x
• libQt6FFmpegStub-crypto.so.x
• libQt6FFmpegStub-va.so.x
• libQt6FFmpegStub-va-drm.so.x
• libQt6FFmpegStub-va-x11.so.x
• (more may be added in the future)

How Stubs Work in Qt

When FFmpeg is dynamically linked:

• It normally expects to be linked against system libraries like libssl.so.3 or libva.so.2.
• Qt patches the FFmpeg binaries using the patchelf tool to replace these real dependencies with stub equivalents.

Example:

# Original linkage
libffmpegmediaplugin.so: needs libavcodec.so (depends on the FFmpeg libs)
libavcodec.so: needs libssl.so.3

# After patching
libffmpegmediaplugin.so: needs libavcodec.so (no changes)
libavcodec.so: needs libQt6FFmpegStub-ssl.so.3
libQt6FFmpegStub-ssl.so.3: optionally needs libssl.so.3 (no explicit linkage)

This patching is performed automatically as part of the build/distribution process.

Runtime Behavior and Security Notes

• FFmpeg plugins are loaded with dlopen(..., RTLD_LOCAL), so stub symbols do not leak into the global symbol table.
• If the application already uses OpenSSL or VAAPI, the system libraries may be picked up from the global scope and must be binary compatible.
• The shipped QtMultimedia and FFmpeg binaries are compatible with:
  • OpenSSL 3.x.x (with symbol versioning @OPENSSL_3.0.0)
  • VAAPI ABI 0.33 (older ABI 0.32 is explicitly unsupported)
• It is also possible to build Qt Multimedia against OpenSSL 1.x.x, though compatibility depends on your FFmpeg configuration.

To completely remove the use of stub libraries, there are two options:

• Use patchelf to restore FFmpeg's dependencies back to the system libraries (e.g., replace libQt6FFmpegStub-ssl.so.3 with libssl.so.3). This must be done for all FFmpeg libraries: libavcodec, libavformat, libavutil, libswresample, and libswscale.
• Replace the shipped FFmpeg libraries with ones built manually by the user. See Building FFmpeg from source.