feat(vulkan): add vk_quality config option by neatnoise · Pull Request #5783 · LizardByte/Sunshine

neatnoise · 2026-09-23T18:36:07Z

Description

Add a vk_quality config option for Vulkan encoder. Users can choose between speed, balanced, or quality presets.

The code queries the driver for supported quality levels using Vulkan Video API and maps presets to actual values:

speed: Level 0 (fastest encoding)
balanced: Middle level (max / 2) (default)
quality: Max level (best quality, slowest)

Reuses FFmpeg's existing Vulkan instance to query capabilities. No overhead when auto is selected.

Screenshot

Issues Fixed or Closed

Roadmap Issues

Type of Change

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

See our AI usage policy.

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

codecov · 2026-09-23T19:22:23Z

Bundle Report

Changes will increase total bundle size by 2.35kB (0.07%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sunshine-esm	990.8kB	2.35kB (0.24%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sunshine-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`assets/index-*.js`	245 bytes	400.04kB	0.06%
`assets/Config-*.js`	571 bytes	86.78kB	0.66%
`images/logo-*.svg`	-630 bytes	1.51kB	-29.47%
*`images/logo-.svg`** (New)	2.17kB	2.17kB	100.0% 🚀

github-actions · 2026-09-23T20:07:07Z


Last Updated	2026-09-24 03:06:54 UTC
Source Run	CI Run #5736
Commit	`da0afc2ed8907e108285f3b8c6eb8ff3c9eb2e06`

Screenshot Comparison

PR #5783 screenshots vs screenshots baseline.

Matrix: `AppImage-aarch64`

Image	Baseline	PR
`sunshine_tray_initial.png`
`sunshine_tray_menu.png`
`sunshine_tray_pairing_request.png`
`sunshine_tray_paused.png`
`sunshine_tray_stopped.png`
`sunshine_tray_streaming.png`
`sunshine_tray_tooltip.png`

Matrix: `AppImage-x86_64`

Image	Baseline	PR
`sunshine_tray_initial.png`
`sunshine_tray_menu.png`
`sunshine_tray_pairing_request.png`
`sunshine_tray_paused.png`
`sunshine_tray_stopped.png`
`sunshine_tray_streaming.png`
`sunshine_tray_tooltip.png`

Matrix: `Windows-AMD64`

Image	Baseline	PR
`sunshine_tray_initial.png`
`sunshine_tray_menu.png`
`sunshine_tray_pairing_request.png`
`sunshine_tray_paused.png`
`sunshine_tray_stopped.png`
`sunshine_tray_streaming.png`
`sunshine_tray_tooltip.png`

Matrix: `Windows-ARM64`

Image	Baseline	PR
`sunshine_tray_initial.png`
`sunshine_tray_menu.png`
`sunshine_tray_pairing_request.png`
`sunshine_tray_paused.png`
`sunshine_tray_stopped.png`
`sunshine_tray_streaming.png`
`sunshine_tray_tooltip.png`

Matrix: `macOS-arm64`

Image	Baseline	PR
`sunshine_tray_initial.png`
`sunshine_tray_menu.png`
`sunshine_tray_pairing_request.png`
`sunshine_tray_paused.png`
`sunshine_tray_stopped.png`
`sunshine_tray_streaming.png`
`sunshine_tray_tooltip.png`

Matrix: `macOS-x86_64`

Image	Baseline	PR
`sunshine_tray_initial.png`
`sunshine_tray_menu.png`
`sunshine_tray_pairing_request.png`
`sunshine_tray_paused.png`
`sunshine_tray_stopped.png`
`sunshine_tray_streaming.png`
`sunshine_tray_tooltip.png`

neatnoise · 2026-09-24T01:49:23Z

The tests are very welcome. I'm thinking about making the default "balanced" option. When "auto" is chosen, ffmpeg sets to 0 (which basically equals to "speed" option).

In my case (AMD RX 9070 XT) the "prefer quality" option hugely improved video without noticeable increased latency.
I use mostly H264 1080p 60 fps. The best vulkan encoding settings are for me: ultra low latency tuning, CBR rate control and the new "prefer quality" option.

ReenigneArcher · 2026-09-24T02:12:35Z

I believe we normally try to have the fastest options as defaults. For 1080p it probably doesn't matter much, but when people push to 4k I'm sure it does.

codecov · 2026-09-24T03:07:07Z

Codecov Report

❌ Patch coverage is 6.40000% with 117 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.40%. Comparing base (08131c5) to head (b74333b).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/platform/linux/vulkan_encode.cpp	0.00%	107 Missing and 9 partials ⚠️
src/config.cpp	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5783      +/-   ##
==========================================
- Coverage   39.54%   39.40%   -0.15%     
==========================================
  Files         122      122              
  Lines       28196    28321     +125     
  Branches    12319    12353      +34     
==========================================
+ Hits        11151    11159       +8     
+ Misses      14745    14168     -577     
- Partials     2300     2994     +694

Flag	Coverage Δ
Alpine-aarch64	`23.67% <1.76%> (-0.17%)`	⬇️
Alpine-x86_64	`23.79% <1.76%> (-0.17%)`	⬇️
Archlinux	`21.82% <1.76%> (-0.16%)`	⬇️
FreeBSD-amd64	`23.98% <3.38%> (-0.16%)`	⬇️
Homebrew-macos-15	`39.03% <77.77%> (+0.02%)`	⬆️
Homebrew-macos-26	`39.35% <77.77%> (+0.04%)`	⬆️
Homebrew-ubuntu-24.04	`25.33% <2.65%> (-0.16%)`	⬇️
Linux-AppImage-aarch64	`26.52% <2.65%> (-0.16%)`	⬇️
Linux-AppImage-x86_64	`26.69% <2.65%> (-0.17%)`	⬇️
PowerShell	`100.00% <ø> (ø)`
Web-UI	`68.42% <ø> (ø)`
Windows-AMD64	`31.08% <50.00%> (+<0.01%)`	⬆️
Windows-ARM64	`26.21% <50.00%> (+0.14%)`	⬆️
macOS-arm64	`32.42% <ø> (ø)`
macOS-x86_64	`33.01% <ø> (+0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/config.h	`18.75% <ø> (ø)`
...ets/common/assets/web/public/assets/locale/en.json	`100.00% <ø> (ø)`
src/config.cpp	`61.80% <88.88%> (+0.26%)`	⬆️
src/platform/linux/vulkan_encode.cpp	`0.27% <0.00%> (-0.06%)`	⬇️

... and 51 files with indirect coverage changes

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 08131c5...b74333b. Read the comment docs.

neatnoise · 2026-09-24T09:28:49Z

I tested all options (speed, balanced, quality) 4K 60 fps HEVC and AV1. Moonlight reports similar host latency in all cases

psyke83 · 2026-09-24T16:02:31Z

Confirmed working on a RX 6600. My card reports driver range 0-3, selects 1 for balanced and 3 for quality.

It's not a fault with this PR, but Vulkan encoding unfortunately looks quite a bit worse compared to VAAPI on my hardware. Vulkan with quality set to best and the highest quality tuning has obvious macroblock artifacting when dragging a window on the desktop at low bitrate (10Mbps, with VBR or CBR) that never shows on VAAPI even at its lowest quality level at the same bitrate or non-QP rate control method. I don't think we're mishandling or missing any of the important exposed AVOptions for Vulkan, so perhaps ffmpeg or the driver's implementation just isn't as mature as VAAPI on my particular hardware.

neatnoise · 2026-09-24T17:04:44Z

@psyke83 thanks for testing, It might heavily depend on the drivers. 9070 XT reports 4 quality levels, 2 (balanced) and 4 (quality) look superior

psyke83 · 2026-09-24T21:37:37Z

@neatnoise

You might need to adapt the same adjustment for the balanced quality if the Intel vulkan driver has the same limitation.

#5797

neatnoise · 2026-09-25T11:15:09Z

Added fallback if level doesn't exist, simplified config logic, made balanced default

ReenigneArcher · 2026-09-26T00:40:55Z

@neatnoise could you rebase this on master?

neatnoise · 2026-09-29T00:03:19Z

Rebased to master

Add user-configurable quality level for Vulkan Video encoders. The quality parameter trades encoding speed for better visual quality. Features: - Add vk_quality config option (0 = fastest, higher = better quality) - Query driver's maxQualityLevels via Vulkan API at stream start - Automatically clamp user value to driver's supported maximum - Reuse FFmpeg's Vulkan instance for efficient quality query (no overhead) - Cache render node lookup to avoid repeated instance creation (~10-20ms saved) - Log warning when clamping occurs The maximum quality level is driver-dependent: - AMD (RADV): typically 4 - NVIDIA/Intel: varies by driver Usage in sunshine.conf: vk_quality = 2

… balanced

sonarqubecloud · 2026-09-29T01:58:36Z

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

ReenigneArcher reviewed Sep 23, 2026

View reviewed changes

Comment thread docs/configuration.md Outdated

Comment thread docs/configuration.md Outdated

Comment thread src/config.cpp Outdated

neatnoise force-pushed the feat/vk-quality branch 4 times, most recently from 4adf946 to da0afc2 Compare September 23, 2026 19:19

neatnoise force-pushed the feat/vk-quality branch 2 times, most recently from bf12bb1 to 2f6c66a Compare September 25, 2026 11:08

neatnoise force-pushed the feat/vk-quality branch from 2f6c66a to 692740e Compare September 25, 2026 11:20

neatnoise force-pushed the feat/vk-quality branch from d10c71e to 7d75ef3 Compare September 29, 2026 00:02

neatnoise added 4 commits September 28, 2026 21:45

feat(vulkan): validate quality levels before setting

a5a7055

feat(vulkan): change default quality to balanced

0467e24

fix(vulkan): simplify quality config - remove auto option, default to…

b74333b

… balanced

ReenigneArcher force-pushed the feat/vk-quality branch from 7d75ef3 to b74333b Compare September 29, 2026 01:45

ReenigneArcher merged commit d41a2a3 into LizardByte:master Sep 29, 2026
66 of 68 checks passed

Conversation

neatnoise commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Screenshot

Issues Fixed or Closed

Roadmap Issues

Type of Change

Checklist

AI Usage

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Uh oh!

github-actions Bot commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Screenshot Comparison

Matrix: AppImage-aarch64

Matrix: AppImage-x86_64

Matrix: Windows-AMD64

Matrix: Windows-ARM64

Matrix: macOS-arm64

Matrix: macOS-x86_64

Uh oh!

neatnoise commented Sep 24, 2026

Uh oh!

ReenigneArcher commented Sep 24, 2026

Uh oh!

codecov Bot commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

neatnoise commented Sep 24, 2026

Uh oh!

psyke83 commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neatnoise commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

psyke83 commented Sep 24, 2026

Uh oh!

neatnoise commented Sep 25, 2026

Uh oh!

ReenigneArcher commented Sep 26, 2026

Uh oh!

neatnoise commented Sep 29, 2026

Uh oh!

sonarqubecloud Bot commented Sep 29, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

neatnoise commented Sep 23, 2026 •

edited

Loading

codecov Bot commented Sep 23, 2026 •

edited

Loading

github-actions Bot commented Sep 23, 2026 •

edited

Loading

Matrix: `AppImage-aarch64`

Matrix: `AppImage-x86_64`

Matrix: `Windows-AMD64`

Matrix: `Windows-ARM64`

Matrix: `macOS-arm64`

Matrix: `macOS-x86_64`

codecov Bot commented Sep 24, 2026 •

edited

Loading

psyke83 commented Sep 24, 2026 •

edited

Loading

neatnoise commented Sep 24, 2026 •

edited

Loading