Hardware Acceleration¶

MediaX supports hardware-accelerated video encoding and decoding on a variety of platforms and GPU hardware.

Supported Platforms¶

CI builds run on Ubuntu 24.04/26.04 (amd64), Ubuntu 24.04 (arm64, on an NVIDIA Jetson) and AlmaLinux 9/10. Windows is not a supported platform (the RTSP client is not available there).

Supported Codecs¶

The codec is selected by the payloader / depayloader class (or ColourspaceType) and announced through SAP/SDP using the dynamic payload types 96 (uncompressed), 98 (AV1), 103 (H.264) and 104 (H.265). JPEG uses the static payload type 26.

Acceleration Backends¶

MediaX uses native backends to access hardware encoders and decoders. The following backends are available depending on your hardware:

Platform / Backend Matrix¶

✅ supported and exercised in CI or the platform documentation · ⚙ supported when the dependency or device is present (not provisioned in CI) · — not applicable

Codec / Backend Matrix¶

CMake Build Options¶

Enable hardware acceleration at build time:

# Intel/AMD VAAPI
cmake -DVAAPI_SUPPORTED=ON ..

# CUDA colourspace acceleration
cmake -DBUILD_CUDA=ON ..

# NVIDIA NVENC/NVDEC H.264
cmake -DNVENC_SUPPORTED=ON ..

# OpenH264 software codec
cmake -DBUILD_OPENH264=ON ..

# All options combined
cmake -DVAAPI_SUPPORTED=ON -DBUILD_CUDA=ON ..

Intel VAAPI Setup¶

Install Drivers¶

# Ubuntu 24.04 / 26.04
sudo apt install -y \
    intel-media-va-driver \
    libva-dev

Verify Installation¶

# Check VA-API support
vainfo

Usage¶

#include "h264/vaapi/rtp_h264_vaapi_payloader.h"
#include "h265/vaapi/rtp_h265_vaapi_payloader.h"

// H.264 with VAAPI
mediax::rtp::h264::vaapi::RtpH264VaapiPayloader h264_payloader;

// H.265 with VAAPI
mediax::rtp::h265::vaapi::RtpH265VaapiPayloader h265_payloader;

Native VAAPI AV1¶

MediaX includes a native VAAPI AV1 backend that uses libva directly. This is automatically built when CMake detects libva (LIBVA_FOUND).

Requirements¶

• Decode: Intel 11th gen+ or AMD RDNA2+
• Encode: Intel 12th gen+ or AMD RDNA3+

Verify Support¶

# Check for AV1 profiles
vainfo 2>&1 | grep -i av1

# You should see entries like:
#   VAProfileAV1Profile0   : VAEntrypointVLD        (decode)
#   VAProfileAV1Profile0   : VAEntrypointEncSliceLP  (encode)

Usage¶

#include "av1/vaapi/rtp_av1_vaapi_payloader.h"
#include "av1/vaapi/rtp_av1_vaapi_depayloader.h"

// AV1 encode + transmit (native VAAPI)
mediax::rtp::av1::vaapi::RtpAv1VaapiPayloader av1_payloader;

// AV1 receive + decode (native VAAPI)
mediax::rtp::av1::vaapi::RtpAv1VaapiDepayloader av1_depayloader;

// Check availability at runtime
if (mediax::rtp::av1::vaapi::RtpAv1VaapiPayloader::IsVaapiAvailable()) {
  // Hardware AV1 encoding is available
}

Android AMediaCodec¶

MediaX includes a native H.264 backend for Android using the NDK's AMediaCodec API — see Android Support for build instructions, usage, and Qt6 integration (including the multicast lock required for reliable RTP/SAP reception on Android Wi-Fi).

Performance Comparison¶

Typical encoding performance for 1920×1080 @ 30fps:

CUDA Colourspace Acceleration¶

MediaX can use CUDA for GPU-accelerated colourspace conversions (RGB ↔ YUV, scaling, etc.) independently of video codec acceleration:

cmake -DBUILD_CUDA=ON ..

The GPU architecture defaults to 75 (Turing), which also runs on newer GPUs through PTX. Choose the architecture of your GPU with -DCMAKE_CUDA_ARCHITECTURES, for example 87 for Jetson Orin, or native to build for the GPU in the build machine (CMake 3.24 or newer). On NVIDIA Jetson the CUDA toolkit is in /usr/local/cuda, add /usr/local/cuda/bin to PATH so CMake finds nvcc. The Ubuntu 24.04 arm64 CI build runs on a Jetson with -DBUILD_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=native.

Supported conversions include:

• RGB24 ↔ YUV422
• RGB24 ↔ Mono8/Mono16
• NV12 → BGRA / RGB
• YUV → ARGB
• Bilinear scaling (BGRA)

CUDA acceleration requires an NVIDIA GPU and the CUDA toolkit.

AVX2 Colourspace Acceleration¶

On x86_64 platforms (Ubuntu 24.04/26.04, AlmaLinux 9/10), MediaX automatically detects AVX2 support at runtime and uses SIMD-accelerated colourspace conversions when available. No build flags are required — AVX2 is compiled as a separate object library with -mavx2 and dispatched via CPUID at startup.

AVX2-accelerated functions:

On CPUs without AVX2 (or on ARM platforms), these functions automatically fall back to the optimised scalar CPU implementation. No application code changes are needed.

Platform Availability¶

Troubleshooting¶

No Hardware Acceleration Detected¶

1. Verify driver installation with vainfo
2. Ensure the correct CMake option is enabled (-DVAAPI_SUPPORTED=ON)

Fallback to Software Encoding¶

If hardware encoding fails, MediaX falls back to OpenH264 software encoding. Check build output for warnings about missing hardware support.

VAAPI Permission Denied¶

# Add user to video and render groups
sudo usermod -aG video,render $USER
# Log out and back in

Diagnostic Output¶

The library is silent by default (errors and warnings still go to stderr). To see which codec, encoder and device were selected, set MEDIAX_LOG:

MEDIAX_LOG=info ./my_app    # codec/device initialisation and selected encoder
MEDIAX_LOG=debug ./my_app   # plus per-frame and bitstream diagnostics

Applications can also call mediax::SetLogLevel(mediax::LogLevel::kInfo) (see utils/log.h). The Qt6 session manager uses the Qt logging category mediax.sap.session: QT_LOGGING_RULES="mediax.sap.session.debug=true".

Support¶

• Website: https://astutesys.com/support
• Email: support@astutesys.com