dtoro
b5c1247093
Problem: after the wiki-hq reorg, agent-instruction and human-doc domains were still scattered across the repo root, with three now-redundant stub files cluttering it. The organizing principle wasn't visible in the layout. Change — enforce three clear buckets: - .agents/ = how agents operate: OIKOS.md, HERMES.md (moved from root), shared/ conventions, domains/ schemas, skills/, and operations/ (operator cheatsheet + enrollment + hermes-agent, moved from root). - knowledge/ = what exists + evidence: wiki/, GLOSSARY.md, and sources/ now including investigations/ (incident records are evidence/sources). - root = substrate + two entry points (AGENTS.md, README.md), plus plans/ as its own design-intent domain. Moves: - investigations/ -> knowledge/sources/investigations/ (incl. archive/, index). - operations/ -> .agents/operations/. - HERMES.md -> .agents/HERMES.md. - Deleted unreferenced root stubs CAVEMAN.md, CONTRIBUTING.md, and OIKOS.md (its 7 remaining linkers repointed to .agents/OIKOS.md). Consumers updated: - inventory.yaml doc_page (agent-enrollment) + regenerated hosts/*.yaml + cards. - tools/setup-hermes-soul.sh and bootstrap.sh (x2) -> .agents/HERMES.md. - bin/homelab help string -> .agents/operations/hermes-agent.md. - knowledge/operations schemas, llm-wiki, page-templates, incident-investigation skill, AGENTS.md/README nav -> new investigations/operations paths. - All markdown links rewritten via the path-resolving mapper. Left in place (substrate/executable/separate-domain): hosts/, ledger/, tools/, plans/, oikos/, mcp/, secrets/, bin/, inventory.yaml. Verification: docs-lint at baseline (2 intentional cross-repo refs, no new breakage); gen-topology.py --check exit 0; build_host_files.py idempotent; all doc_page targets resolve; Hermes provisioning scripts point at the new path. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
84 lines
4.7 KiB
Markdown
84 lines
4.7 KiB
Markdown
# 2026-06-03 — Moonlight/Sunshine game streaming unstable over WiFi
|
||
|
||
## Summary
|
||
|
||
[`ludo-mini`](../../../hosts/strong.yaml) runs Sunshine as the game-streaming server; [`mac-mini`](../../../hosts/mac-mini.yaml) runs Moonlight as the client. Despite both machines being on the same physical subnet (192.168.178.0/24), streaming was unstable — stuttering, dropouts, and high latency. Root cause: **mac-mini is connected only via WiFi**, while ludo-mini is wired Ethernet (2.5 Gbps). WiFi throughput shows 1-second UDP dropouts and high jitter (28 ms stddev), which breaks real-time video streaming.
|
||
|
||
## Timeline
|
||
|
||
### Pre-existing state
|
||
- ludo-mini: wired Ethernet (eno1, 2.5 Gbps), 192.168.178.181/24
|
||
- mac-mini: WiFi (en1, 802.11ac, 234 Mbps Tx rate, 1 stream, -60 dBm RSSI), 192.168.178.99/24
|
||
- Both on the same subnet via a consumer router at 192.168.178.1
|
||
- Sunshine configured: bitrate=80 Mbps, encoder=amf (AMD GPU), fec_percentage=5, hevc_mode=2
|
||
- Moonlight configured: bitrate=57 Mbps, fps=60, localaddr=192.168.178.181 (correct)
|
||
|
||
### 2026-06-03 — investigation
|
||
**Network tests (iperf3 between mac-mini ↔ ludo-mini):**
|
||
- TCP throughput: 49–86 Mbps, average ~65 Mbps — highly variable
|
||
- UDP throughput: 1-second complete dropout during a 5-second test; 0% loss otherwise
|
||
- Ping: 4.7 ms avg, but **28 ms stddev**, max **138 ms** — WiFi-level jitter
|
||
- Netbird P2P connection also showed 7 ms latency over the tunnel (unnecessary given same-subnet direct connection)
|
||
|
||
**Additional findings:**
|
||
- mac-mini has a built-in Ethernet port (en0) but it is inactive — no cable connected
|
||
- mac-mini also has Thunderbolt Ethernet adapters (en5, en6, en7) all inactive
|
||
- ludo-mini's en0 shows `speed 2500` (2.5 GbE)
|
||
- Netbird routes `192.168.8.0/24` via `utun100`, but 192.168.178.0/24 traffic stays on `en1`
|
||
|
||
## Root cause
|
||
|
||
mac-mini is on WiFi. WiFi introduces:
|
||
1. **Throughput variance** — 49–86 Mbps TCP fluctuation
|
||
2. **Dropouts** — 1-second UDP blackouts from radio retransmissions
|
||
3. **Jitter** — 28 ms stddev with spikes to 138 ms
|
||
|
||
Moonlight/Sunshine streams real-time video over UDP. Any jitter spike or dropout causes visual stutter or frame drops. The 57 Mbps Moonlight bitrate was too aggressive for the WiFi link's consistency, even though the average throughput is ~65 Mbps.
|
||
|
||
## Mitigations applied
|
||
|
||
### mac-mini — Moonlight (via `defaults write`)
|
||
|
||
| Setting | Before | After | Rationale |
|
||
||---------|--------|-------|-----------|
|
||
|| bitrate | 57 Mbps | 25 Mbps | Reduce to a level WiFi can sustain consistently |
|
||
|| framepacing | off (0) | on (1) | Smooths frame timing over variable latency |
|
||
|| fps | 30 | 60 | Restored to game-appropriate value |
|
||
|
||
### mac-mini — Moonlight (current, wired — 2026-06-04)
|
||
|
||
| Setting | WiFi value | Wired value | Rationale |
|
||
||---------|-----------|-------------|-----------|
|
||
|| bitrate | 60 Mbps | 80 Mbps | Wired 1 GbE can sustain comfortably |
|
||
|| framepacing | on (1) | off (0) | Wired latency is consistent, no smoothing needed |
|
||
|| fps | 60 | 60 | Unchanged |
|
||
|
||
### ludo-mini — Sunshine (via SSH)
|
||
|
||
| Setting | WiFi value | Wired value | Rationale |
|
||
||---------|-----------|-------------|-----------|
|
||
|| bitrate | 40 Mbps | 80 Mbps | Wired can handle full bandwidth |
|
||
|| fec_percentage | 2 | 5 | Restored to default — wired has no dropout concern |
|
||
|| packetsize | 1024 | 1316 | Restored to default (Ethernet MTU) |
|
||
|
||
Sunshine restarted after changes; confirmed active.
|
||
|
||
## Resolution
|
||
|
||
### 2026-06-04 — mac-mini wired to LAN
|
||
|
||
mac-mini plugged into Ethernet (en0, 192.168.178.182). This definitively resolves the WiFi jitter that caused streaming instability. All WiFi-era conservative settings reverted to appropriate wired values on both ends.
|
||
|
||
## Open questions
|
||
|
||
~~1. **Ethernet wiring** — mac-mini has an active en0 port. Plugging it into the same switch/router as ludo-mini would eliminate WiFi jitter entirely. This is the definitive fix.~~ **RESOLVED** — mac-mini now wired via en0.
|
||
2. **WiFi alternatives** — If wiring is impractical, a WiFi 6 (802.11ax) USB adapter or Thunderbolt-to-Ethernet adapter would help, but wired Ethernet is the only reliable solution for game streaming.
|
||
3. **Netbird route** — `192.168.8.0/24` is routed over Netbird `utun100`. If Moonlight ever falls back to that subnet (ludo-mini's 192.168.8.133 LAN IP), traffic tunnels unnecessarily. Moonlight correctly uses 192.168.178.181, so this is not currently an issue.
|
||
|
||
## Changelog
|
||
|
||
### 2026-06-04 — mac-mini wired to LAN, configs reverted from WiFi mitigations
|
||
- mac-mini connected via en0 (wired Ethernet, 192.168.178.182), WiFi mitigations no longer needed
|
||
- Moonlight: bitrate 60→80 Mbps, framepacing disabled
|
||
- Sunshine: bitrate 40→80 Mbps, fec_percentage 2→5, packetsize restored to default (1316)
|
||
- First root cause in investigation (Open questions #1) resolved |