enricobuehler
346385bad8
`punktfunk-gamescope` had never been published to the apt registry — not in any release. It was built inside the host job's Ubuntu 24.04 image, where it cannot build: our pin vendors wlroots 0.19.3, which floors `wayland-server` at 1.23.1, and noble ships 1.22.0 (it also lacks libxcb-errors-dev and has only libdisplay-info 0.1.1). Every rung of that path was a `::warning::` returning 0 and the one hard gate ran last by design, so v0.26.0 and v0.27.0 both released with the package missing while docs-site told apt users to install it. The same tags shipped it fine for Arch, Fedora 44 and Bazzite. It now builds in its own job on Debian 13 (ci/gamescope-trixie.Dockerfile), the oldest apt base the tree configures on. One package serves Debian 13 AND Ubuntu 26.04 — measured by installing and running it on both — because the build also vendors libdisplay-info via the new `--extra-fallback` option: linked against the distro copy it demands `libdisplay-info2` on trixie, which Ubuntu 26.04 does not have (it carries libdisplay-info3). The option is opt-in, so the Arch/Fedora/nix outputs are byte-for-byte unchanged. Ubuntu 24.04 gets no gamescope package and cannot — its wayland is too old to run one however built. Debian 13 is now a documented host target. That needed no packaging change at all: the host .deb's glibc-2.39 floor and bundled FFmpeg already made it installable, and it had been working for a long time while docs-site said Debian was unsupported and unverified. Verified by installing: host, web console and plugin runner install, resolve every soname and run. The desktop client stays Ubuntu-26.04-only (built there, floors at `libc6 >= 2.43`; Debian 13 has 2.41). Compositor detection now answers Cinnamon (Mint, LMDE) with the route that works instead of advice that cannot help. Muffin forked from Mutter 3.36: `org.cinnamon.Muffin.ScreenCast` has only RecordMonitor/RecordWindow, never RecordVirtual, and xdg-desktop-portal-xapp implements no ScreenCast — so no value of PUNKTFUNK_COMPOSITOR makes a Cinnamon desktop host a virtual display. The error names headless gamescope, which needs no desktop compositor. The XDG sniff moved into a pure function so those branches are testable; Cinnamon is matched before GNOME, since it is a GNOME derivative and the generic arm would otherwise hand it the Mutter backend (caught by the new test). New `smoke-install` job installs every published package from the registry in pristine ubuntu:24.04, ubuntu:26.04 and debian:trixie images, asserts each binary resolves its libraries and runs, and insists the version served is the one this run built. Nothing in deb.yml had ever installed a package it produced, which is how both of the above survived unnoticed. ⚠ Bootstrap: seed `punktfunk-gamescope-trixie:latest` into the LAN registry once (docker.yml builds it thereafter) or the new job cannot start.
6.9 KiB
title, description
| title | description |
|---|---|
| Requirements | What you need to run a Punktfunk host — GPU, driver, desktop, and network. |
Supported setups
A Punktfunk host runs primarily on a Linux machine with a dedicated GPU — NVIDIA (NVENC) is the most-exercised path, and AMD/Intel GPUs work via Vulkan Video or VAAPI. A native Windows host is also available. Setup splits along two axes: you install the package per distro, then configure the host — and learn its quirks — per desktop/compositor.
New here? Read Security & Safe Use first — a streaming host is remote control of the machine, so keep it on a trusted LAN or VPN and require pairing.
Distros — install the package:
Desktops — configure and quirks:
Pick your distro to install, then your desktop to configure — the two are independent. The host needs one of these compositor backends to create a virtual display.
Support is deliberately non-uniform: each compositor and each GPU vendor gets its own capture, display and input backend, and they are not equally capable. The Support matrix has a row for every host desktop, GPU and client app, with each cell taken from the code that makes the decision — read it before assuming a feature is available on your combination.
Windows host: Punktfunk also runs as a native host on Windows 11 22H2 or newer (x64) — a signed installer that registers a service and bundles a virtual-display driver whose driver framework (IddCx 1.10) makes 22H2 the hard floor — Windows 10 is not supported. It encodes on NVIDIA (NVENC), AMD (AMF), or Intel (QSV), with a software fallback, and is newer than the Linux host; see Windows Host.
GPU and driver
- An NVIDIA GPU with NVENC — effectively any GeForce RTX or workstation card. NVENC is what encodes the video in hardware.
- NVIDIA driver 535 or newer (550+ recommended). The driver must include the GL/EGL userspace,
not just
nvidia-utils— without it the compositor can't initialise the GPU and capture fails. Each install guide installs the right package (e.g.libnvidia-gl-<version>on Ubuntu). nvidia-drm modeset=1must be enabled (Wayland on NVIDIA needs it). The install guides cover this.- AMD / Intel GPUs encode without any of the NVIDIA pieces above. For HEVC and AV1 the host
goes through Vulkan Video by default, so you want an up-to-date Mesa and the matching Vulkan
driver —
mesa-vulkan-driverson Ubuntu,vulkan-radeon/vulkan-intelon Arch. VAAPI (mesa-va-driversorintel-media-driver) is the H.264 path and the fallback for everything else: a machine with only the VAAPI driver still streams, it just gives up the Vulkan path's cleaner recovery from packet loss.PUNKTFUNK_VULKAN_ENCODE=0pins VAAPI. Validated live on AMD RDNA3. On modern Intel (Gen12/Tiger Lake and newer, including Arc) the VAAPI driver only offers the low-power (VDEnc) encode entrypoint — the host detects this and falls back automatically (PUNKTFUNK_VAAPI_LOW_POWER=1|0pins it) — and low-power encode needs the HuC firmware loaded (the kernel default on those platforms; checkdmesg | grep -i hucif encoding fails). A GPU-less software H.264 encoder also exists (PUNKTFUNK_ENCODER=software), meant as a fallback rather than a daily driver.
Consumer GeForce cards historically cap the number of concurrent NVENC sessions (a few at once); workstation cards don't. This only matters if you stream to many devices simultaneously.
HDR and 10-bit
HDR (10-bit BT.2020 PQ) is on by default, and what a Linux box needs for it is a gamescope
session running the patched punktfunk-gamescope build, or GNOME 50 or newer mirroring a real
HDR monitor on the GameStream plane — the ordinary KWin, Mutter and wlroots virtual displays are
8-bit upstream and stream SDR. HDR has the full chain, per host and per client, and how
to find the link that is missing.
Desktop session
The host attaches to a Wayland desktop session and creates virtual displays in it, so either a session is running for the user the host runs as, or the host brings one up itself. This can be:
- a normal logged-in desktop (you're sitting at the machine, or it auto-logs-in),
- a headless session that comes up at boot with no monitor or login — see Running as a Service, or
- no session at all — on the gamescope backend the host spawns its own headless gamescope
per client connect (on a Steam appliance it can bring up the whole Steam session), so nothing has
to be running beforehand. Auto-detection reads the live session, so on a box that boots to
nothing, set
PUNKTFUNK_COMPOSITOR=gamescopeinhost.env— with a gamescope session already running the host finds it by itself. See Steam / gamescope.
Minimum compositor versions (newer is fine):
- KWin ≥ 6.5.6 (KDE Plasma) — headless virtual outputs.
- GNOME ≥ 48 (Mutter) — virtual-monitor screen-cast.
- gamescope ≥ 3.16.22 (Bazzite/Steam) — below this, headless capture deadlocks against PipeWire ≥ 1.6.
- gamescope ≥ 3.16.23 for the Steam overlay (Shift+Tab / Quick Access Menu) to reach the stream at all — older builds never paint it into the node the host captures, so no host setting can bring it back.
For HDR on gamescope you additionally need the patched punktfunk-gamescope build — see
HDR and 10-bit above.
The same floors, with what each one gates, are in Version floors worth knowing; where the two disagree, the matrix is the one checked against the code.
Network
- Host and client on the same network — a LAN, or a VPN that puts them on one subnet. Punktfunk assumes a trusted local network; it's not built to be exposed to the public internet — don't port-forward it. To stream from outside your home, use a VPN so the remote client is on the same private subnet.
- For best results, a wired or fast Wi-Fi link. The host can run a built-in speed test to pick a bitrate for your link (see Configuration).
A client
You also need something to stream to — see Connect a Client. There are native Punktfunk clients for Apple (macOS, iOS, iPadOS, tvOS), Linux, Windows, and Android, and any Moonlight client works too. All of them can discover the host on your network automatically.