feat(capture/linux): add KWin direct screencast capture method by Kishi85 · Pull Request #5009 · LizardByte/Sunshine

Kishi85 · 2026-04-16T20:27:25Z

Description

This adapts the changes from #4724 to the changes from #5008. See the linked PR for details on the feature.

ToDo-List:

Screenshot

Issues Fixed or Closed

Closes feat(capture/linux): add KWin direct screencast capture method #4724

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

neatnoise · 2026-04-17T12:49:02Z

Tested on KDE Plasma 6.6.4, RX 9070 XT, Mesa 26.2 dev, CachyOS with Vulkan CBR encoding. Works great once you get past the setup — I had to set KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 for KWin (via
~/.config/environment.d/kwin.conf) and restart the session, otherwise the protocol doesn't show up in the registry even though the screencast plugin is loaded.

Once running, streaming is smooth. At one point Moonlight picked the external IP instead of the local one (sometimes It does), so the stream was going out through the internet and back without me even noticing — only realized when I turned on the debug overlay and saw higher the Internet network latency.

Kishi85 · 2026-04-17T15:55:10Z

void-linux/void-packages#31274 (comment)

Has had the permission issue before on xdg-portal-kde and fixed it by adding X-KDE-Wayland-Interfaces=zkde_screencast_unstable_v1 to the associated desktop file. So maybe we could do something similar here and have a clean way to run this without any hacks or environment variables necessary.

Kishi85 · 2026-04-17T16:40:55Z

Adding a dummy desktop file like this as ~/.local/share/applications/app-dev.lizardbyte.app.Sunshine-kwin-screencast-helper.desktop or /usr/share/applications/app-dev.lizardbyte.app.Sunshine-kwin-screencast-helper.desktop fixes the permission issue but needs the absolute path to the real binary in it for kwin to be able to properly assign the permission:

[Desktop Entry]
Comment=Sunshine kwin screencast permission helper
Name=app-dev.lizardbyte.app.Sunshine-kwin-screencast-helper
NoDisplay=true
Type=Application
X-KDE-Wayland-Interfaces=zkde_screencast_unstable_v1
Exec=/home/user/git/sunshine/cmake-build-debug/sunshine-0.0.0-b1dbab76

I'll have to test if we have to package and properly distribute the .desktop file or if it is sufficient to create it on-the-fly upon kwingrab init (in ~/.local/share/applications/app-dev.lizardbyte.app.Sunshine-kwin-screencast-helper.desktop before accessing zkde_screencast_unstable_v1). The latter would be preferable, we could also just remove the desktop file upon destruction to have a clean state.

Kishi85 · 2026-04-18T19:57:57Z

Running this with CAP_SYS_ADMIN breaks KWin's permission check (because it's not allowed to resolve the executable path for the PID with the capability). I'll have to check if the same workaround we do for portalgrab works here.

Kishi85 · 2026-04-22T08:27:06Z

Added necessary adaptions for #5041 ~~(also temporarily added the commit from #5041 to the list so this can be tested properly)~~.

~~Please do not merge before #5041 is merged.~~

This commit is taken from LizardByte#4724 with all pipewire duplication removed and changed to pipewire.cpp Co-authored-by: Ramalama2 <6314556+Ramalama2@users.noreply.github.com>

…wayland output index This is just a first shot at working multi-monitor support for basic testing.

…in XDG_DATA_HOME/applications

… index

Utilitzies kde_output_order_v1 wayland protocol

…s permission check KWin's Wayland permission check requires the wayland client processs pid's executable to be readable by KWin. While running with CAP_SYS_ADMIN this is not possible so KWin will fail the check.

This is necessary for running with CAP_SYS_ADMIN as the normal check for display_names being empty will not work as that will always return a dummy value to not drop capabilities early (before encoder probing).

…ermission Also extend the permission helper to check if system file exists

…ters

To be able to re-use existing wayland code

…s properly cleaned up on error

Added right after ENABLE_PORTAL (as it's very similar). FreeBSD and Flatpak should be tested more before enabling.

Kishi85 · 2026-04-23T10:03:12Z

@ReenigneArcher Do you think this should be enabled for FreeBSD and Flatpak as well (to be on-par with portalgrab)? Nothing should break, the worst case would be that kwingrab does not work (most likely due to missing permissions).

Unfortunately I can't test those 2 options by myself atm, hence I've left them out in eba45e6.

psyke83 · 2026-04-23T14:35:18Z

My thoughts:

XDG Desktop Portal is always guaranteed to work for a Flatpak since the XDG standard is mandated by the package format, and the Desktop Portal is specifically targeted for sandboxed apps. KDE also (uniquely) has a secondary permission system - plumbed through flatpak - that allows bypassing of manual portal setup. For that reason, kwingrab is technically not necessary unless there is a measurable performance difference in the screencast flow through pipewire between the methods. But on the other hand, kwingrab has the same security requirements as portal, and can work without issue as long as your .desktop file is installed, correct? I don't see the harm in enabling it, as long as we can verify it works as expected. Having it enabled for all possible Linux packaging formats would simplify documentation.

FreeBSD doesn't support Flatpak, and while I think they do support the XDG standard, Desktop Portal is not guaranteed to be present, and if it is, it's unclear how to leverage the permission bypass without a working flatpak command, so it seems that kwingrab makes sense for this environment.

sonarqubecloud · 2026-04-23T14:37:17Z

Quality Gate failed

Failed conditions
18 New issues
18 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

Kishi85 · 2026-04-23T14:59:25Z

My thoughts:

XDG Desktop Portal is always guaranteed to work for a Flatpak since the XDG standard is mandated by the package format, and the Desktop Portal is specifically targeted for sandboxed apps. KDE also (uniquely) has a secondary permission system - plumbed through flatpak - that allows bypassing of manual portal setup. For that reason, kwingrab is technically not necessary unless there is a measurable performance difference in the screencast flow through pipewire between the methods. But on the other hand, kwingrab has the same security requirements as portal, and can work without issue as long as your .desktop file is installed, correct? I don't see the harm in enabling it, as long as we can verify it works as expected. Having it enabled for all possible Linux packaging formats would simplify documentation.

FreeBSD doesn't support Flatpak, and while I think they do support the XDG standard, Desktop Portal is not guaranteed to be present, and if it is, it's unclear how to leverage the permission bypass without a working flatpak command, so it seems that kwingrab makes sense for this environment.

From my personal testing (over local ethernet) kwingrab feels subjectively snappier than portalgrab and objectively (from moonlight streaming stats) host processing latency is lower for kwingrab vs. portalgrab on mostly idle desktop. At least in my case min values go down to 1.5ms with kwingrab vs. >=2ms with portalgrab, with averages following by around the same amount of difference.
Since we're forced to use KDE-specific Wayland protocols for kwingrab via zkde_screencast_unstable_v1 already it's also using kde_output_order_v1 so kwingrab is able to follow Screen priorities set in Display Settings. Making the primary screen the one that the sunshine stream is started on and keyboard shortcut order by the same logic.
The secondary permission system for portalgrab via flatpak seems to be irrelevant for kwingrab as it's only checking the wayland interface permission via executable matching desktop file. AppImages work via the temporary permission helper but I'm unsure if the same is true for Flatpak (as that might not yield the correct desktop file for permission or need the security context implementation instead).
As for FreeBSD that's the interesting one. KWin screencasting does not require Desktop Portal only Pipewire so in theory it should just work with kwin_wayland on FreeBSD. I've no way to test this atm and I'm not sure the permission setup will work correctly for that case.

Kishi85 · 2026-04-23T17:04:10Z

Technical sidenote: Looking at /usr/share/applications/org.freedesktop.impl.portal.desktop.kde.desktop one can see that xdg-desktop-portal-kde is also using zkde_screencast_unstable_v1 (among a few other interfaces) to provide the XDG portal implementation for KDE:

[Desktop Entry]
Exec=/usr/lib/xdg-desktop-portal-kde
X-KDE-Wayland-Interfaces=org_kde_kwin_fake_input,org_kde_plasma_window_management,zkde_screencast_unstable_v1
X-KDE-DBUS-Restricted-Interfaces=org.kde.KWin.ScreenShot2
NoDisplay=true
Icon=kde

So we can assume that all pipewire stream features for portalgrab via xdg-desktop-portal-kde should also be directly available for kwingrab.

psyke83 · 2026-04-23T17:15:41Z

That's the issue with kwingrab; there's extra maintenance burden in directly utilizing the (unstable) Wayland extension that would be transparently handled by XDG Portal via the KDE helper.

Relevant PR that may impact us in future, if the "v1" protocol is obsoleted: https://invent.kde.org/plasma/kwin/-/merge_requests/9048
Edit: matching PR on Portal side: https://invent.kde.org/plasma/xdg-desktop-portal-kde/-/merge_requests/544

Kishi85 · 2026-04-23T17:27:31Z

That's the issue with kwingrab; there's extra maintenance burden in directly utilizing the (unstable) Wayland extension that would be transparently handled by XDG Portal via the KDE helper.

Relevant PR that may impact us in future, if the "v1" protocol is obsoleted: https://invent.kde.org/plasma/kwin/-/merge_requests/9048 Edit: matching PR on Portal side: https://invent.kde.org/plasma/xdg-desktop-portal-kde/-/merge_requests/544

We're not the only ones in that boat then (OBS for example also utilizes it) and if it breaks we still have a working fallback with portalgrab (which Sunshine will always need for anything non-KWin). Also we have enough time to prepare so thanks for mentioning the drafts early.

kwingrab is just a way to get a more direct stream for KWin-based systems with a few bonuses (like working screen priorities). The main streaming logic is already shared with portalgrab by utilizing pipewire_display_t so it's just the negotiation that might break until fixed (although I'm not seeing a huge difference for output streaming between v1 and v2 as it is right now. We should even be able to implement a fallback from v2 to v1 once the necessary definitions are in plasma-wayland-protocols).

Kishi85 force-pushed the kwin-direct-screencast branch 9 times, most recently from 2ce02db to b1dbab7 Compare April 17, 2026 12:08

Kishi85 changed the title ~~feat(capture/linux): add KWin direct screencast capture method~~ feat(capture/linux): add KWin direct screencast capture method - v2 Apr 17, 2026

ReenigneArcher changed the title ~~feat(capture/linux): add KWin direct screencast capture method - v2~~ feat(capture/linux): add KWin direct screencast capture method Apr 17, 2026

Kishi85 changed the title ~~feat(capture/linux): add KWin direct screencast capture method~~ feat(capture/linux): add KWin direct screencast capture method (v2) Apr 17, 2026

Kishi85 changed the title ~~feat(capture/linux): add KWin direct screencast capture method (v2)~~ feat(capture/linux): add KWin direct screencast capture method Apr 17, 2026

Kishi85 force-pushed the kwin-direct-screencast branch 13 times, most recently from 980f115 to 2e361c6 Compare April 18, 2026 19:14

Kishi85 marked this pull request as ready for review April 21, 2026 17:27

Kishi85 force-pushed the kwin-direct-screencast branch from 6453fa9 to 03163b3 Compare April 22, 2026 08:23

This comment was marked as off-topic.

Sign in to view

This was referenced Apr 22, 2026

fix: touch scaling bug and initialize display variables as 0 #4758

Merged

Sunshine Reads Incorrect Monitor Index #221

Open

Kishi85 and others added 15 commits April 23, 2026 07:06

feat(capture/linux): Add KWIN direct screencast capture method

80d317a

This commit is taken from LizardByte#4724 with all pipewire duplication removed and changed to pipewire.cpp Co-authored-by: Ramalama2 <6314556+Ramalama2@users.noreply.github.com>

feat(linux/kwingrab): Cleanup and add multi-monitor support based on …

369bf52

…wayland output index This is just a first shot at working multi-monitor support for basic testing.

fix(linux/kwin): Create/update desktop permission file automatically …

652dcd4

…in XDG_DATA_HOME/applications

fix(linux/kwin): Match output based on wl_output names not on display…

e331b81

… index

feat(linux/kwin): Order outputs by KDE's screen priority

966ef17

Utilitzies kde_output_order_v1 wayland protocol

fix(linux/kwin): Add missing advanced config UI option

13db09b

fix(linux/kwin): Fix verify_kwin in misc.cpp by using a separate check

1b11886

This is necessary for running with CAP_SYS_ADMIN as the normal check for display_names being empty will not work as that will always return a dummy value to not drop capabilities early (before encoder probing).

fix(linux/kwin): Install a system application desktop file for KWin p…

3a06894

…ermission Also extend the permission helper to check if system file exists

fix(linux/kwin): Cleanup and unify naming

03e233f

refactor(linux/kwin): Use a map with new struct for all output parame…

bb4b00f

…ters

refactor(linux/kwin): Move kwin_available check logic into screencast_t

df52795

To be able to re-use existing wayland code

fix(linux/kwin): Reduce wayland logging verbosity and ensure output i…

958414c

…s properly cleaned up on error

feat(linux/kwin): Enable kwingrab in Linux Build script / COPR spec

eba45e6

Added right after ENABLE_PORTAL (as it's very similar). FreeBSD and Flatpak should be tested more before enabling.

fix(linux/kwin): Adapt to multi-monitor absolute touchinput fixes

c8229da

docs(readme): Add KWin Screencast to the feature table

56f7160

Uh oh!

Conversation

Kishi85 commented Apr 16, 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!

neatnoise commented Apr 17, 2026

Uh oh!

Kishi85 commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kishi85 commented Apr 17, 2026

Uh oh!

Kishi85 commented Apr 18, 2026

Uh oh!

Kishi85 commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as off-topic.

This comment was marked as off-topic.

Kishi85 commented Apr 23, 2026

Uh oh!

psyke83 commented Apr 23, 2026

Uh oh!

sonarqubecloud Bot commented Apr 23, 2026

Quality Gate failed

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Kishi85 commented Apr 16, 2026 •

edited

Loading

Kishi85 commented Apr 17, 2026 •

edited

Loading

Kishi85 commented Apr 22, 2026 •

edited

Loading

Kishi85 commented Apr 23, 2026 •

edited

Loading

Kishi85 commented Apr 23, 2026 •

edited

Loading

psyke83 commented Apr 23, 2026 •

edited

Loading

Kishi85 commented Apr 23, 2026 •

edited

Loading