Repository navigation
Description
Summary
High Performance mode (and so Match Client) only works when the client and the Mac are on the same subnet. Over a VPN path that includes NAT, the session gets 0 video packets. It reconnects a few times and the user ends up with no client-sized virtual display.
It looks like the client never sends a UDP packet until it has received one. The Mac sends media to :5900/5901. Behind NAT, that address is the NAT gateway, so the gateway has no mapping to forward the stream back.
Setup
Server: Mac Studio, macOS Screen Sharing, High Performance. Main display 7680×2160, so tiles=4.
Client: rootshell on iPhone (Wi‑Fi), High Performance · Match Client.
Path that fails: client LAN → travel router (masquerade into WireGuard) → home gateway → Mac. The home gateway also SNATs VPN traffic into the Mac's subnet, so the Mac sees the gateway's LAN address as the peer.
Path that works: client and Mac on the same Wi‑Fi/LAN, with no NAT.
What the client log shows (VNC Debug Logging)
Apple ServerInit capabilities: flags=0x52 preciseScroll=true dynamicDisplay=true
Apple media bearer=Wi-Fi initialBWE=20000kbps screenTransport=local
POSIX UDP started local=5900 remote=:5900 ...
POSIX UDP started local=5901 remote=:5901 ...
Deferring staged virtual display 2048x3408 until initial Apple media negotiation completes
Apple media DisplayInfo2 announced 1 screens: 7680x2160; captureLuma=16588800 tiles=4
Apple AVC message 2 accepted offer lengths audio=315 video=452 video2=0
Startup media watchdog: 0/4 sources decoding (attempt 1..3); requesting native FIR after rate settled
Video bootstrap failed (0/4 bands decoding after 3 FIR attempts); re-requesting the media stream before dropping the connection
Connection terminated: ... sinceVideoRTP=never highPerformance=true videoSources=0 interface=wifi
[HEARTBEAT] ... sinceVideoRTP=never videoSources=0 bitrate=0kbps
What the network shows (same session)
On the Mac (netstat -anv -p udp): avconferenced sockets :5901 ↔ :5901 and :5900 ↔ :5900. rxbytes stays at 0 and txbytes grows to about 186 MB in 40 s, so the Mac is streaming.
On the home gateway (conntrack): only src= sport=5901 dst= dport=5901 ... [UNREPLIED], about 330 MB. There is no client→Mac UDP entry at all. TCP 5900 is present and works.
On the travel router (conntrack): TCP 5900 is present, and no UDP from the client to the Mac.
So no UDP ever leaves the client towards the Mac. With no outbound packet there is no NAT mapping, and the Mac's media is addressed to the gateway itself.
Why (from the source)
Every UDP send in TransportSession takes its channel from state that only exists after a packet has arrived:
appleMediaVideoSSRCChannels[header.ssrc] = channel (transportsession.swift:6630) is set on the first received video RTP. The FIR, NACK, LTR ack and loss-feedback senders (for example sendAppleMediaKeyframeRequest, :6342) all look up a channel there.
appleMediaAudioChannel (:6604) is set on the first received audio RTP, and only then does sendAppleMediaAudioReceiverReport (:7378) run.
configureAppleMediaUDP (:5488) binds localPort == remotePort and then waits.
That's fine on a flat LAN, but nothing ever opens a NAT mapping.
Suggested fix
As soon as each media UDP channel is bound (in startAppleMediaStreamUDPIfNeeded), before the offer is accepted and the Mac starts sending, send one small datagram from that local port to the Mac's matching port. Repeat about every 15–20 s until the first RTP arrives on that channel, then rely on the normal RTCP traffic.
Ideally the datagram is something the server already tolerates, such as a protected RTCP RR with no report blocks or whatever native Screen Sharing sends. Only the 5‑tuple matters for the NAT.
Timing matters for Linux‑style NAT. If the Mac's packets reach the gateway first, the gateway already holds an UNREPLIED entry mac:5901 → gw:5901. The client's SNAT would collide with it and get a different source port. Sending at bind time avoids that in the common case.
The NAT keeps the source ports in my setup (masquerade and SNAT --persistent), so once the mapping exists the Mac's gw:5901 traffic should be translated back to the client.
I haven't built or tested a patch. If this approach sounds right to you, I'm happy to open a PR or test a build over this setup.
Activity
Fix High Performance showing no video behind a NAT
Update rootshell-vnc to 0.1.40
kitknox commentedon Nov 15, 2026
Fix is in 614847f please give this a test. It should go out in the next build of rootshell as well.
cnsren commentedon Nov 15, 2026
kitknox commentedon Nov 15, 2026
Hmm. The TestFlight build doesn't have this fix so if it is working it may be from the other recent changes that allow high performance mode to work at lower bitrates.
cnsren commentedon Nov 15, 2026
You're right, my mistake. My TestFlight build is 1.0.16 (178) and it doesn't have 614847f. I looked closer while connected just now: High Performance still fails over the NAT path. The gateway shows only
[UNREPLIED]Mac→gateway UDP on 5900/5901, and the Mac's sockets receive 0 bytes. The session then falls back to Standard, and because 0.1.39 also uses the Apple virtual display in Standard, Match Client still works over TCP. That's what I mistook for the fix.So 178 is a nice improvement on its own (client-sized display over plain TCP), but the UDP issue is still there. I'll retest High Performance once a build with 0.1.40+ ships and report back.