feat(linux)!: Support streaming through XDG portals and Pipewire #4417

ReenigneArcher · 2025-11-12T22:26:50Z

Description

This PR replaces #2507 ... Thanks to @garnacho for the initial work on this!

This PR adds a new "grab" implementation to use XDG desktop portals and Pipewire. There is a breaking change that comes along with this implementation, which is that the sunshine binaries provided by our packages will no longer have the setcap applied to them automatically for KMS capture. For the RPM packages built in our Copr repo, there is a new sunshine-kms binary which does have the setcap applied. This was done this way to work around rpm-ostree issues that do not allow the user to apply setcap manually.

TODO:

update homebrew formula, depends on pipewire 1.4.9 (new formula) Homebrew/homebrew-core#254211
fix software encoder tests (XDG portal should not be primary capture method... or environment is missing something)
- AppImage (fail)
- FreeBSD (fail and hang)
update cmake build args to explicitly include -DSUNSHINE_ENABLE_PORTAL throughout
reduce/eliminate sonar warnings

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

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 · 2025-11-12T22:27:52Z

Bundle Report

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

Detailed changes

Bundle name	Size	Change
sunshine-esm	770.8kB	90 bytes (0.01%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sunshine-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`assets/config-*.js`	90 bytes	67.18kB	0.13%

Files in assets/config-*.js:

./src_assets/common/assets/web/configs/tabs/Advanced.vue → Total Size: 9.24kB

codecov · 2025-11-12T22:57:16Z

Codecov Report

❌ Patch coverage is 5.44323% with 608 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (master@2a31583). Learn more about missing BASE report.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/platform/linux/portalgrab.cpp	4.50%	442 Missing and 152 partials ⚠️
src/platform/linux/misc.cpp	38.88%	8 Missing and 3 partials ⚠️
src/platform/linux/kmsgrab.cpp	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master    #4417   +/-   ##
=========================================
  Coverage          ?   15.11%           
=========================================
  Files             ?       95           
  Lines             ?    19874           
  Branches          ?     9178           
=========================================
  Hits              ?     3004           
  Misses            ?    13329           
  Partials          ?     3541

Flag	Coverage Δ
Archlinux	`11.20% <2.92%> (?)`
FreeBSD-14.3-amd64	`13.23% <4.16%> (?)`
Homebrew-ubuntu-22.04	`13.43% <3.13%> (?)`
Linux-AppImage	`11.60% <4.45%> (?)`
Windows-AMD64	`13.49% <ø> (?)`

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

Files with missing lines	Coverage Δ
src/platform/linux/kmsgrab.cpp	`3.83% <0.00%> (ø)`
src/platform/linux/misc.cpp	`15.50% <38.88%> (ø)`
src/platform/linux/portalgrab.cpp	`4.50% <4.50%> (ø)`

src/platform/linux/portalgrab.cpp

psyke83 · 2026-01-22T15:18:56Z

The current implementation in this PR doesn't perform as well as KMS capture on my system (RX 6600, Ubuntu 25.10 with Mesa PPA enabled), but this should not be a reason not to add support.

It might work better on more powerful systems, and there is still room for improvement (example: the frame pacing code has not been changed to align with @gschintgen's improved pacing on KMS/X11). Also, the KDE/KWin developers have already stated that kmsgrab should be deprecated in favour of xdg portal.

XT-Martinez · 2026-01-28T14:33:48Z

Hi Everyone,

I've been testing the early flatpak builds of this PR and got it to work with Gnome and Bazzite.
However, I noticed that monitoring scaling is not handled properly, leading to cropped image capture.

Here's a screenshot

Works fine on KMS

XT-Martinez · 2026-01-28T14:39:35Z

Touch and Pen passthrough (inputs that are relative to the display) are not working as well

nicman23 · 2026-01-29T10:32:30Z

hello, how do you make use of it? is there a toggle or a env var to switch to xdg portals from kmsgrab?

XT-Martinez · 2026-01-29T11:22:43Z

hello, how do you make use of it? is there a toggle or a env var to switch to xdg portals from kmsgrab?

It is configurable in the web UI.

This is not present in the glad version imported in Sunshine, plug the holes so that these functions may be used.

Add a new portal "grab" implementation that will request the necessary permissions over XDG portals and use Pipewire for video data streaming. This supports DMA-Buf buffer exchange for hardware accelerated encoding (VAAPI, nvenc), software encoding will only work with memory buffers.

Require GIO and PIPEWIRE packages for portal support and use SYSTEM include directories. Also, clarify the fatal error message order for missing dependencies.

Pipewire has been added to the dependency lists for FreeBSD, Arch, Fedora, Homebrew, and Debian-based packaging and build scripts. This ensures proper support and integration for systems using Pipewire.

A value of 2 indicates "Remember this Selection". Co-authored-by: Carson Katri <[email protected]>

…ystems (#4510) Co-authored-by: Carlos Garnacho <[email protected]> Co-authored-by: Carson Katri <[email protected]> Co-authored-by: d.bondarev <[email protected]>

Corrects the installation path for sunshine-kms to use %{buildroot}%{_bindir} instead of %{_bindir}, ensuring proper packaging for RPM builds.

Replaced raw arrays with std::array for type safety and clarity in buffer and struct allocations throughout portalgrab.cpp. Updated related code to use .data() and .size() where appropriate, improving maintainability and reducing potential for errors.

Changed C-style string constants to array declarations for REQUEST_PREFIX and SESSION_PREFIX. Updated function calls to use std::array::data() for params. Split spa_pod_frame variable declarations for clarity.

Updated path string construction in portalgrab.cpp to use std::format instead of g_strdup_printf, improving type safety and readability.

Applied minor refactoring for improved code clarity and consistency: added [[maybe_unused]] to unused parameters, replaced C-style casts with static_cast, removed unnecessary semicolon, and simplified std::fill_n usage.

Refactored parameter assignment to avoid post-increment in array indexing and improve clarity. Updated token check to use direct character comparison. Replaced enum class usage with 'using enum' for mem_type_e. Improved logging for unrecognized capture status by using std::to_underlying.

Updated function parameters and local variables to use const qualifiers where appropriate. Replaced C-style casts with C++ static_cast for improved type safety and clarity. Minor code cleanups and style improvements.

Added the -DSUNSHINE_ENABLE_PORTAL=ON flag to FreeBSD CI, COPR spec, Flatpak, and linux_build.sh scripts to ensure the portal feature is enabled across all build targets. Also reordered some CMake flags for consistency.

…nts (#4619)

…4622)

Reformats the mark_as_advanced call in FindSystemd.cmake to list each variable on a separate line, improving readability and maintainability.

…land users (#4635)

sonarqubecloud · 2026-01-30T17:54:25Z

Quality Gate failed

Failed conditions
9 New issues
9 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

ReenigneArcher force-pushed the feat/linux/add-xdg-portal-grab branch from f7173e3 to d65baf5 Compare November 15, 2025 03:28

carson-katri reviewed Dec 5, 2025

View reviewed changes

src/platform/linux/portalgrab.cpp Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view