Streaming Windows Games to a Mac with Moonlight
Streaming Windows Games to a Mac with Moonlight
Sunshine runs on the Windows gaming PC, while Moonlight on the Mac receives video and sends keyboard, mouse, and controller input. The game still runs on Windows; the Mac needs neither the Windows game installation nor a compatibility layer.
My setup uses a Mac mini M4 and a Windows 11 laptop with an RTX 3050 Ti Laptop and 4 GiB of VRAM, playing GTA5. This guide starts with a LAN connection, then covers black screens, Sunshine crashes, NVENC timeouts, and image quality. On a low-VRAM laptop, game and encoder workloads need attention together.
1. Preparation
| Location | Preparation |
|---|---|
| Windows host | Working graphics driver and locally playable game; install Sunshine |
| Mac client | Install Moonlight; access the host's LAN |
| Network | Prefer wired Ethernet for the host; temporarily wire the Mac to isolate Wi-Fi variation |
| Display | Keep an active Windows display available for capture; test the ordinary desktop first |
Windows game → Sunshine capture/encoding → LAN → Moonlight decoding → Mac display
↑ │
└──────── input control ────────┘Complete the LAN setup first. Remote access adds routing, reachability, and access-control questions that are easier to investigate after local streaming works.
2. Install Sunshine
Download the appropriate Windows/CPU-architecture installer from Sunshine releases. Follow its installation instructions and use the installed service rather than launching a second instance manually. Check the graphics-driver requirements for both a new install and an upgrade. See Windows installation.
On the Windows host, open the default management address:
https://localhost:47990Create the management account on first use. Its default certificate is self-signed: verify that the address belongs to your host before proceeding. The management password is separate from a Moonlight pairing PIN. Check that the application list contains Desktop.
Inspect the service and process in administrator PowerShell:
Get-Service *sunshine*
Get-Process sunshine -ErrorAction SilentlyContinue |
Select-Object Id,StartTime,PathIf no service appears, inspect installation logs and the installation method. If an instance already runs, do not start another with a different configuration directory. Keep default encoding settings initially instead of changing HEVC, HDR, and advanced NVENC options together.
2.1 Port settings
Sunshine's default base port is 47989; its web interface defaults to 47990. Changing the base offsets the other ports. My host used base 48989, putting management at https://host-ip:48990. That was a custom configuration, not a required installation step.
Change ports only for a confirmed conflict, then align the ports shown by Sunshine, firewall rules, and the Moonlight host address. A reachable management page does not validate video traffic. See network configuration.
2.2 Firewall rules
Retain the installer-created rules and verify they are enabled for the current network profile:
Get-NetConnectionProfile | Select-Object InterfaceAlias,NetworkCategory
Get-NetFirewallRule -DisplayName '*Sunshine*' |
Select-Object DisplayName,Enabled,Profile,Direction,Action
Get-NetFirewallRule -DisplayName '*Sunshine*' |
Get-NetFirewallPortFilter |
Select-Object Protocol,LocalPort,RemotePortNames vary by package/language; inspect program paths in Windows Defender Firewall with Advanced Security if needed. Streaming video requires UDP, so a TCP probe alone cannot validate it. Update relevant rules after custom port changes; permitting only WebUI is insufficient, and leaving the whole firewall disabled is not a repair.
3. Install and pair Moonlight
Follow the macOS download from the Moonlight website, install, and launch. Keep Windows logged into its desktop with an active display.
- Look for the discovered Windows host. If absent, add its LAN IPv4 address manually.
- For a custom base, enter host-ip:port, for example 192.168.1.50:48989. This is not the management port.
- Select the host and obtain the PIN shown by Moonlight.
- Enter that PIN on Sunshine's PIN page and submit.
- Return to Moonlight, open the application list, and start Desktop.
Use the UI rather than editing sunshine_state.json or calling the pairing API. For duplicate host names, check IP/port and the actual Windows streaming services before removing obsolete client entries. See the Moonlight setup and controls.
4. First stream
These starting settings create an easy-to-diagnose baseline rather than maximum quality:
| Setting | Starting point |
|---|---|
| Resolution | 1920 × 1080 |
| Frame rate | 60 FPS |
| Bitrate | 15–20 Mbps; reduce for an unstable link |
| Codec | Automatic; compare H.264 separately for compatibility |
| HDR | Off until SDR works |
Move windows, play audio, and test mouse/keyboard. Ctrl+Alt+Shift+S opens performance statistics; Alt corresponds to Option on a Mac keyboard. Inspect frame rate, network drops, and decoding time, then start the game and compare. Ctrl+Alt+Shift+Q ends the stream without guaranteeing that the host game closes.
Check game, Windows desktop, and requested stream resolutions together. Selecting 1080p in Moonlight does not guarantee an automatic host-display switch. Confirm aspect ratio, text size, and captured display before increasing refresh rate or enabling HDR.
5. Black video and missing audio
Work through network and capture separately:
- Test Desktop first. If it works and only one game is black, inspect fullscreen/windowed mode, display selection, and capture rather than immediately re-pairing.
- Confirm an active host display. Recheck capture output after closing a laptop lid, unplugging a screen, or changing display mode.
- Inspect the current network and UDP rules. This matters after Wi-Fi, VPN, or base-port changes. Reachable WebUI and successful ping do not clear video transport.
- Read display/encoder initialization logs. On hybrid-GPU laptops, identify the actual display adapter instead of assuming every output uses NVIDIA.
- Separate audio diagnosis. Confirm local Windows playback and client volume, then inspect Sunshine's chosen audio device.
After changing sessions through RDP, retry from the normal host console desktop. If lower bitrate immediately helps, use Moonlight network statistics to investigate the link; black video alone is not evidence of VRAM exhaustion. See Moonlight troubleshooting.
6. Sunshine crashes
With Sunshine 0.23.1, I encountered frozen video and failed reconnects while the service still showed Running. Application events recorded six crashes within one minute, and Sunshine logged repeated startup sequences. Recovery can restart a process while hiding that it crashed.
On Windows:
Get-Service *sunshine*
Get-Process sunshine -ErrorAction SilentlyContinue |
Select-Object Id,StartTime,Responding
Get-WinEvent -FilterHashtable @{
LogName='Application';Id=1000;StartTime=(Get-Date).AddHours(-3)
} | Where-Object Message -match 'Sunshine' |
Select-Object TimeCreated,Id,Message
Get-Content 'C:\Program Files\Sunshine\config\sunshine.log' -Tail 100Compare changing process StartTime, events naming the executable, and repeated initialization. This case had 0x80000003 at the same module/offset; the exception alone does not locate a certificate problem or source line. A dump/stack is needed for that investigation.
Save configuration and fault logs, then upgrade through the supported procedure to a compatible version. For a pairing failure limited to one client, remove/re-pair that client through the UI rather than clearing all state. My upgrade to v2025.628.4510 produced 50 minutes without another crash, but later encoder timeouts remained a separate problem.
7. Encoding timeouts
frame 1 encode wait timeout means encoding did not finish within its wait. One occurrence coincided with 3688/4096 MiB used, 92% GPU utilization, and 60 W. On a 4-GiB host, inspect game textures, background applications, and encoder load together.
Start telemetry before streaming:
nvidia-smi --query-gpu=timestamp,name,memory.used,memory.total,utilization.gpu,power.draw --format=csv -l 2Repeat the same game scene while changing one item:
- Reduce textures or other VRAM-heavy settings, retaining the stream resolution/frame rate.
- Exit unused GPU applications, recorders, and overlays; compare memory and encoder latency.
- Lower stream resolution or frame rate to compare encoder load.
- Verify actual NVENC use and compatible driver/Sunshine versions. Resolve initialization/version errors first.
There is no universal safe VRAM percentage. High use and a timeout together do not prove an internal allocation failure. If the process cannot be stopped, retain the error/PID, reboot during an acceptable window, and repeat at lower load.
HAGS and NVENC priority
nvenc_realtime_hags controls the NVENC scheduling priority used while Windows HAGS is enabled. For high-load freezing, compare this option while keeping other settings fixed:
nvenc_realtime_hags = disabledIt does not disable Windows hardware-accelerated GPU scheduling, and reduced priority can trade capture performance under load. Restart Sunshine as required, repeat the same scene, and restore the option if it does not help. Test the Windows HAGS switch separately in Graphics settings with the required reboot, without simultaneously changing drivers/encoding options. See NVENC scheduling.
This laptop still timed out after the Sunshine priority change, so HAGS was not established as its sole cause.
8. Quality and HDR
Use client statistics first. For network drops, reduce bitrate and inspect Wi-Fi. For high decode time, lower client resolution/frame rate or compare codecs. For high server encode latency, revisit GPU load and encoding settings.
Compare one option in the same scene:
| Symptom | First comparison |
|---|---|
| Motion/detail looks smeared | Increase bitrate within network capacity, or lower output load |
| Dark gradients show banding | Actual bit depth, codec, HDR/SDR, display range |
| HDR looks washed out/overexposed | Host/client HDR, display capability, calibration |
| Codec change adds latency | Hardware encoding and Mac hardware decoding |
hevc_mode advertises HEVC capability; setting it to four is not a supported way to force 10-bit 4:4:4, and Main10 does not imply 4:4:4. Keep capability detection automatic and confirm the negotiated format in encoder/client statistics. Higher NVENC presets also cost encoding time: stabilize the session before assuming P7 suits every game. See encoding configuration.
9. Automatic recovery
During September 1–3, my watchdog made eight timeout-related restarts and five separate starts after the service stopped. Automation reduced manual intervention, but those were still failures rather than evidence that the problem vanished.
Diagnose logged errors first. A recovery script should recognize fresh errors, enforce a restart interval, record before/after PIDs, and verify client reconnects. An old timeout still present in a log must not create repeated restarts or an unlimited silent retry loop during a game.
Save Sunshine and Moonlight settings before each change. Respect configuration compatibility when rolling back versions; after pairing, retest Desktop, game video, input, and audio. Judge the result through frame rate, latency, drops, and reconnects during an actual game session. Running is only the first check.
