Description
Feature Request: In-client network-quality measurement (jitter / loss / RTT) on native Heads
Summary
Add a lightweight network-quality probe to the HydraHead Flatscreen client that measures jitter, packet loss, reordering, and RTT on the active path to the Body, and reports it to HydraNeck as diagnostics telemetry. Today this data exists only implicitly for the WebRTC path (round-trip time drives quality-tier selection); native Moonlight Heads streaming over the WireGuard mesh have no equivalent visibility.
Motivation
Per the Traffic Flows doc, remote native Heads reach Bodies as Head → WireGuard → Hub → WireGuard → Body, over consumer ISP paths in many deployments. VR/XR streaming quality is governed far more by jitter and tail latency than by average RTT or hop count — a steady 20 ms path outperforms a jumpy 12 ms one, because jitter both causes missed-frame hitches and forces a larger jitter buffer that raises motion-to-photon latency.
HydraNeck is positioned as the diagnostics layer, but currently there's no way for a partner or engineer to answer "why does streaming feel bad at Venue X?" with data. Hop-count and a one-off ping don't capture it. This feature gives operations a real signal and lets Heads make better path/quality decisions.
Proposed behaviour
Measurement. The Head runs a UDP probe against the Body (or district server) that measures inter-arrival jitter using the RFC 3550 running estimate, plus loss and out-of-order counts. Probe packets should approximate the stream's real packet rate/size, and run inside the WireGuard tunnel, so numbers reflect the actual streaming path — not an idle ICMP ping outside it.
Two contexts:
Pre-flight: a short probe during discoverBody(), after the LAN-vs-WireGuard path is chosen, to characterise the path before launching Moonlight.
In-session (optional): a low-rate continuous probe so hitches can be correlated with jitter/loss spikes in real time.
Report percentiles, not just averages. Capture p50 / p95 / p99 / max jitter, loss %, and reordering. For VR the tail is what hurts — an average that looks fine can hide periodic p99 spikes that drop frames.
Telemetry to HydraNeck. Push results as a per-session diagnostics record tagged with district, venue, Body, chosen path (LAN / WireGuard), and Head type, so partners and engineers can see per-venue and per-path quality over time.
Feed path/quality decisions. Extend the existing quality-tier logic (currently RTT-only on the WebRTC side) so jitter and loss can influence tier selection or trigger a warning when a path is unfit for VR.
Measurement notes / correctness
Use one-way inter-arrival jitter, which needs no clock sync (it's built from deltas on the receiver's monotonic clock, so a constant offset cancels). Do not report absolute one-way latency unless NTP/PTP sync is in place — consumer NTP error would make it meaningless.
On Android/headset Heads, use a monotonic timebase (System.nanoTime) and timestamp as close to the socket as possible, so device scheduling jitter isn't mistaken for network jitter. Distinguishing the two is itself useful diagnostic output.
Acceptance criteria
Native Head records jitter (p50/p95/p99/max), loss %, reordering, and RTT for the active path.
Measurement runs inside the WireGuard tunnel at a realistic packet profile.
Results are visible in HydraNeck per session, filterable by district / venue / Body / path.
No meaningful added latency to the stream from an in-session probe (sub-1% overhead target).
Non-goals
Not a replacement for full APM; this is path-quality telemetry, not GPU/render metrics (those belong to HydraNode/HydraCluster).
Not attempting synchronised absolute one-way latency in v1.