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>
71 lines
3.7 KiB
Markdown
71 lines
3.7 KiB
Markdown
---
|
|
title: Requirements
|
|
description: 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](/docs/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](/docs/ubuntu-gnome) |
|
|
| **Ubuntu** (Desktop or Server) | KDE Plasma (KWin) | [Ubuntu — KDE](/docs/ubuntu-kde) |
|
|
| **Fedora** | KDE Plasma (KWin) | [Fedora — KDE](/docs/fedora-kde) |
|
|
| **Bazzite** | gamescope (Steam) | [Bazzite](/docs/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](/docs/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=1`** must be enabled (Wayland on NVIDIA needs it). The setup guides cover this.
|
|
- **AMD / Intel GPUs** encode via **VAAPI** instead (install `mesa-va-drivers` or
|
|
`intel-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](/docs/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](/docs/configuration)).
|
|
|
|
## A client
|
|
|
|
You also need something to stream *to* — see [Connect a Client](/docs/clients). 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.
|