enricobuehler
12843fe253
Adds a client-selectable **preferred codec** and wires the core + ABI + probe + Linux client to
negotiate and decode it. (Windows/Apple/Android follow in 2b.)
**Core:**
- `Hello.preferred_codec` (a single CODEC_* bit, 0 = auto) — a soft hint appended after
`video_codecs`. `resolve_codec(client, host, preferred)` now honors the preference when the host
can also emit it, else falls back to precedence (HEVC > AV1 > H.264). Roundtrip + preference tests.
- `NativeClient::connect` takes `video_codecs` + `preferred_codec`; `NativeClient.codec` exposes the
resolved `Welcome.codec`.
- ABI: `punktfunk_connect_ex7` (adds the two codec params; `ex6` delegates to it advertising
HEVC-only) + `punktfunk_connection_codec` getter + `PUNKTFUNK_CODEC_{H264,HEVC,AV1}` constants
(drift-guarded against the wire values). Header regenerated.
**Host:** passes `hello.preferred_codec` into `resolve_codec`.
**probe:** `--codec h264|hevc|av1|auto` sets the preference (still advertises it can decode all
three); the dump extension already follows the resolved codec.
**Linux client:** advertises the codecs FFmpeg can actually decode (`decodable_codecs()`), threads
the user's `codec` setting as the preference, and builds the decoder — both the software and VAAPI
paths, plus the mid-session VAAPI→software demotion — from the negotiated `Welcome.codec` instead of
hardcoding HEVC. New "Video codec" dropdown in Preferences (Automatic/HEVC/H.264/AV1).
Live-validated on the dev box: probe `--codec hevc` against a software (H.264-only) host resolves to
H.264 (graceful soft-preference fallback), no failure. clippy + core (57) + host (133) tests green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.7 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 VAAPI (a native Windows host is also available — see below). These are the Linux desktop environments it supports today, each with its own guide:
| Setup | Desktop / compositor | Guide |
|---|---|---|
| Ubuntu (Desktop or Server) | GNOME (Mutter) | Ubuntu — GNOME |
| Ubuntu (Desktop or Server) | KDE Plasma (KWin) | Ubuntu — KDE |
| Fedora | KDE Plasma (KWin) | Fedora — KDE |
| Bazzite | gamescope (Steam) | Bazzite |
Other wlroots compositors (Sway/Hyprland) also work but aren't a primary target. If your desktop isn't listed, the host still needs one of these compositor backends to create a virtual display.
Windows host: punktfunk also runs as a native host on Windows 10/11 (x64) — a signed installer that registers a service and bundles a virtual-display driver. 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 setup guide installs the right package (e.g.libnvidia-gl-<version>on Ubuntu). nvidia-drm modeset=1must be enabled (Wayland on NVIDIA needs it). The setup guides cover this.- AMD / Intel GPUs encode via VAAPI instead (install
mesa-va-driversorintel-media-driver; validated live on AMD RDNA3). The NVIDIA-specific notes above don't apply there. 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.
Desktop session
The host attaches to a Wayland desktop session and creates virtual displays in it, so a session needs to be running for the user the host runs as. This can be:
- a normal logged-in desktop (you're sitting at the machine, or it auto-logs-in), or
- a headless session that comes up at boot with no monitor or login — see Running as a Service.
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) — older versions deadlock during capture.
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.
- 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.