unom/punktfunk
6
0
Fork 1
Code Issues 3 Pull Requests 3 Actions 6 Packages Projects Releases 45 Wiki Activity
Files
6ff62b087ca4ba585263fe7af3eb481e7a49a028
punktfunk/packaging/flatpak/README.md
T
enricobuehler 5c05246098 feat: M10 — FFmpeg is gone from the client 
cargo tree -p punktfunk-client-session finds no ffmpeg. The host still does,
which is the whole point: pf-encode keeps libavcodec unconditionally and no
host workflow, packaging script or licence file was touched.

Deleted: crates/pf-ffvk, video_vulkan.rs, video_vaapi.rs, video_libav.rs, the
libavcodec half of video_d3d11.rs, the av_log machinery, ffmpeg::codec::Id as
the decoder's vocabulary (the quic CODEC_* wire constants now serve, which is
why the evidence table was keyed on them), DecodedImage::VkFrame and ::Dmabuf,
the presenter's AVVkFrame lane, and the ffmpeg-fallback feature with
everything behind it. DrmFrameGuard collapses from an enum to a newtype, which
removes an unsafe impl Send. Roughly 25,000 lines.

Then the CI, packaging, licensing and docs work the plan's §6 lists: the
Windows workflows lose FFMPEG_DIR, PF_FFVK_VULKAN_INCLUDE and their PATH
prepend; the MSIX loses its DLL wildcard; the client .deb stops emitting libav
sonames on its own because depends come from dpkg-shlibdeps; arch, flatpak and
nix drop the dependency; and the README's "FFmpeg 7 or 8" contract narrows to
the host.

Three defects reached users' machines in the first cut, and none was in the
deletion itself.

All three desktop Settings UIs offer vulkan, vaapi and d3d11va as stored
decoder values, so those strings sit in shipped settings files today. Refusing
them by name — which is the correct rule for a stale pin — would have bricked
every upgraded client whose owner ever touched that dropdown. They now migrate
onto the native rung for the same hardware family, at decoder construction AND
at each dialog's lookup, because a legacy value that matches no preset
displays as "Automatic" and silently rewrites the user's preference on the
next save.

M9's evidence filter was deleted on the argument that with no libavcodec twin
below, barring an unproven rung removes hardware decode rather than moving
down one rung. That is true on Windows and false on Linux for Intel and every
unknown vendor id, where prefer_vulkan_first is false and the order is
native-vaapi → native-vk: a rung that has decoded nothing anywhere sitting
above one that is 250/250 on three drivers. Every Intel Linux desktop would
have moved from libavcodec VAAPI, shipping for years, onto pf-vaadec by
default — and a rung that constructs and then produces wrong pixels leaves
only by the error-streak demotion, which this codebase already documents as
not tripping on the B580's strobing. The filter is restored as a narrow, pure,
testable rule: an unproven rung yields to a proven one, and to nothing else.
Windows deliberately passes no rung below, because that vendor family is the
one with a measured wrong-pixel report against Vulkan decode, and trading no
evidence for evidence of corruption is the wrong direction.

And the notices still said FFmpeg was bundled. The root file is what both
desktop clients include_str! and what the MSIX ships, three lines under the
new card saying no FFmpeg is bundled; Apple's Acknowledgements said it too, on
iOS, tvOS and macOS. The generator now emits four per-client files scoped by
transitive closure — 0 FFmpeg mentions in each, verified — while the root file
keeps it for the host. That also ends the standing false attribution of
ffmpeg-next, GTK4, windows-rs and the NVENC SDK to an iPhone.

Windows has no reachable box, so it was compiled instead: a cross clippy at
-D warnings on x86_64 and aarch64-pc-windows-msvc with the C toolchain stubbed
so build scripts run without linking. That gate immediately caught an
include_str! path one directory too deep, which nothing else could have.

Gates: container clippy -D warnings, 160 tests, workspace check, both Windows
targets clean, client ffmpeg count 0 and host 2. The four decode crates are
untouched, so the hardware rungs' 250/250 stands.

⚠ Owed and unrun: no GPU has executed any of this milestone. M8's on-glass
software check, M7's D3D11 and VAAPI AV1 hardware legs, and M9's field bake
all still want hardware, and the bake window and criteria remain the user's.
2026-08-07 08:58:47 +02:00

220 lines
12 KiB
Markdown
Raw Blame History

# punktfunk client — Flatpak (Steam Deck / SteamOS, and any flatpak distro)
The native Linux **client** — the shell (crate `punktfunk-client-linux`, binary
`punktfunk-client`) plus the Vulkan session binary it execs for streaming (crate
`punktfunk-client-session`, binary `punktfunk-session`) — is
published two ways by CI (`.gitea/workflows/flatpak.yml`), on every push to `main` (a rolling
`<next-minor>-ciN.g<sha>` build, base derived from the latest stable tag by
`scripts/ci/pf-version.sh`) and on `v*` tags (a clean `X.Y.Z`):
1. **Hosted OSTree repo at `https://flatpak.unom.io`** (recommended) — a GPG-signed Flatpak
remote served by a static Caddy container on unom-1, so users **install once and then
`flatpak update`**. Shared unom-wide repo (remote name `unom`), reusable by other unom apps
under the same signing key. See "Install (recommended)" below.
2. **Single-file `.flatpak` bundle** in **Gitea's generic package registry** (`unom` org) — the
no-remote fallback the **Decky plugin** consumes (stable `latest/punktfunk-client.flatpak`
URL) and the offline/manual path. On tags it's also attached to the Gitea release.
> The **host** is NOT a flatpak (it needs unsandboxed `/dev/uinput` + zero-copy NVENC — see
> [`../README.md`](../README.md) "Why not Flatpak"). Only the **client** is sandbox-friendly.
## Why flatpak for the Steam Deck
SteamOS `/usr` is read-only and image-based, and the system is **missing `libadwaita` and
`libSDL3`** — so a bare `punktfunk-client` binary dropped into `~/.local/bin` won't run. Flatpak
is the Deck's native, update-survivable app path (the user already runs Moonlight and chiaki-ng
as flatpaks), and the bundle carries libadwaita (from `org.gnome.Platform//50`) + a bundled SDL3.
It carries no FFmpeg: since M10 the client decodes on the user's own GPU drivers (Vulkan Video,
VAAPI) with openh264 + rav1d as the CPU floor, so the runtime's `codecs-extra` extension — and the
encumbered-codec question it answered — no longer enter into it.
App id: **`io.unom.Punktfunk`** (matches the Apple bundle id family and the Decky plugin's
flatpak fallback).
## Install (recommended): the hosted repo
One command adds the signed `unom` remote and installs the client; it auto-adds Flathub for the
GNOME runtime, and `flatpak update` tracks new builds from then on:
```sh
flatpak install --user https://flatpak.unom.io/io.unom.Punktfunk.flatpakref
flatpak run io.unom.Punktfunk
```
Equivalent two-step (add the whole remote, then install by app id):
```sh
flatpak remote-add --user --if-not-exists unom https://flatpak.unom.io/unom.flatpakrepo
flatpak install --user unom io.unom.Punktfunk
```
Updates — the whole point of the hosted repo:
```sh
flatpak update # or: flatpak update io.unom.Punktfunk
```
## Install on the Deck via the bundle (no-remote fallback)
The generic registry is a plain HTTP file store, so just download the bundle and install it
per-user (no root, survives SteamOS updates). This is what the Decky plugin uses; the hosted
repo above is the better path for a human on the Deck:
```sh
# Pick a version: a tag like 1.2.3, or the newest main build's <next-minor>-ciN.gSHA.
VER=1.2.3
URL="https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/$VER/punktfunk-client-$VER.flatpak"
# Flathub must be enabled (it is on the Deck) so the GNOME runtime pulls in:
flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
curl -fL -o /tmp/punktfunk-client.flatpak "$URL"
flatpak install --user --bundle /tmp/punktfunk-client.flatpak
```
Run it:
```sh
flatpak run io.unom.Punktfunk # GUI host list (mDNS)
flatpak run io.unom.Punktfunk --connect HOST:PORT
```
The **Decky plugin** launches exactly this (`flatpak run io.unom.Punktfunk --connect …`) once
installed — see [`../../clients/decky/README.md`](../../clients/decky/README.md).
## Updating the bundle install
If you installed from the **bundle** (not the hosted repo), it has no remote to track, so updates
are "download the newer bundle and reinstall":
```sh
flatpak install --user --bundle /tmp/punktfunk-client.flatpak # same command, newer file
```
Installs from `https://flatpak.unom.io` instead just take `flatpak update` (see "Install
(recommended)" above).
## Build locally / the CI fallback
CI builds this in a **`--privileged`** Fedora container, because `flatpak-builder` runs
`bubblewrap`, which needs user namespaces the default Docker executor denies. **If the Gitea
runner can't grant `--privileged`** (the job fails at `flatpak-builder` with
*"Creating new namespace failed: Operation not permitted"*), build it out-of-band and upload
by hand. The easiest place is **on the Deck itself** (it can run `org.flatpak.Builder`
user-scope, no root):
```sh
# On the Deck (or any flatpak box), one-time:
flatpak install --user -y flathub org.flatpak.Builder
# build-flatpak.sh auto-detects org.flatpak.Builder, generates cargo-sources.json (or reuses an
# existing one — see below), builds, and exports dist/punktfunk-client-<version>.flatpak:
bash packaging/flatpak/build-flatpak.sh
# Upload to the generic registry (PAT with write:package):
curl -fsS --user "enricobuehler:$REGISTRY_TOKEN" \
--upload-file dist/punktfunk-client-*.flatpak \
"https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/0.0.1-manual/punktfunk-client.flatpak"
```
> `cargo-sources.json` generation needs `python3` + `aiohttp` + `tomlkit`, which the Deck lacks.
> Generate it on a dev box (`build-flatpak.sh` does it, or run the upstream
> `flatpak-cargo-generator.py Cargo.lock -o packaging/flatpak/cargo-sources.json`), rsync it next
> to the manifest, and `build-flatpak.sh` reuses it (it only regenerates when the file is absent
> or `FORCE_GEN=1`).
> The Mac build host **cannot** build a Linux flatpak (no flatpak-builder for macOS), and
> home-worker-2 has no flatpak and no passwordless sudo to install it — so the Deck or the
> privileged CI container are the only two viable build sites.
### aarch64
The manifest builds for aarch64 as well as x86_64. Two things are architecture-specific, and both
are now expressed properly rather than hardcoded:
* **`PKG_CONFIG_PATH`** contains the runtime's multiarch directory. flatpak-builder does *not*
shell-expand `env` values, so `${FLATPAK_ARCH}` would be taken literally — a `build-options.arch`
override supplies the aarch64 string instead, inheriting everything else.
* **The prebuilt Skia archive** is per-target and pinned by sha256. There are now two `type: file`
sources discriminated by `only-arches`, both landing on the same `dest-filename`, so
`SKIA_BINARIES_URL` stays one literal path. Upstream publishes the aarch64 archive under the
same skia commit hash and the same resolved-feature key (`pdf-textlayout-vulkan`), so on a
skia-safe bump update both URLs and both hashes together.
```sh
ARCH=aarch64 bash packaging/flatpak/build-flatpak.sh
# -> dist/punktfunk-client-<version>-aarch64.flatpak
```
`ARCH` defaults to this machine's, and the bundle name now carries the architecture so an x86_64
and an aarch64 build can coexist in `dist/`. This is **not** a cross-compile: flatpak-builder runs
the build in a sandbox for the target arch, so building aarch64 anywhere but an arm64 machine
needs qemu binfmt and is very slow. Not yet verified end to end — the manifest is correct by
construction and the Skia hash was checked against the published archive, but no aarch64 flatpak
has been built.
## Manifest
[`io.unom.Punktfunk.yml`](io.unom.Punktfunk.yml). Runtime `org.gnome.Platform//50`
(GTK 4.20 + libadwaita 1.8 ≥ the crate floors of v4_16 / v1_5), built on freedesktop-sdk 25.08,
with two build-time SDK extensions: `org.freedesktop.Sdk.Extension.rust-stable` (→ //25.08,
**rustc 1.96** — the GTK4 dep chain, e.g. pango-sys 0.22, needs ≥ 1.92, which the EOL GNOME-48 /
24.08 rust-stable at 1.89 could not provide) and `org.freedesktop.Sdk.Extension.llvm20` (libclang,
needed by bindgen in sdl3-sys / pyrowave-sys). **No libavcodec at any layer** — the client links no
FFmpeg since M10, so neither the SDK's stripped build nor the runtime's `codecs-extra` shadow of it
is involved; HEVC decodes on the GPU's own driver, and there is deliberately no software HEVC
rung (see the manifest header). A bundled
**SDL3 3.4.10** module (pinned to match `sdl3-sys 0.6.6+SDL-3.4.10`), and finish-args for Wayland +
`--device=all` (GPU/VAAPI render node + evdev + the hidraw char-devices SDL3 needs for DualSense)
+ `--socket=pulseaudio` (PipeWire-pulse: playback + mic) + `--share=network`. Alongside it:
`io.unom.Punktfunk.desktop`, `io.unom.Punktfunk.metainfo.xml`, `io.unom.Punktfunk.svg` (all
installed by the manifest). No `vulkan-headers` module: it existed for `pf-ffvk`'s bindgen over
FFmpeg's `hwcontext_vulkan.h`, and ash generates its own bindings and dlopens the loader.
`cargo-sources.json` (the offline crate cache) is a pure function of
`Cargo.lock`; CI regenerates it each build and it is **gitignored** — generate it on any box with
network + `python3`/`aiohttp`/`tomlkit` (`build-flatpak.sh` does this automatically) and, for a
build host that lacks those (the Deck), rsync the generated file in alongside the manifest.
**Offline Skia:** the session binary's Skia console UI (`pf-console-ui` → `skia-safe`) normally
downloads prebuilt `libskia` binaries at build time, which is dead in the offline sandbox — so the
manifest pins a `skia-binaries-….tar.gz` source and points the build at it with
`SKIA_BINARIES_URL: file://…`. When bumping the `skia-safe`/`skia-bindings` crate version, update
that pinned tarball (URL + sha256) to the matching `skia-binaries` release or the build breaks
offline.
## Hosting the repo (unom-1) + one-time setup
The OSTree repo flatpak-builder produces is GPG-signed in CI and rsynced to unom-1, where a tiny
static **Caddy container** (`server/compose.production.yml` + `server/Caddyfile`, port **3230**)
serves the `./site` tree (`repo/` + `unom.flatpakrepo` + `io.unom.Punktfunk.flatpakref` +
`index.html`). The edge Caddy on home-reverse-proxy-1 fronts it at `https://flatpak.unom.io`.
The CI deploy step **no-ops until the secret + infra exist**, so it won't redden builds mid-setup.
**Signing key:** dedicated RSA-4096 key `unom Flatpak Repo <flatpak@unom.io>`. Public key committed
at [`unom-flatpak.gpg`](unom-flatpak.gpg) (its base64 goes into the `.flatpakrepo`/`.flatpakref`
`GPGKey=`); private key (ASCII-armored, then base64) lives only in the CI secret.
One-time setup (mirrors any new unom DMZ service — see the deploy-infra notes):
1. **Secret** `FLATPAK_GPG_PRIVATE_KEY` on this repo = base64 of the armored private key
(`gpg --armor --export-secret-keys <fpr> | base64 -w0`). `DEPLOY_*` + `REGISTRY_TOKEN` already exist.
2. **Edge Caddy** on home-reverse-proxy-1 (`/home/caddy/caddy/Caddyfile`, apply by hand + `./reload.sh`):
`flatpak.unom.io { reverse_proxy 192.168.50.50:3230 }`
3. **Port allowlist:** add `3230` to `caddy_target_ports` in `unom/infra` (proxmox/unom-1) + terraform apply.
4. **DNS:** ensure `flatpak.unom.io` resolves to the edge proxy.
Re-signing/rotation: regenerate the key, replace `unom-flatpak.gpg` + the secret; every client must
re-add the remote (the `GPGKey` changed), so rotate rarely.
## Alternatives considered
- **Hosted OSTree repo (chosen):** the only option that gives `flatpak update`. We self-host the
static tree on unom-1 behind Caddy (Gitea has no flatpak/ostree registry); the build already
produces the repo, so the marginal cost is GPG signing + an rsync + a 10-line static container.
- **Generic registry bundle (kept as fallback):** one curl to publish, one `flatpak install
--bundle` to consume; mirrors the deb/rpm curl-upload pattern. No auto-update — this is what the
**Decky plugin** pulls (stable `latest/punktfunk-client.flatpak`), plus the offline/manual path.
- **Release attachment:** also done on tags, good for a human-facing download page.
- **Flathub (deferred):** best discoverability + zero hosting, but a separate submission/review
process and less control; revisit once the client is past scaffold quality.
Reference in New Issue View Git Blame Copy Permalink