[Solved] Black Screen Video Playback with VAAPI (GStreamer/Intel)

General Discussion
1

TL;DR: If you are seeing a black screen when playing H.264 videos using GStreamer and VAAPI, it is likely due to a driver bug incorrectly flagging the video as Stereoscopic 3D (views=2). The fix is to force software decoding or remove the problematic plugin.

The Issue

When running GStreamer applications on systems with Intel/VAAPI hardware acceleration enabled, certain video files—typically H.264 High Profile MP4s—may play with a black screen. The pipeline runs without crashing, audio might play, but the video output is invisible.

The Root Cause

Our investigation revealed that the VAAPI hardware driver (gstreamer-vaapi) incorrectly identifies standard 2D video files as Stereoscopic 3D (Multiview).

  • Diagnostics: Running gst-launch-1.0 -v … showed the decoder outputting caps with views=(int)2.

  • Impact: Downstream elements receive this 3D metadata and attempt to render a “second view” (which is empty/black) or fail to negotiate a valid display format.

  • Verification: Software decoding (avdec_h264) works perfectly because it correctly identifies the video as 2D (views=1).

The Solution

You can fix this by disabling the buggy hardware decoder, either for your specific application or system-wide.

Option 1: Disable in Python (Recommended for Developers)

Force your application to use software decoding by disabling the VAAPI rank. Add this at the very top of your script:


import os

# Force software decoding to avoid VAAPI "views=2" bug causing black screens

os.environ["GST_PLUGIN_FEATURE_RANK"] = "vaapidecodebin:NONE"

import gi

gi.require_version("Gst", "1.0")

Option 2: Disable via Environment Variable

Run your application with the environment variable set. This works for any GStreamer app without code changes:


export GST_PLUGIN_FEATURE_RANK=vaapidecodebin:NONE

python your_app.py

Option 3: System-Wide Uninstall

If you do not need VAAPI hardware acceleration for other tasks, you can uninstall the plugin entirely. This ensures GStreamer always uses the stable software decoders.

sudo apt remove gstreamer1.0-vaapi

1 Like