feat(clients): unified stats vocabulary across every client + Moonlight comparison docs

One stat model everywhere (design/stats-unification.md): four measurement
points (capture/received/decoded/displayed), three stages that tile the
interval exactly, and a HUD that shows the addition explicitly —

  end-to-end 14.2 ms p50 · 19.8 p95 · capture→on-glass
  = host+network 9.8 + decode 2.1 + display 2.3

replacing each client's ad-hoc mix of overlapping absolutes (the Apple HUD's
three arrow lines that looked sequential but weren't), mean-vs-median decode
times (Windows/Linux), missing same-host-clock flags (Windows/Linux), and
three different names for the same capture→received measurement (probe's
"reassembled", Apple/Android's "client", Windows/Linux's post-decode "lat").

Per client: Apple threads receivedNs through the VT decode via the frame
refcon bit pattern so the decode stage exists at all (stage-1 fallback
honestly degrades to a capture→received headline); Windows carries
FrameTimes through the existing frame channel to the render thread and adds
e2e p50/p95 post-Present; Linux stamps received at AU pop and rides
decoded_ns on DecodedFrame to the paintable-set site; Android pairs receipt
stamps with MediaCodec output buffers via the codec's pts round-trip (JNI
stats array 14→16 doubles, indexes 0-13 unchanged). fps now uniformly counts
received AUs; lost/(received+lost) per window, hidden at zero.

docs-site gains "Understanding the Stats Overlay": what each line means, why
the equation only approximately sums (percentiles), and a line-by-line
Moonlight/Sunshine matrix — including that Moonlight has no end-to-end
number and its "network latency" is an ENet control RTT, so punktfunk's
headline must not be compared against any single Moonlight line.

Verified here: linux client + probe + core check/clippy/fmt green, android
native cargo-ndk arm64 check green. Pending: Windows CI + on-glass, swift
test on the mac, on-device Android.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

This commit is contained in:

Enrico Bühler

2026-07-03 21:01:29 +00:00

parent c7630ff5dc

commit 09a5957c6d

38 changed files with 1122 additions and 380 deletions

									
										clients/apple/Sources/PunktfunkClient/Screenshots/ScreenshotScenes.swift
									
		+4
		-1
	
												View File
												
				@@ -170,7 +170,10 @@ private struct ShotHUD: View {

				                Text("5120×1440@240  240 fps  812.4 Mb/s")

				                    .font(.system(.caption, design: .monospaced))

				            }

				            Text("capture→client 1.3/2.1 ms p50/p95")

				            Text("end-to-end 2.9 ms p50 · 3.8 p95 · capture→on-glass")

				                .font(.system(.caption2, design: .monospaced))

				                .foregroundStyle(.secondary)

				            Text("= host+network 1.3 + decode 0.7 + display 0.9")

				                .font(.system(.caption2, design: .monospaced))

				                .foregroundStyle(.secondary)

				            #if os(macOS)