forked from unom/punktfunk
enricobuehlerandClaude Opus 5
eb4ab91627
PUNKTFUNK_MAX_FPS caps how fast the compositor lets the game render. It deliberately does NOT touch the session: the client still negotiates and receives its full rate, because the encode loop re-encodes the held frame whenever the compositor produced no new one, and a repeat of an unchanged picture is an almost-empty P-frame. So a 60-capped game on a 120 Hz session still puts 120 frames a second on the wire — and the GPU time the game gives up goes to capture and encode instead, which is the point (on a laptop or a handheld, it goes to heat and battery too). Capping the stream would be a different and mostly unwanted feature: it hands the client fewer frames than it asked for and saves the game's GPU nothing. gamescope is the compositor that has the lever, so it is the one that gets it: the rate becomes --nested-refresh, which is what gamescope clamps the game to. All three sessions we own take it — the bare spawn's -r, the managed gamescope-session-plus wrapper's PF_HZ, and the SteamOS PATH shim's. In the managed path the limit lands on PF_HZ alone and NOT on CUSTOM_REFRESH_RATES, so the mode the session advertises stays the client's — that is what makes games see the real refresh rather than the box's EDID. Two scoping notes. Under gamescope the cap is the nested output's rate, so everything it composites moves at it, not the game alone; there is only the one output. And the attach path (PUNKTFUNK_GAMESCOPE_NODE) mirrors a gamescope we do not own, so it has no lever to pull and is untouched. Closes #13 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
115 lines
8.3 KiB
Bash
115 lines
8.3 KiB
Bash
# punktfunk host configuration (~/.config/punktfunk/host.env) — consumed by punktfunk-host.service.
|
|
#
|
|
# YOU BARELY NEED THIS FILE. The host AUTO-DETECTS the live session per connect — which compositor
|
|
# is running (KWin / Mutter / sway / Hyprland / gamescope), its Wayland socket, session bus, and the
|
|
# matching input backend — and FOLLOWS the box when it switches between a desktop and Steam Gaming
|
|
# Mode, even mid-stream. Everything below except PUNKTFUNK_VIDEO_SOURCE is an optional override.
|
|
#
|
|
# Two rules that save debugging sessions:
|
|
# * Keys are CASE-SENSITIVE. `punktfunk_gamescope_attach=1` sets nothing — use the exact
|
|
# uppercase names.
|
|
# * On a desktop you actually use, do NOT set PUNKTFUNK_COMPOSITOR / WAYLAND_DISPLAY /
|
|
# XDG_CURRENT_DESKTOP. Pinning the compositor DISABLES session-following (a switch to Game
|
|
# Mode mid-stream then kills the stream instead of being followed), and stale session vars
|
|
# point detection at dead sockets. Those knobs are for CI and dedicated appliances (below).
|
|
|
|
# Video source: `virtual` creates a per-client virtual output at the client's exact
|
|
# resolution+refresh (the flagship mode); `portal` captures an existing monitor.
|
|
PUNKTFUNK_VIDEO_SOURCE=virtual
|
|
|
|
# GPU zero-copy capture (dmabuf → CUDA → NVENC / VAAPI / Vulkan) is ON by default and falls back to
|
|
# CPU automatically. No need to set it. Set to 0 only to force the CPU path.
|
|
# PUNKTFUNK_ZEROCOPY=0
|
|
|
|
# The name this host shows up under in Moonlight and the Punktfunk clients. Defaults to the
|
|
# machine's hostname; set it to give the box a friendly name without renaming the machine.
|
|
#PUNKTFUNK_HOST_NAME=Living Room
|
|
|
|
# --- Session anchors (rarely needed) -------------------------------------------------------
|
|
# As a `systemctl --user` service the host inherits the correct XDG_RUNTIME_DIR from systemd and
|
|
# derives the bus (`unix:path=$XDG_RUNTIME_DIR/bus`) itself. Set these ONLY when running the host
|
|
# outside a user service (ssh, cron) — and with YOUR uid (`id -u`), never a copy-pasted 1000: a
|
|
# wrong uid points the host at another user's (nonexistent) PipeWire/D-Bus, and every session
|
|
# fails with errors like "pw audio connect … Creation failed".
|
|
#XDG_RUNTIME_DIR=/run/user/<uid>
|
|
#DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<uid>/bus
|
|
|
|
# --- Steam Gaming Mode (Linux boxes with gamescope session infra: Bazzite/SteamOS/Nobara) ---
|
|
# Game Mode is auto-handled; two models decide WHERE it runs when a client streams:
|
|
# * MANAGED (the default where session infra is detected) — the host relaunches the gaming
|
|
# session HEADLESS at the CLIENT's exact mode ("game mode on the virtual screen"); physical
|
|
# displays drop out of it, and the box is restored on a debounced idle after disconnect.
|
|
# * ATTACH — the BOX owns its session: Game Mode stays on the physical screen and the host
|
|
# captures/follows it, never tearing it down. Reconnects land wherever the box is.
|
|
#PUNKTFUNK_GAMESCOPE_ATTACH=1 # pick the ATTACH model
|
|
#PUNKTFUNK_GAMESCOPE_MANAGED=1 # force MANAGED even where infra detection wouldn't pick it
|
|
#PUNKTFUNK_GAMESCOPE_SESSION=steam # host owns a gamescope-session-plus session at the client mode
|
|
#PUNKTFUNK_GAMESCOPE_NODE=auto # raw attach: discover + capture a running gamescope's node
|
|
# # (do NOT combine with SESSION)
|
|
#PUNKTFUNK_GAMESCOPE_APP=vkcube # nested command for ad-hoc bare-gamescope sessions
|
|
#PUNKTFUNK_SESSION_WATCH=0 # disable mid-stream Desktop<->Game following (on by default
|
|
# # on gamescope-infra boxes)
|
|
|
|
# --- Force a backend (CI / tests / dedicated single-session appliances ONLY) ---------------
|
|
# PINS the backend: the host stops following the live session entirely — per connect AND
|
|
# mid-stream. Fine for a dedicated headless appliance (punktfunk-kde-session.service, a pure
|
|
# gamescope box) or a CI run; wrong for any box that switches sessions.
|
|
#PUNKTFUNK_COMPOSITOR=kwin # kwin | mutter | gamescope | wlroots | hyprland
|
|
#PUNKTFUNK_INPUT_BACKEND=libei # wlr | libei | gamescope | uinput (auto-routed per connect)
|
|
#WAYLAND_DISPLAY=wayland-kde # headless-KDE appliance socket; retargeted per connect otherwise
|
|
#XDG_CURRENT_DESKTOP=KDE
|
|
|
|
# Optional overrides (apps.json is the primary mechanism for per-app settings):
|
|
#PUNKTFUNK_FEC_PCT=20 # video FEC overhead percent
|
|
#PUNKTFUNK_PERF=1 # per-stage timing logs
|
|
#PUNKTFUNK_MDNS=0 # disable the mDNS adverts (native + GameStream) — for multicast-
|
|
# dead networks/containers; clients add the host by address instead
|
|
# Display-management policy (keep-alive · topology · conflict · identity · layout · max) is set in the
|
|
# web console (Host → Virtual displays) → ~/.config/punktfunk/display-settings.json, NOT here; a
|
|
# settings file supersedes the legacy PUNKTFUNK_MONITOR_LINGER_MS / _NO_ISOLATE / *_VIRTUAL_PRIMARY
|
|
# knobs. One transport knob has no console equivalent:
|
|
#PUNKTFUNK_IDLE_TIMEOUT_MS=8000 # disconnect-detection latency: how long before a DROPPED client is
|
|
# declared gone (a kept display then starts its linger, or frees).
|
|
# Lower (e.g. 3000) to reclaim kept displays sooner after an
|
|
# ungraceful drop; clamped ≥1s, keep-alive ping scales with it so a
|
|
# live session never false-disconnects. A deliberate quit is instant.
|
|
# Session recovery hook: fired (debounced, ≥60 s apart) when a client connects while NO graphical
|
|
# session is live for this uid — e.g. a compositor crash dropped the box to the GDM greeter, whose
|
|
# auto-login only runs once per boot, so the box would otherwise need a walk-up login or a reboot.
|
|
# Restarting the display manager re-runs auto-login and the client's retry lands in the recovered
|
|
# desktop. Runs detached via `sh -c` as the host's user, so it needs passwordless privilege for
|
|
# exactly this action (sudoers drop-in: `youruser ALL=(root) NOPASSWD: /usr/bin/systemctl restart
|
|
# gdm`, or a polkit rule + plain `systemctl restart display-manager`). Unset = disabled.
|
|
#PUNKTFUNK_RECOVER_SESSION_CMD=sudo -n systemctl restart gdm
|
|
|
|
# Full-chroma 4:4:4 (HEVC Range Extensions) — sharper text/desktop, no chroma loss. Honored only on
|
|
# the punktfunk/1 native path when the client advertises 4:4:4 AND the GPU supports it (probed; else
|
|
# the session stays 4:2:0). HEVC-only; independent of 10-bit. NVENC (NVIDIA) is the validated path;
|
|
# VAAPI/AMF/QSV decline (4:2:0). GameStream/Moonlight always stays 4:2:0.
|
|
#PUNKTFUNK_444=1
|
|
#PUNKTFUNK_10BIT=1 # HEVC Main10 / HDR (when the client advertises 10-bit)
|
|
|
|
# Frame limiter for the GAME — how fast the compositor lets it render. Unset (or 0) = no limit,
|
|
# the default. It does NOT cap the stream: the client still negotiates and receives its full rate,
|
|
# because the encode loop re-encodes the held frame when the compositor produced no new one (an
|
|
# almost-empty P-frame). So a 60-capped game on a 120 Hz session still sends 120 frames a second,
|
|
# and the GPU time the game gives up goes to capture and encode instead — and to heat and battery
|
|
# on a laptop or handheld.
|
|
# gamescope only, today: it takes this as --nested-refresh, the rate it clamps the game to. That is
|
|
# the nested output's rate, so everything gamescope composites moves at it. Other compositors have
|
|
# no equivalent lever and ignore it.
|
|
#PUNKTFUNK_MAX_FPS=60
|
|
|
|
# Run the virtual display at a MULTIPLE of the session's frame rate, without sending a single
|
|
# extra frame. A compositor paints on its own vblank, so a frame finished just after the capture
|
|
# sampled waits nearly a whole interval to be picked up — the jittery part of the latency budget.
|
|
# At 2 that worst case halves. Costs the compositor and GPU the extra composites, so it's opt-in;
|
|
# 1 (default) is off, 4 is the ceiling. If the backend won't give the multiplied rate it reports
|
|
# what it achieved and the stream paces to that, exactly as it would for any other refusal.
|
|
#PUNKTFUNK_VDISPLAY_HZ_MULT=2
|
|
#RUST_LOG=info
|
|
# Management API bearer token. The mgmt API is HTTPS + token-authenticated ALWAYS (even on
|
|
# loopback); if unset it is auto-generated + persisted to ~/.config/punktfunk/mgmt-token (which the
|
|
# bundled web console sources). Set here only to pin a specific token.
|
|
#PUNKTFUNK_MGMT_TOKEN=
|