FFmpeg stub libraries on Linux and Android | Qt Multimedia | Qt 6.11.1
Description: This document explains the stub mechanism used for FFmpeg's dynamic dependencies on Linux and Android platforms.

- Qt 6.11
- Qt Multimedia
- Building Qt Multimedia from sources
- Building FFmpeg from source
- FFmpeg stub libraries on Linux and Android
- Qt 6.11.1 Reference Documentation

Building FFmpeg for Android on Linux ◦ Upgrading from Qt 5

# 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)

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.

Building FFmpeg for Android on Linux ◦ Upgrading from Qt 5