Files

T

enricobuehler 12843fe253 feat(protocol,clients): codec preference negotiation + Linux client decodes per Welcome (Phase 2a)

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>

2026-07-02 00:13:26 +00:00

6.7 KiB

Raw Blame History

Packaging punktfunk for Fedora / Bazzite

The punktfunk host links system FFmpeg (NVENC on NVIDIA, VAAPI on AMD/Intel, with a GPU-less software-H.264 fallback), PipeWire and Opus. This page covers packaging it for the Fedora Atomic / Bazzite world (rpm-ostree + bootc), where most of those deps are already present; the NVIDIA-specific notes below apply to the NVENC path.

👉 Ubuntu/Debian hosts install via apt from Gitea's package registry — see debian/README.md (apt update && apt upgrade for new builds).

👉 End-to-end Bazzite setup walkthrough (install → udev/group → host.env → service → firewall → verify → troubleshooting): bazzite/README.md. This file is the higher-level packaging rationale.

packaging/
  rpm/punktfunk.spec      # the RPM (builds punktfunk-host from source with cargo)
  bazzite/host.env        # gamescope-default config for a Bazzite appliance
  bazzite/README.md       # step-by-step Bazzite setup guide
  bootc/Containerfile     # bake punktfunk into a Bazzite-based atomic image
  copr/                   # COPR build-from-SCM settings

The other packaging targets have their own READMEs: debian/ (apt), arch/ (PKGBUILD + sysext), flatpak/ (the client), windows/ (host installer + drivers), plus kde/ and linux/ helpers.

What's needed beyond base Fedora

Dependency	Where it comes from
`ffmpeg-libs` with NVENC	RPM Fusion nonfree (`ffmpeg`, not `ffmpeg-free`)
NVIDIA driver (`libnvidia-encode`, `libEGL_nvidia`)	Bazzite -nvidia images ship it; plain Fedora: `akmod-nvidia` + `xorg-x11-drv-nvidia-cuda`
gamescope, PipeWire, wireplumber	Bazzite ships these; plain Fedora: `dnf install gamescope pipewire wireplumber`
`opus`, `libei`	Fedora base / updates

On Bazzite the only genuinely new runtime bits are ffmpeg-libs (RPM Fusion) + opus + libei — the rest of the stack is already there. The default backend is gamescope (packaging/bazzite/host.env), which the host spawns headless per session — no desktop login.

Option A — Gitea RPM registry (recommended; per-host, `rpm-ostree`)

The host's RPM is published to unom's self-hosted Gitea RPM registry (CI builds it on every push), mirroring the Debian/apt setup. Add one repo file, install, and track updates with rpm-ostree upgrade — no COPR account needed. Full guide: rpm/README.md.

# GPG-signed pkgs + Gitea-signed metadata → gpgcheck=1, repo_gpgcheck=1 (see rpm/README.md)
sudo tee /etc/yum.repos.d/punktfunk.repo >/dev/null <<'REPO'
[gitea-unom-bazzite]
name=punktfunk (unom, Bazzite)
baseurl=https://git.unom.io/api/packages/unom/rpm/bazzite
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://git.unom.io/api/packages/unom/rpm/repository.key
       https://git.unom.io/api/packages/unom/generic/punktfunk-keys/1/RPM-GPG-KEY-punktfunk
REPO
rpm-ostree install punktfunk && systemctl reboot
# updates:  rpm-ostree upgrade && systemctl reboot

Option B — COPR (per-host, `rpm-ostree install`)

Create a COPR project, enable build-from-SCM pointing at this repo, spec path packaging/rpm/punktfunk.spec (see copr/README.md). Under External Repositories add RPM Fusion nonfree so ffmpeg-devel resolves at build time.

On the Bazzite host:

# RPM Fusion (for the NVENC ffmpeg) — usually already enabled on Bazzite
rpm-ostree install \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
# enable the COPR + install punktfunk
sudo wget -O /etc/yum.repos.d/_copr_punktfunk.repo \
  https://copr.fedorainfracloud.org/coprs/enricobuehler/punktfunk/repo/fedora-$(rpm -E %fedora)/
rpm-ostree install punktfunk
systemctl reboot

Option C — bootc (image-based, atomic)

Layer punktfunk into a Bazzite image once, then rebase any number of hosts onto it — no per-host drift. See bootc/Containerfile:

podman build -t ghcr.io/<you>/bazzite-punktfunk -f packaging/bootc/Containerfile .
podman push  ghcr.io/<you>/bazzite-punktfunk
# on the target:
sudo bootc switch ghcr.io/<you>/bazzite-punktfunk && systemctl reboot

First-run setup (either option)

ujust add-user-to-input-group           # virtual gamepads need /dev/uinput (then re-login).
                                        # On Bazzite use ujust, NOT `usermod -aG input` (atomic OS — it won't stick).
mkdir -p ~/.config/punktfunk
cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env   # edit (gamescope app, etc.)
systemctl --user enable --now punktfunk-host

# Management web console (pairing + status) — pulled in by default (the host RPM Recommends it;
# `--no-install-recommends` / headless-only boxes can skip it). Enable it and read the login password:
systemctl --user enable --now punktfunk-web
journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'   # then open https://<host-ip>:3000

Pair a stock Moonlight client (mDNS-discovered), or connect the native punktfunk/1 client — via the web console at https://<host-ip>:3000 or directly.

⚠️ COPR caveat: COPR's mock chroot has no bun, so a COPR build produces only punktfunk + punktfunk-client — not punktfunk-web. For the console on a COPR/bootc host, install from the Gitea RPM registry (Option A — it carries punktfunk-web), which is also why bootc/Containerfile installs from there rather than COPR.

Why not Flatpak (for the HOST)?

The host needs unsandboxed access the zero-copy NVENC path, /dev/uinput, the PipeWire graph and the compositor's privileged protocols — a Flatpak sandbox fights all of these. An RPM (or the bootc layer) installs into the host system where those just work.

👉 The client is a different story — it IS shipped as a Flatpak (the only viable Steam Deck install path: SteamOS /usr is read-only and lacks libadwaita/libSDL3). See flatpak/README.md. The client sandbox only needs the GPU render node, Wayland, PipeWire audio, the network and hidraw — all expressible as finish-args.

Building the SRPM/RPM locally (Fedora only)

git archive --format=tar.gz --prefix=punktfunk-0.3.0/ -o ~/rpmbuild/SOURCES/punktfunk-0.3.0.tar.gz HEAD
rpmbuild -ba packaging/rpm/punktfunk.spec     # needs the BuildRequires from the spec
# (0.3.0 = the spec's default %{pf_version}; the prefix and tarball name must match it)

(Not buildable on Debian/Ubuntu — use a Fedora toolbox/container or COPR.)

6.7 KiB Raw Blame History