enricobuehlerandClaude Fable 5
6617275387
Field triage (Nobara, Discord): the kde.md starter host.env told desktop users to set PUNKTFUNK_COMPOSITOR=kwin, which PINS the backend — detect() short-circuits and the capture-loss rebuild never re-detects — so a mid-stream switch to Game Mode killed the stream instead of following it. A follow-up hardcoded XDG_RUNTIME_DIR=/run/user/1000 anchor broke PipeWire for any non-1000 uid (pw audio connect: Creation failed). Revamp across every starter/example/reference: - Desktop starters (kde/gnome/hyprland/sway) shrink to PUNKTFUNK_VIDEO_SOURCE=virtual + an explicit warning that pinning disables session-following; forcing a backend is CI/appliance-only. - host.env.example: rewritten around auto-detection; anchors demoted to a commented ssh/cron-only block with the uid trap spelled out; the gamescope ATTACH/MANAGED knobs documented (previously missing); case-sensitivity called out. - packaging/bazzite/host.env + README: drop the uid-1000 anchors (a systemctl --user service inherits/derives them); README's stale PUNKTFUNK_COMPOSITOR=gamescope-era template synced to the real one. - packaging/kde/host.env: loud APPLIANCE-ONLY header (it pins on purpose). - configuration.md: session-anchors section inverted to "leave unset", compositor row states the pin consequence, case-sensitivity note. - troubleshooting.md: new "session fails right after editing host.env" section (case, wrong-uid anchors, stale pin, restart-to-apply). - gamescope.md/bazzite.md: attach/managed descriptions match current behavior (managed is the infra-detected default; attach re-modes a box-owned session to the client's resolution). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.2 KiB
title, description
| title | description |
|---|---|
| Sway / wlroots | Configure a punktfunk host on a wlroots compositor (Sway, River). |
Sway (and other wlroots-proper compositors like River) can host: the host adds a per-client headless
output at the client's exact mode with swaymsg create_output and captures it through the
xdg-desktop-portal-wlr (xdpw) ScreenCast portal, injecting input via the wlroots virtual
pointer/keyboard protocols.
On Hyprland? It's a separate first-class backend (its own
hyprctlIPC and xdph portal) — see Hyprland. This page is for sway and other wlroots-proper compositors.
This is not a primary target. It works and is validated live on sway 1.11 (zero-copy), but it sees far less testing than the KDE and GNOME paths — expect rougher edges. If you have a choice, KDE or GNOME are the better-exercised desktops.
This page assumes the package is already installed — see Arch, Ubuntu, or Fedora.
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.
host.env
The host auto-detects a wlroots session, so the starter ~/.config/punktfunk/host.env is one line:
PUNKTFUNK_VIDEO_SOURCE=virtual
# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
To force the backend (CI/testing — note that pinning turns live-session auto-detection off, so the host stops following session switches):
PUNKTFUNK_COMPOSITOR=wlroots # aliases: sway, wlr (the wlroots-proper family)
PUNKTFUNK_INPUT_BACKEND=wlr
See Configuration for the full reference.
How it works
- Video — the host adds a headless output at the client's exact mode with
swaymsg create_output. This uses Sway's IPC specifically; other wlroots-proper compositors (River, …) are best-effort on this path. (Hyprland is driven by its own backend, not this one.) - Capture — it captures that output through the xdg-desktop-portal-wlr (xdpw) ScreenCast portal. The host writes a managed chooser config so the output pick is automatic — no interactive picker dialog to answer.
- Input — mouse and keyboard are injected via the wlroots virtual pointer and virtual keyboard protocols.
For how long the virtual output lives, and extend-vs-exclusive topology, see Virtual displays.
Requirements
- A running wlroots-proper session (Sway, River, …). On Hyprland, use the Hyprland backend instead.
- xdg-desktop-portal-wlr (xdpw) installed and running — the host captures through its ScreenCast portal. Without it there is no video.
Start the host
With the backend selected, start the host from inside your Sway session:
systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f
Bring up the console and pair
Enable the web console, read its login password, and arm PIN pairing — see The Web Console. Then connect a client.