punktfunk/docs-site/content/docs/sway.md at worktree-gamestream-pad-heartbeat

Both wlr-family backends accepted the topology axis, the management API reported
it as the session's effective topology, and the backend logged a warning and did
nothing (sweep 13.18 shipped the warning, never the behaviour). Because
`resolve_topology` sends `auto` — the default — to `Exclusive` on any host without
a `PUNKTFUNK_COMPOSITOR` pin, and both compositors are auto-detected, the default
policy on every such box was an Exclusive that behaved as Extend. Closes #284.

`exclusive` now disables the operator's heads for the session and restores them
when the display GROUP's last member is torn down, via the same
`take_topology_restore` hand-off KWin uses — so the registry runs the restore
before the last output is reclaimed and the compositor never sees zero enabled
outputs, and a sibling session never has the desk re-enabled under it.

The disable filter is group-aware (design §6.1): enabled, not ours, and not
managed. On Hyprland `managed` is `PF-<pid>-<n>`, which covers a second host's
outputs too; on sway it is the `HEADLESS-` prefix, which also spares a headless
sway's own bootstrap output — the harmless failure, versus blacking out a live
sibling.

`primary` stays treated as extend, which is the honest answer rather than a gap:
Wayland has no primary-output concept and these compositors have only a focused
output, which the streamed head already holds since #283. It now says so
distinctly instead of sharing a warning with `exclusive`.

🛑 The Hyprland restore is `hyprctl reload`, and that is measured, not chosen.
Re-applying the head's own mode/position/scale — what design §5.2 and the issue
both assume — does NOT undo a disable: it answers `ok` and leaves `disabled:
true`. Probed 2026-08-18 against 0.56.2 (hyprlang) and 0.55.4 (Lua); every
targeted form was accepted and changed nothing, including `,enable` (answers
`invalid resolution`), `preferred,auto,1`, `monitorv2 disabled=false`, `keyword
unset monitor`, the Lua `disabled = false`, `dispatch dpms on` and
`forcerendererreload`. A runtime monitor rule is additive and the `disable` keeps
winning; only re-reading the config clears it. The headless output survives the
reload, so the issue's worry about losing it does not hold. Side effects are
documented at the call site and in the docs: other runtime `keyword` overrides are
dropped, and a hyprlang config re-runs its `exec =` lines. It runs only when a
session actually disabled something.

Disable is spelled per config era and confirmed by read-back, mirroring
`set_monitor_rule`: `keyword monitor <n>,disable` under hyprlang, `hl.monitor{
output = "<n>", disabled = true }` under Lua. Both eras reject the other's form at
exit 0, so the read-back — not the exit status, not the `ok` — is what decides.

Also fixes a marker gap that made one of those rejections read as success:
`hyprctl keyword` under the Lua config manager answers "keyword can't work with
non-legacy parsers. Use eval.", and `hyprctl_dispatch` matched "couldn't" but not
"can't". `set_monitor_rule` was covered by its own mode verification; nothing else
was.

⚠ The sway half is NOT exercised on a live sway — no box in the fleet runs one,
the same gap #283's `focus output` shipped with. The argv is sway's documented
surface, both shapes are pinned by tests (this file uses `output <name> <verb>`
AND `focus output <name>`, so getting one backwards is the live risk), and the
read-back turns a wrong guess into a warning naming the outputs rather than a
screen that silently stays dark.

Six new unit tests cover the group-aware filter on both backends, the headless
no-op case, both disable spellings and the marker set. 246 pass on Linux.

2026-08-18 17:49:45 +02:00

6.3 KiB

Raw Permalink Blame History

title, description

title	description
Sway / wlroots	Configure a Punktfunk host on sway.

Sway 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.

Despite the backend's name, this path is sway specifically. Everything it does for video — creating the headless output, setting its mode, listing your monitors — goes through sway's IPC (swaymsg), so a wlroots compositor without that IPC (River, dwl, …) cannot host: the session fails straight away with swaymsg get_outputs (is the host inside the sway session env — SWAYSOCK?). Input would be fine there — it uses the wlroots virtual pointer/keyboard protocols, which those compositors do have — but with no video there is no stream.

On Hyprland? It's a separate first-class backend (its own hyprctl IPC and xdph portal) — see Hyprland. This page is for sway.

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
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, and so does everything else on the video side (mode setting, monitor listing). (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.
Window placement — under the default extend topology the headless output sits beside your real monitors and nothing promotes it. sway opens a new window on the focused workspace, so the host runs swaymsg focus output HEADLESS-… — once when the output is ready, and again right before it launches anything from your library. Without that, games open on whichever physical monitor had focus and the stream shows a bare desktop.
Exclusive topology — if you set it, the host runs swaymsg output <name> disable for each of your physical outputs at session start and swaymsg output <name> enable when the last streaming display is torn down. Outputs named HEADLESS-* are never disabled, so a second streaming client (and a headless sway's own bootstrap output) is left alone.
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 sway session — its IPC socket (SWAYSOCK) is what the whole video path runs on. You don't have to export it: the host finds the live sway instance itself on every connect, so a systemd --user host works even though it never inherited your login shell's environment. 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.
ScreenCast routed to xdpw — only if another portal backend (gtk, gnome) is installed alongside it. xdg-desktop-portal picks one implementation per interface, and if it hands ScreenCast to the wrong backend the host steers an xdpw chooser nobody is reading. Pin it for your session by creating ~/.config/xdg-desktop-portal/sway-portals.conf:
```
[preferred]
default=gtk
org.freedesktop.impl.portal.ScreenCast=wlr
```
Then systemctl --user restart xdg-desktop-portal. On a box with only xdpw installed there is nothing to choose between, so you can skip this.

Troubleshooting: black client + "unsupported cursor mode requested"

A black client with pipeline build failed in the host log and dbus: unsupported cursor mode requested, cancelling from xdpw is one failure, not two.

xdpw refuses the ScreenCast metadata cursor mode and cancels the cast, and the portal spec makes that fatal rather than a fallback. Hosts before this release asked for it whenever the client drew the pointer itself (desktop mouse mode), so those sessions never produced a frame. Hosts from this release check what xdpw advertises first and use an embedded cursor instead, so the session streams.

On an older host, switch the client to game mouse mode — it stops asking for the metadata cursor and the stream comes up. The same failure on Hyprland reads unavailable cursor mode 4; see Hyprland.

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

This unit runs the secure native-only host. To also serve stock Moonlight clients, GameStream compat is opt-in (PUNKTFUNK_GAMESTREAM=1 in host.env, trusted LANs only) — see What the unit starts.

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.

6.3 KiB Raw Permalink Blame History