enricobuehler
12a5318397
The host stamps `pts_ns` on every audio datagram and the client decoded it
into `AudioPacket` — and then never read it. Video's `pts_ns` is used end to
end (the presenter computes a true glass-to-glass `displayed + clock_offset −
pts`), so audio free-ran at whatever depth its jitter ring happened to reach,
video was presented on an independent path, and nothing ever compared them.
The A/V offset was an accident of buffer depths: it moved whenever the ring
ratcheted under underrun pressure, and it got WORSE every time video got
faster, because a quicker decoder lowers the video leg and leaves audio's
exactly where it was. That is what a field report on the Steam Deck heard as
"the audio delay is way too high", and it is why shaving milliseconds off the
audio budget had not helped.
Video is the master. In a game streamer the video leg is the input-feel budget
and must never be inflated to satisfy the audio clock, while audio tolerates
small crossfaded corrections that are inaudible — and `crossfade_drop` already
applies them. So audio moves:
audio_e2e = (now + buffered_ahead + clock_offset) − pts_ns
av_offset = audio_e2e − video_e2e (> 0 ⇒ audio behind the picture)
`AvSync` smooths that with an EWMA, ignores what sits inside a deadband no
listener can detect, refuses the implausible outright rather than clamping it
(a wall-clock step must not steer the ring), and proposes a depth.
Continuity outranks sync, always. `JitterPolicy::set_sync_target` only ever
takes a REQUEST, clamped between the existing underrun-driven floor and the
hard cap. A link whose jitter genuinely needs more buffer than the picture is
away keeps its buffer and the residual is reported — sync can never starve the
ring into dropouts. `None` is the default and reproduces the previous behaviour
exactly, so the four client rings can adopt this one at a time without
diverging.
Two upstream defects found on the way, both prerequisites:
* The host stamped `pts_ns` at ENCODE time, inside the loop draining an
already-accumulated chunk, so every frame of a chunk carried near-identical
timestamps describing when we got round to encoding. Harmless while nothing
consumed it; a sync loop regulating against it would regulate against a
fiction. It now comes off the capture clock.
* The host did not pace. One capture callback hands over a whole quantum — 5 ms
when the graph honours our ask, 21.3 ms on a VM, where stock PipeWire raises
`min-quantum` to 1024 — and the loop drained all of it into back-to-back
`send_datagram` calls. The wire carried a 4-5 frame burst then ~21 ms of
nothing, and a ring can only absorb that by standing a burst period deep.
Frames now leave on the audio clock, which costs no average latency.
And the reason none of this was visible: `buffer_ms`/`target_ms` existed only
as a `tracing::debug!` line, absent from `Stats`. On a Deck the client runs
under Steam's `reaper` with stdout on a pipe nobody can read, so the one number
identifying a deep ring was unobtainable on the device reporting the latency.
The HUD now carries `audio buffer N ms · a/v ±N ms` — both, because a deep ring
on a jittery link is correct and only the offset separates that from audio held
late. The host also reports its negotiated quantum against the one it asked
for, per capture open rather than once per process.
Verified: 364 core + 40 presenter tests on Linux, clippy -D warnings clean on
punktfunk-{core,host} + pf-{client-core,presenter}, fmt clean. New tests pin
the safety invariant (sync cannot pull the target below the continuity floor on
any preset), that `None` leaves the policy bit-identical, and that a device
quantum exceeding the hard cap does not panic `Ord::clamp` inside a realtime
callback.
Android and Apple keep today's behaviour (the `None` default) until their
presenters publish a video figure to align against; design/audio-latency-
overhaul.md carries the plan.
punktfunk-host
The streaming host — the program you run on the machine whose desktop or games you want to stream. For each client that connects, it spins up a virtual display sized to that device, captures it on the GPU, encodes with hardware NVENC/VAAPI/AMF/QSV, and sends it out over a low-latency transport — no physical monitor, no letterboxing, no rearranging your real screens.
It speaks two protocols from one process:
- GameStream — so any Moonlight / Artemis client works day one.
punktfunk/1— punktfunk's own faster protocol (QUIC control plane, GF(2¹⁶) FEC + AES-GCM data plane) that the native clients use.
Runs on Linux (the primary, most battle-tested path) and Windows (x64). The shared protocol,
FEC, and crypto live in punktfunk-core; this crate is everything
platform-facing around it.
What it does
- Per-client virtual displays at the exact WxH@Hz. Linux uses per-compositor backends — KWin, gamescope, Mutter, and Sway/wlroots; Windows uses its own all-Rust IddCx virtual display, even on the secure desktop (UAC / lock screen).
- GPU zero-copy capture → encode. dmabuf → CUDA/Vulkan → NVENC on Linux; on Windows the host pushes frames straight into its own IDD (sealed IDD-push, no screen-scraping) → GPU encode. Encoders auto-select by GPU vendor: NVENC (NVIDIA), VAAPI (Linux AMD/Intel), AMF/QSV (Windows AMD/Intel), or software H.264 as a floor. HDR/10-bit and HEVC 4:4:4 supported.
- Input injection. Mouse/keyboard (libei / gamescope EIS / wlr / Windows SendInput) and virtual gamepads — Xbox 360/One, DualSense, DualShock 4 — with rumble and HID feedback back-channels.
- Audio both ways. Opus audio host→client, plus a virtual microphone the client can talk into.
- Trust & discovery. A persistent host identity, SPAKE2 PIN pairing (default) or TOFU, and mDNS auto-advertisement so clients find the host without typing an IP.
- Management API + web console. A REST API (
mgmt.rs, OpenAPI atapi/openapi.json) drives status, paired devices, and on-demand pairing; the browser UI is inweb/.
Run it
punktfunk-host serve runs inside your desktop session. Bare serve is the secure native-only
default (punktfunk/1 + the management API); add --gamestream on a trusted LAN to also accept
stock Moonlight clients.
# Linux, from the repo root (see the repo README "Running on this box" for the headless recipe):
cargo run -rp punktfunk-host -- serve # native-only (secure default)
cargo run -rp punktfunk-host -- serve --gamestream # + Moonlight compatibility
Then pair from the web console (https://<host-ip>:47992) or the client app.
Most people should install a package rather than run from source — see
packaging/ (apt · rpm/COPR/bootc · Arch/sysext · Windows installer) and
the per-platform guides at docs.punktfunk.unom.io/docs/install.
Subcommands
| Command | Purpose |
|---|---|
serve |
The host (native punktfunk/1 + mgmt API; --gamestream adds Moonlight). |
punktfunk1-host |
Standalone native-protocol listener for testing/measurement (--source virtual, --max-sessions). |
openapi |
Print the management-API OpenAPI spec (regenerates api/openapi.json). |
library |
Inspect the multi-store game library. |
service · driver · web |
Windows: SCM service, driver install, bundled web console. |
*-test / *-selftest / *-probe |
Diagnostics (input, zero-copy, HDR, compositor, gamepads). |
--help lists them all.
Layout
src/
main.rs CLI + subcommand dispatch
config.rs · session_plan.rs · session_tuning.rs · pipeline.rs session setup + the frame pipeline
vdisplay/ per-compositor virtual outputs (kwin · gamescope · mutter · wlroots)
capture/ · capture.rs screen/dmabuf capture (+ Windows IDD-push)
encode/ · encode.rs per-GPU encoders (nvenc · vaapi · ffmpeg_win (AMF/QSV) · sw)
linux/zerocopy/ dmabuf → CUDA → NVENC bridges (EGL/GL tiled, Vulkan LINEAR)
inject/ · inject.rs input backends (libei · wlr · uinput gamepads · UHID DualSense/DS4)
audio/ · audio.rs Opus out + virtual mic (PipeWire / WASAPI)
gamestream/ Moonlight compat: nvhttp · pairing · rtsp · control · stream · gamepad · apps
native.rs the native punktfunk/1 host (QUIC control + native-thread UDP data plane)
mgmt.rs · native_pairing.rs · stats_recorder.rs management API, pairing, perf capture
hdr.rs · library.rs HDR metadata; multi-store game library
linux/ · windows/ platform-confined backends
Related
punktfunk-core— the shared protocol · FEC · crypto core- Clients — the apps that connect (Apple · Linux · Windows · Android · probe)
- Packaging & docs — install & operate
- punktfunk-planning (internal planning repo) — architecture rationale and deep-dive plans