feat(linux): async_depth configuration for VA-API

[inkatail]

Description

This PR implements async_depth configuration for VA-API encoder, which seems to fix FPS stability in most games, at the cost of increasing latency, my testing was done with the value set at 4, but I decided to make the default 1 since I kinda just didn't spend too much time on testing to get a perfect default.
All of this has been done with AI, as I am not really experienced with programming, but the FPS stability issues kept being annoying since I switched to Linux, and instead of waiting I just decided to try doing anything with it.
This PR might be not perfect and probably might be improved by someone who knows VA-API more than me.

Screenshot

Issues Fixed or Closed

• Resolves Inconsistent FPS in Certain Games #4693

Roadmap Issues

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[ReenigneArcher]

Thanks for the PR. I'm not an expert on va-api. Is a value of 1 the same as the existing behavior?

In addition to my review below, docs/configuration.md will also need to be updated.

[psyke83]

The issue you're trying to solve seems to be encoder starvation due to high GPU load and VAAPI not having higher GPU process priority. It's possible that the Vulkan encoder may behave better, so I would recommended testing that before committing to this path. Regardless, it should definitely not be changed from the default of 1 as it will increase latency.

[inkatail]

The issue you're trying to solve seems to be encoder starvation due to high GPU load and VAAPI not having higher GPU process priority. It's possible that the Vulkan encoder may behave better, so I would recommended testing that before committing to this path. Regardless, it should definitely not be changed from the default of 1 as it will increase latency.

I tested the Vulkan encoder pull request, and It seems to work about the same (bad) in this situation.
(Yes, I confirmed it uses the Vulkan encoder properly)

[codecov]

Bundle Report

Changes will increase total bundle size by 614 bytes (0.08%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sunshine-esm	773.58kB	614 bytes (0.08%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sunshine-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
assets/_plugin-*.js	190 bytes	350.86kB	0.05%
assets/config-*.js	424 bytes	67.62kB	0.63%

Files in assets/_plugin-*.js:

• ./src_assets/common/assets/web/public/assets/locale/en.json → Total Size: 37.47kB

Files in assets/config-*.js:

• ./src_assets/common/assets/web/configs/tabs/encoders/VAAPIEncoder.vue → Total Size: 1.49kB

[ReenigneArcher]

@inkatail we have a test to ensure config options are properly defined everywhere. Looks like it was missed in one place.

[147](https://github.com/LizardByte/Sunshine/actions/runs/22447045856/job/65004456793?pr=4745#step:11:2148)
[ RUN      ] ConfigConsistencyTest.AllConfigOptionsExistInAllFiles
/__w/Sunshine/Sunshine/pkg/src/sunshine/tests/integration/test_config_consistency.cpp:466: Failure
Failed
Config options missing from files:
  config.html missing: vaapi_async_depth


[2026-02-26 15:04:43.808]: Tests: From /__w/Sunshine/Sunshine/pkg/src/sunshine/tests/integration/test_config_consistency.cpp:439
[2026-02-26 15:04:43.808]: Tests:   ConfigConsistencyTest/AllConfigOptionsExistInAllFiles started
[2026-02-26 15:04:43.845]: Tests: At /__w/Sunshine/Sunshine/pkg/src/sunshine/tests/integration/test_config_consistency.cpp:466
[2026-02-26 15:04:43.845]: Tests:   Failure: Failed
Config options missing from files:
  config.html missing: vaapi_async_depth

[2026-02-26 15:04:43.845]: Tests: ConfigConsistencyTest/AllConfigOptionsExistInAllFiles failed
[  FAILED  ] ConfigConsistencyTest.AllConfigOptionsExistInAllFiles (36 ms)

[codecov]

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
280	1	279	11

View the top 1 failed test(s) by shortest run time

ConfigConsistencyTest::AllConfigOptionsExistInAllFiles

Stack Traces | 0.053s run time

D:.../tests/integration/test_config_consistency.cpp:466
Failed
Config options missing from files:
  config.html missing: vaapi_async_depth

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[psyke83]

@inkatail @ReenigneArcher

Won't this PR be incomplete once Vulkan support is merged? That also uses the same parameter with the same behaviour.

conn@ryzenl:~/work/sunshine$ ffmpeg -h encoder=hevc_vulkan 2>&1 | grep -C2 async_depth
  -idr_interval      <int>        E..V....... Distance (in I-frames) between key frames (from 0 to INT_MAX) (default 0)
  -b_depth           <int>        E..V....... Maximum B-frame reference depth (from 1 to INT_MAX) (default 1)
  -async_depth       <int>        E..V....... Maximum processing parallelism. Increase this to improve single channel performance. (from 1 to 64) (default 2)
  -qp                <int>        E..V....... Use an explicit constant quantizer for the whole stream (from -1 to 255) (default -1)
  -quality           <int>        E..V....... Set encode quality (trades off against speed, higher is faster) (from 0 to INT_MAX) (default 0)
conn@ryzenl:~/work/sunshine$ ffmpeg -h encoder=h264_vulkan 2>&1 | grep -C2 async_depth
  -idr_interval      <int>        E..V....... Distance (in I-frames) between key frames (from 0 to INT_MAX) (default 0)
  -b_depth           <int>        E..V....... Maximum B-frame reference depth (from 1 to INT_MAX) (default 1)
  -async_depth       <int>        E..V....... Maximum processing parallelism. Increase this to improve single channel performance. (from 1 to 64) (default 2)
  -qp                <int>        E..V....... Use an explicit constant quantizer for the whole stream (from -1 to 255) (default -1)
  -quality           <int>        E..V....... Set encode quality (trades off against speed, higher is faster) (from 0 to INT_MAX) (default 0)

@inkatail have you tried portalgrab without changing async_depth to see if it performs any better under heavy load? It might have less slowdown due to the frames being grabbed from the compositor and not having to wait for read after the framebuffer write that's done via kms.

[inkatail]

@inkatail @ReenigneArcher

Won't this PR be incomplete once Vulkan support is merged? That also uses the same parameter with the same behaviour.

conn@ryzenl:~/work/sunshine$ ffmpeg -h encoder=hevc_vulkan 2>&1 | grep -C2 async_depth
  -idr_interval      <int>        E..V....... Distance (in I-frames) between key frames (from 0 to INT_MAX) (default 0)
  -b_depth           <int>        E..V....... Maximum B-frame reference depth (from 1 to INT_MAX) (default 1)
  -async_depth       <int>        E..V....... Maximum processing parallelism. Increase this to improve single channel performance. (from 1 to 64) (default 2)
  -qp                <int>        E..V....... Use an explicit constant quantizer for the whole stream (from -1 to 255) (default -1)
  -quality           <int>        E..V....... Set encode quality (trades off against speed, higher is faster) (from 0 to INT_MAX) (default 0)
conn@ryzenl:~/work/sunshine$ ffmpeg -h encoder=h264_vulkan 2>&1 | grep -C2 async_depth
  -idr_interval      <int>        E..V....... Distance (in I-frames) between key frames (from 0 to INT_MAX) (default 0)
  -b_depth           <int>        E..V....... Maximum B-frame reference depth (from 1 to INT_MAX) (default 1)
  -async_depth       <int>        E..V....... Maximum processing parallelism. Increase this to improve single channel performance. (from 1 to 64) (default 2)
  -qp                <int>        E..V....... Use an explicit constant quantizer for the whole stream (from -1 to 255) (default -1)
  -quality           <int>        E..V....... Set encode quality (trades off against speed, higher is faster) (from 0 to INT_MAX) (default 0)

@inkatail have you tried portalgrab without changing async_depth to see if it performs any better under heavy load? It might have less slowdown due to the frames being grabbed from the compositor and not having to wait for read after the framebuffer write that's done via kms.

@psyke83 Well I have tested that, It seemed a little better but I still experienced this overall bad feeling.
About Vulkan, I will probably work on adding that there too when it's merged

[inkatail]

@inkatail we have a test to ensure config options are properly defined everywhere. Looks like it was missed in one place.

[147](https://github.com/LizardByte/Sunshine/actions/runs/22447045856/job/65004456793?pr=4745#step:11:2148)
[ RUN      ] ConfigConsistencyTest.AllConfigOptionsExistInAllFiles
/__w/Sunshine/Sunshine/pkg/src/sunshine/tests/integration/test_config_consistency.cpp:466: Failure
Failed
Config options missing from files:
  config.html missing: vaapi_async_depth


[2026-02-26 15:04:43.808]: Tests: From /__w/Sunshine/Sunshine/pkg/src/sunshine/tests/integration/test_config_consistency.cpp:439
[2026-02-26 15:04:43.808]: Tests:   ConfigConsistencyTest/AllConfigOptionsExistInAllFiles started
[2026-02-26 15:04:43.845]: Tests: At /__w/Sunshine/Sunshine/pkg/src/sunshine/tests/integration/test_config_consistency.cpp:466
[2026-02-26 15:04:43.845]: Tests:   Failure: Failed
Config options missing from files:
  config.html missing: vaapi_async_depth

[2026-02-26 15:04:43.845]: Tests: ConfigConsistencyTest/AllConfigOptionsExistInAllFiles failed
[  FAILED  ] ConfigConsistencyTest.AllConfigOptionsExistInAllFiles (36 ms)

@ReenigneArcher Should be correct now, I think.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud