enricobuehlerandClaude Opus 5
d383161723
ci / rust (push) Failing after 2m31s
ci / docs-site (push) Successful in 1m22s
ci / web (push) Successful in 1m48s
docker / builders (--build-arg FEDORA_VERSION=44, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm, -f44) (push) Successful in 1m1s
ci / rust-arm64 (push) Successful in 2m2s
docker / builders (ci/android-ci.Dockerfile, punktfunk-android-ci) (push) Successful in 11s
docker / builders (ci/arch-ci.Dockerfile, punktfunk-arch-ci) (push) Successful in 9s
docker / builders (ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 9s
docker / builders (ci/rust-ci-noble.Dockerfile, punktfunk-rust-ci-noble) (push) Successful in 9s
docker / builders (ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 9s
docker / builders-arm64cross (push) Successful in 20s
docker / apps (., web/Dockerfile, punktfunk-web) (push) Canceled after 36s
docker / apps (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Canceled after 36s
docker / deploy-docs (push) Canceled after 0s
~1150 feat/fix commits landed since v0.19 and the docs drifted badly. This is a full sweep of every page against the code as shipped: ~280 verified corrections, nine new pages, and one deletion. The worst of what was wrong: the quickstart's five-minute path could not work (`serve` never started the web console, so step 3 had no PIN to read); every packaged Linux host runs `serve --gamestream` while security.md told readers to leave GameStream off; HDR was documented as Windows-only; `PUNKTFUNK_SECURE_DDA` was documented as a working knob that nothing reads; `PUNKTFUNK_INPUT_BACKEND` listed a `uinput` value that does not exist and named libei for KDE instead of kwin; README linked three pages deleted on 2026-07-05; and the rpm-ostree update command pointed at a script no package installs. Completeness: about half of what shipped since v0.19 had no page at all. New: support-matrix (what works where, from 217 verified capability cells), input (mouse/touch/pen — and the in-stream chords, so the docs finally say how to get your mouse back), client-settings, profiles-and-links, game-library, clipboard, wake-on-lan, hdr, uninstall. Updating existed but had zero inbound links. status.md is gone: its facts moved into the support matrix, its shell stays as a redirect so the public URL does not 404. roadmap.md is themes now, not a feature checklist — checkboxes are what rotted. Debian is no longer claimed. The .deb's Depends resolve against Ubuntu images, nothing in CI builds or tests Debian, and Debian 12 is below the glibc 2.39 floor. The `debian` in the repo URL is the package format. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
147 lines
7.2 KiB
Markdown
147 lines
7.2 KiB
Markdown
---
|
|
title: KDE Plasma (KWin)
|
|
description: Configure a Punktfunk host for KDE — host.env, quirks, and a headless KWin session.
|
|
---
|
|
|
|
Configure a Punktfunk host on **KDE Plasma**. The host uses KDE's KWin compositor to create a
|
|
per-client virtual display, captured zero-copy on the GPU (NVIDIA, AMD and Intel alike). This page
|
|
assumes the package is already installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora),
|
|
[Arch](/docs/arch), or the
|
|
[Bazzite](/docs/bazzite) appliance.
|
|
|
|
> New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
|
|
> the machine, so keep it on a trusted LAN or VPN and require pairing.
|
|
|
|
## host.env
|
|
|
|
The host auto-detects your KWin session on every connect — including a box that switches between
|
|
the Plasma desktop and Steam Game Mode — so the starter `~/.config/punktfunk/host.env` is one line:
|
|
|
|
```ini
|
|
# ~/.config/punktfunk/host.env (keys are case-sensitive)
|
|
PUNKTFUNK_VIDEO_SOURCE=virtual
|
|
# GPU zero-copy capture→encode (dmabuf → CUDA/NVENC on NVIDIA, dmabuf → Vulkan Video or VAAPI on
|
|
# AMD/Intel) is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
|
|
```
|
|
|
|
> **Don't set `PUNKTFUNK_COMPOSITOR`, `WAYLAND_DISPLAY`, or `XDG_CURRENT_DESKTOP` here.** Pinning
|
|
> the compositor turns auto-detection **off** — per connect *and* mid-stream — so a switch to Game
|
|
> Mode then kills the stream instead of being followed, and stale session values point the host at
|
|
> dead sockets. Forcing a backend is for CI and dedicated appliances (the
|
|
> [headless session](#headless-session) below ships a `host.env.kde` that pins on purpose).
|
|
|
|
If the box switches between the desktop and Game Mode, also enable lingering — the host is a user
|
|
service, and without linger the logout moment of a session switch tears it (and PipeWire) down
|
|
mid-stream:
|
|
|
|
```sh
|
|
sudo loginctl enable-linger "$USER"
|
|
```
|
|
|
|
See the [Configuration reference](/docs/configuration) for every option.
|
|
|
|
## Use a Wayland session
|
|
|
|
KDE must run on **Wayland**, not X11 — pick the Wayland session from the picker on the login screen.
|
|
The virtual-display path is Wayland-only and will not come up under X11.
|
|
|
|
On a normal Plasma login KWin drives your real hardware, and **any Plasma 6 release** can create the
|
|
virtual output — what it needs is the screencast grant below, not a particular version. The
|
|
[headless session](#headless-session) further down is the exception: it runs
|
|
`kwin_wayland --virtual`, and *that* backend only learned to create virtual outputs in
|
|
**KWin 6.5.6**, so an appliance box needs 6.5.6 or newer. Check with:
|
|
|
|
```sh
|
|
kwin_wayland --version
|
|
```
|
|
|
|
## Streaming the interactive desktop
|
|
|
|
To stream a logged-in Plasma desktop (rather than a headless session, below), KWin has to hand the
|
|
host its restricted screencast protocol. The host package ships an `io.unom.Punktfunk.Host.desktop`
|
|
file whose `X-KDE-Wayland-Interfaces` grants exactly that on a normal interactive session
|
|
(least-privilege, the same mechanism krfb/krdp use). After a **fresh install, log out and back into
|
|
the Desktop session once** so KWin re-reads the grant.
|
|
|
|
**Input needs no extra setup.** That same `.desktop` file also grants `org_kde_kwin_fake_input`, so
|
|
the host injects keyboard, mouse and touch straight into KWin — no portal, and no "Allow remote
|
|
control?" dialog for a headless box to answer, on every distro. All a fresh install needs is the log
|
|
out and back in above, so KWin re-reads the grant.
|
|
|
|
The old RemoteDesktop-portal grant only matters now if you force the libei input backend
|
|
(`PUNKTFUNK_INPUT_BACKEND=libei`) — that one injects through the RemoteDesktop portal, and on KDE it
|
|
is also what a portal capture (`PUNKTFUNK_VIDEO_SOURCE=portal`) is anchored to, so the capture
|
|
inherits the same grant. To seed it, Fedora and Bazzite ship a one-shot helper (run once as the
|
|
streaming user, no root); the `.deb` and Arch packages don't include that wrapper, so copy the
|
|
shipped `kde-authorized` file into the portal store by hand instead (the share dir is
|
|
`/usr/share/punktfunk-host` on Ubuntu, `/usr/share/punktfunk` on Arch) and log out and back
|
|
in:
|
|
|
|
```sh
|
|
bash /usr/share/punktfunk/bazzite/kde-desktop-setup.sh # Fedora / Bazzite
|
|
|
|
mkdir -p ~/.local/share/flatpak/db # Ubuntu / Arch
|
|
cp /usr/share/punktfunk*/headless/kde-authorized ~/.local/share/flatpak/db/kde-authorized
|
|
```
|
|
|
|
A login-less appliance skips all of this — its headless session (below) needs none of these grants.
|
|
|
|
## Start the host
|
|
|
|
With `host.env` in place, start the host from **inside your Plasma session**:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-host
|
|
journalctl --user -u punktfunk-host -f # watch it come up and print its identity fingerprint
|
|
```
|
|
|
|
This unit runs `serve --gamestream`, so it serves stock [Moonlight](/docs/moonlight) clients as well
|
|
as the native ones. For a native-only host, see
|
|
[What the unit starts](/docs/running-as-a-service#what-the-unit-starts).
|
|
|
|
A desktop-login host should also follow your session's lifetime, or restarting Plasma leaves the host
|
|
wired to a compositor that is gone — it keeps answering, and every session after that fails at
|
|
capture. Add the drop-in from
|
|
[Restart the host with your desktop](/docs/running-as-a-service#restart-the-host-with-your-desktop).
|
|
Skip it on the headless appliance route below.
|
|
|
|
Then bring up [The Web Console](/docs/web-console) to arm pairing and connect a
|
|
[client](/docs/clients). To start at boot — including fully headless — see the
|
|
[headless session](#headless-session) below or [Running as a Service](/docs/running-as-a-service).
|
|
|
|
## Persistent per-client scaling
|
|
|
|
KWin round-trips per-client display scale: it names each session's virtual output per client, so a
|
|
scale you set for one client (150 %, 125 %, …) is reapplied on that client's next connect. See
|
|
[Virtual displays](/docs/virtual-displays).
|
|
|
|
## Headless session
|
|
|
|
For a login-less appliance — a box that streams at boot with no graphical login — the host brings up a
|
|
**dedicated headless KWin session** rather than relying on an interactive one. It runs its own
|
|
`kwin --virtual` session (shipped as the `punktfunk-kde-session.service` unit) with permission checks
|
|
relaxed, so it needs none of the interactive grants above.
|
|
|
|
```sh
|
|
mkdir -p ~/.config/punktfunk
|
|
cp /usr/share/punktfunk/host.env.kde ~/.config/punktfunk/host.env # Ubuntu: /usr/share/punktfunk-host/host.env.kde
|
|
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now punktfunk-kde-session punktfunk-host
|
|
sudo loginctl enable-linger "$USER"
|
|
```
|
|
|
|
The session unit brings up headless KWin; the host unit follows it and starts listening. See
|
|
[Running as a Service](/docs/running-as-a-service) for the full headless setup.
|
|
|
|
## Troubleshooting
|
|
|
|
- **KWin isn't handing over the screencast protocol:** run `punktfunk-host probe-compositor` from
|
|
inside the session. It exits 0 only when KWin is up *and* advertising the grant to the host, and
|
|
prints the reason when it isn't — after a fresh install that is usually just the missing log out
|
|
and back in. On the headless appliance session, also check `kwin_wayland --version` is ≥ 6.5.6.
|
|
- **Black screen / no picture:** confirm you're on a Wayland session (not X11) and, on NVIDIA, that
|
|
the GL userspace is installed. More in [Troubleshooting](/docs/troubleshooting).
|
|
|
|
To bring the console up and pair, see [The Web Console](/docs/web-console).
|