Skip to content

frontend, appimage: Tell the user how to fix a missing VA-API encoder (driver not installed, no render group, no encode entrypoint) #1862

Closed

Description

@zackees

Problem. In #1720 a user's imported profile used ffmpeg_vaapi_tex. Finding out why it was missing took about ten rounds of support. The causes were all on the host and each has a one-line fix, but OBS never named one:

  1. No VA-API driver for the GPU was installed (iHD_drv_video.so absent; libva only says va_openDriver() returns -1). Fix: sudo apt install intel-media-va-driver-non-free (Intel), mesa-va-drivers (AMD).
  2. The user could not open /dev/dri/renderD128 (not in the render/video group). Fix: sudo usermod -aG render,video $USER, then log in again.
  3. The driver loads but lists no VAEntrypointEncSlice for the codec (hardware can't encode it). Fix: pick another encoder.
  4. NVIDIA GPU: VA-API encode is not available. Fix: use NVENC.

#1841 replaced "Unknown" with EncoderMissing.VAAPI.NotSupported ("Run vainfo to check…"). That still leaves the user to diagnose it.

Proposal. At startup, classify why VA-API has no encoder and keep the result:

  • the GPU vendor of each render node (/sys/class/drm/renderD*/device/vendor),
  • whether the node is readable by this user,
  • which driver files exist in the hostlib search dirs (build-aux/appimage/hostlib/hostlib.c), and, if one exists, whether its dependencies resolve,
  • whether vaInitialize succeeds and which encode entrypoints it lists.

Map the result to one cause from the list above. Print it as a VAAPI: log line, and show it in the Missing Encoders dialog with the exact command for the user's distro family (apt/dnf/pacman, falling back to the package name). The same treatment applies to the QSV "module not loaded in this build" case (#1720: the profile's recording encoder was still QSV), which should say "This build does not include Quick Sync; choose FFmpeg VAAPI H.264 in Settings → Output → Recording."

Testing (no new CI time, no GPU). Keep the classifier a pure function over an injected view of the system (sysfs root, /dev/dri permissions, driver dir, a fake vaInitialize result). Tier 1 Rust unit tests or a cmocka case in the existing binary cover each cause with fixture directories. One table-driven test per cause, all in-process, runs in milliseconds. Add a differential case where a C reference exists. No hardware lane.

Acceptance.

  • Each of causes 1-4, plus "QSV not in this build", gives a distinct dialog message with a fix the user can run, and a matching VAAPI:/QSV: log line.
  • Fixture tests for every cause, inside the existing test binaries (testing-policy category map).
  • features.md line.

Refs #1720, #1841.

Activity

  1. zackees commented on Oct 23, 2026

    @zackees
    MemberAuthor

    Claiming: #1862, one PR.

    1. RED: a Qt-free profile_vaapi_diagnose() in frontend/utility/profile-activate (next to frontend: Say why a VA-API or QSV encoder from a profile is missing #1841's profile_missing_encoder_reason()), stubbed, with cmocka cases added to the existing test_profile_activate binary. No new executable, no new CI lane.
    2. GREEN: classify render node → vendor → access → driver file, plus the distro's install command; dialog strings, a VAAPI: log line, and a QSV "not in this build" message; features.md.

    Decisions:

    • No libva in the frontend. obs-ffmpeg already ran vaInitialize; the frontend only reads /dev/dri/renderD128-135, /sys/class/drm/renderD*/device/vendor, the VA driver files in the standard dri dirs, and /etc/os-release, through an injected file-access table. Tests use fakes: no fixture dirs, no root/permission tricks, milliseconds.
    • "Driver present + accessible but no encoder" stays the existing NotSupported message (cause 3).
    • An unrecognized distro gets the package name instead of a command.

    First PR expected this session.

  2. added
    claimedAn agent or person has claimed this; check the claim comment before starting
    on Oct 23, 2026
  3. added a commit that references this issue on Oct 23, 2026
    941bc35
  4. zackees commented on Oct 23, 2026

    @zackees
    MemberAuthor

    Fixed by #1872 (merged 0e733c1): the Missing Encoders dialog names the VA-API cause (no render device, NVIDIA only, no render-group access, no driver installed with the distro install command, or cannot encode), logs a VAAPI: line, and a build without QSV says to pick another encoder for Streaming and Recording. Nothing left here; QSV itself continues in #1863.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claimedAn agent or person has claimed this; check the claim comment before starting

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions