feat(amf): add amd_max_au_size option

[pollopopo]

Description

Adds a new optional AMF encoder parameter amd_max_au_size that exposes the existing FFmpeg/AMF maximum Access Unit size option to Sunshine users. This is not a silver bullet — it is an additional tool in the toolbox for users who have exhausted other options and are still experiencing stream instability, particularly on problematic Wi-Fi connections.

Most users will never need this setting. The existing rate control modes (VBR_LATENCY, CBR) and other options (enforce_hrd, vbaq, preanalysis) should be the first line of troubleshooting. This option is intended as a last resort for difficult network conditions where standard rate control cannot prevent occasional oversized frames from disrupting the stream.

Background

Sunshine uses FEC (Forward Error Correction) to protect video frames against packet loss. FEC has a hard limit: each block supports max 255 data shards, with max 4 blocks per frame. When an encoded frame exceeds this limit (~889 KB at default settings), FEC is disabled for that frame:

// stream.cpp line 1373
if (fec_blocks_needed > MAX_FEC_BLOCKS) {
    BOOST_LOG(warning) << "Skipping FEC for abnormally large encoded frame...";
    fecPercentage = 0;
}

Additionally, large encoded frames produce large packet bursts that can overwhelm Wi-Fi TX queues, causing packet loss even when the link has sufficient average bandwidth.

Standard rate control modes (VBR, CBR) treat bitrate targets as soft constraints and can still produce occasional frame size spikes during high-complexity scenes. For most users on decent networks, these spikes are harmless. But on congested or unreliable Wi-Fi, they can be the difference between a stable and unstable stream.

What this PR does

Exposes the AMF max_au_size encoder option, which sets a hard, hardware-enforced cap on the maximum encoded frame size in bits. This maps to AMF_VIDEO_ENCODER_MAX_AU_SIZE (H.264) and AMF_VIDEO_ENCODER_HEVC_MAX_AU_SIZE (HEVC). AV1 does not support this option and has been excluded.

• Disabled by default — no change to existing behavior for any user
• Optional — uses std::optional<int>, completely ignored when not set (FFmpeg default: -1)
• Zero overhead — the cap is enforced by the AMF hardware encoder, not in software
• Follows existing patterns — same implementation approach as amd_enforce_hrd, amd_vbaq, etc.

When to use it

This setting is for users who:

• Are streaming over Wi-Fi and experiencing dropped frames or stuttering
• Have already tried adjusting bitrate, rate control mode, FEC percentage, and other standard settings
• Are still seeing instability due to occasional frame size spikes

It is not a replacement for proper rate control configuration and network optimization.

Trade-offs

When the cap is hit, the encoder is forced to reduce quality for that frame, which may cause brief visual quality drops. The value also effectively limits the maximum bitrate regardless of what is configured in the client. Users should set it as high as their network reliably handles — not lower than necessary.

Choosing a value

The value is in bits. It controls the maximum size of any single encoded frame. Start with 800000 (~97 KB per frame, ~46 Mbps at 60fps) and increase until you find the highest value that remains stable on your network.

Value	Max frame size	Max bitrate at 60fps
800000	~97 KB	~46 Mbps
1000000	~122 KB	~58 Mbps
1600000	~195 KB	~93 Mbps

Screenshot

New "AMF Max AU Size (bits)" field appears in the AMD AMF Encoder > Rate Control Settings section of the Web UI.

Issues Fixed or Closed

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

[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

[LizardByte-bot]

It looks like this PR has been idle for 90 days. If it's still something you're working on or would like to pursue, please leave a comment or update your branch. Otherwise, we'll be closing this PR in 10 days to reduce our backlog. Thanks!

[codecov]

Bundle Report

Changes will decrease total bundle size by 267 bytes (-0.01%) ⬇️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sunshine-esm	878.67kB	-267 bytes (-0.03%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: sunshine-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
assets/logo-*.js	-15 bytes	384.71kB	-0.0%
assets/config-*.js	-252 bytes	73.54kB	-0.34%

Files in assets/logo-*.js:

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

Files in assets/config-*.js:

• ./src_assets/common/assets/web/config.html → Total Size: 0 bytes

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

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 33.81%. Comparing base (3dfbfe0) to head (e09df6b).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/video.cpp	0.00%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4926      +/-   ##
==========================================
+ Coverage   32.50%   33.81%   +1.31%     
==========================================
  Files         104      104              
  Lines       25003    25065      +62     
  Branches    11078    11087       +9     
==========================================
+ Hits         8126     8476     +350     
- Misses      13894    14804     +910     
+ Partials     2983     1785    -1198     

Flag	Coverage Δ
Archlinux	0.00% <0.00%> (ø)
FreeBSD-amd64	19.45% <77.77%> (+1.06%)	⬆️
Homebrew-macos-14	30.69% <100.00%> (+2.58%)	⬆️
Homebrew-macos-15	31.40% <100.00%> (+2.57%)	⬆️
Homebrew-macos-26	31.50% <100.00%> (+2.56%)	⬆️
Homebrew-ubuntu-24.04	20.76% <100.00%> (+1.69%)	⬆️
Linux-AppImage	20.17% <100.00%> (+1.70%)	⬆️
Windows-AMD64	25.76% <100.00%> (+1.96%)	⬆️
Windows-ARM64	21.64% <63.63%> (+1.11%)	⬆️
macOS-arm64	25.48% <ø> (+0.10%)	⬆️
macOS-x86_64	26.13% <ø> (+0.11%)	⬆️

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

Files with missing lines	Coverage Δ
src/config.cpp	59.82% <100.00%> (+35.62%)	⬆️
src/config.h	25.00% <ø> (+13.88%)	⬆️
src/video.cpp	54.31% <0.00%> (-0.06%)	⬇️

... and 58 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 3dfbfe0...e09df6b. Read the comment docs.

[github-actions]

Build artifacts

Artifacts from workflow run 32500593750:

• build-Archlinux
• build-Docker-debian-trixie
• build-Docker-ubuntu-22.04
• build-Docker-ubuntu-24.04
• build-Docker-ubuntu-26.04
• build-FreeBSD-amd64
• build-Homebrew
• build-Linux-AppImage
• build-Linux-Flatpak-aarch64
• build-Linux-Flatpak-x86_64
• build-macOS-arm64
• build-macOS-x86_64
• build-Windows-AMD64
• build-Windows-ARM64

_{You must be signed in to GitHub to download workflow artifacts.}

[github-actions]

Last Updated	2026-08-21 19:22:37 UTC
Source Run	CI Run #5063
Commit	e09df6bd26a6bf8c3e4026339cb134a589081b3f

Screenshot Comparison

PR #4926 screenshots vs screenshots baseline.

Matrix: AppImage

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

[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