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>
4.0 KiB
title, description
| title | description |
|---|---|
| Host CLI | The punktfunk-host commands and the flags you'll actually use. |
The host is one binary, punktfunk-host. Most of the time you'll run a single command; the rest reads
its settings from host.env.
serve
The normal way to run a host. By default serve starts the secure native host: the native
punktfunk/1 server (QUIC, SPAKE2 PIN pairing, per-direction AEAD) plus the management API/web
console — all in one process. The native plane is always on; there is no flag to turn it off.
punktfunk-host serve
Add --gamestream (alias --moonlight) to also run the GameStream/Moonlight-compatible planes
(nvhttp pairing, RTSP, ENet control, _nvstream mDNS) — required for stock Moonlight
clients. This is opt-in because GameStream carries inherent on-path weaknesses (pairing over plain
HTTP; its legacy control encryption can reuse GCM nonces — security-review #5/#9), so enable it only
on a trusted LAN. The native plane is immune to those issues.
punktfunk-host serve --gamestream
| Flag | Meaning |
|---|---|
--gamestream / --moonlight |
Also run the GameStream/Moonlight-compat planes (for stock Moonlight clients). Opt-in, trusted-LAN only — see above. |
--native |
No-op. The native punktfunk/1 server always runs in serve; kept only for backward compatibility. |
--native-port <PORT> |
Native QUIC port (default 9777). |
--open |
Don't require pairing — serve any device on the network. Off by default; only for trusted single-user setups. |
--mgmt-bind <IP:PORT> |
Management API address (default loopback 127.0.0.1:47990). |
--mgmt-token <TOKEN> |
Override the bearer token for the management API. |
These are the only flags serve accepts.
The management API is always HTTPS with bearer-token auth. If you don't pass --mgmt-token, a token
is auto-generated and persisted to ~/.config/punktfunk/mgmt-token; --mgmt-token only overrides it. A
token is required when you bind the API off loopback with --mgmt-bind. Every endpoint is documented
in the interactive API Reference.
By default the host requires pairing — see Pairing & Trust. On serve you
arm pairing from the web console (or mgmt API); the host then displays a 4-digit PIN. Pass --open to
turn off the mandatory-pairing default and serve any device on the network (trusted single-user setups
only). The pairing flags below are punktfunk1-host-only and do not apply to serve.
punktfunk1-host
A standalone native-only host, mainly for testing the punktfunk/1 path without the GameStream server
or web console.
punktfunk-host punktfunk1-host --source virtual
| Flag | Meaning |
|---|---|
--port <N> |
QUIC listen port (default 9777). |
--source synthetic · virtual |
virtual uses a real virtual display + NVENC; synthetic emits test frames. |
--seconds <N> / --frames <N> |
Bound each session by wall-clock seconds or frame count. |
--max-concurrent <N> |
Stream at most N sessions at once (default 4); overflow waits in the queue. |
--max-sessions <N> |
Exit after N sessions (0 = serve forever). |
--allow-pairing |
Accept PIN pairing; the host prints a PIN when a client pairs. |
--require-pairing |
Only serve paired devices (implies --allow-pairing). |
--max-concurrent, --allow-pairing, and --require-pairing are punktfunk1-host-only — serve does not
accept them. On serve you arm pairing from the web console instead, and concurrency is fixed at
the built-in default (4 sessions) rather than settable from the command line.
Both serve and punktfunk1-host advertise the host on the network so clients can discover it. List
hosts from another machine with punktfunk-probe --discover.
Environment
Most behaviour (compositor, video source, input backend, zero-copy) is set in
host.env, not on the command line. When running as a
service, the unit loads host.env for you.