Skip to content
luxusAi

Moonlight / Vibeshine Troubleshooting

Moonlight Black Screen Troubleshooting Guide

Section titled “Moonlight Black Screen Troubleshooting Guide”

✅ Server Status Verification

Section titled “✅ Server Status Verification”

The Vibeshine (Sunshine fork) server is working correctly:

  • Status: SUNSHINE_SERVER_FREE (ready for connections)
  • Ports: All required ports are accessible (47984, 47989, 47990, 47998, 48000, 48010)
  • Encoders: NVIDIA H.264, HEVC, and AV1 encoders detected
  • Display: KMS screencasting active on HDMI-A-2 (1920x1080)
  • Network: Server accessible from client machines

🎯 Common Moonlight Black Screen Causes

Section titled “🎯 Common Moonlight Black Screen Causes”

1. Client Configuration Issues

Section titled “1. Client Configuration Issues”

Check Moonlight Settings:

Section titled “Check Moonlight Settings:”
  1. Open Moonlight on your client device
  2. Go to Settings → Streaming
  3. Verify these settings:
    • Resolution: Try 1920x1080 or lower
    • FPS: Start with 30fps, then try 60fps
    • Bitrate: Start with 10 Mbps, increase if needed
    • Codec: Try H.264 first, then HEVC

Network Settings:

Section titled “Network Settings:”
  1. Streaming Quality: Start with “Balanced” or “Smooth”
  2. Hardware Acceleration: Enable if available
  3. Audio: Enable to test if video is the only issue

2. Connection Method

Section titled “2. Connection Method”

Try Different Connection Methods:

Section titled “Try Different Connection Methods:”

  1. LAN Connection (recommended):

    Host: lea (or 192.168.178.71)
    Port: 47989

  2. Manual Pairing:

    • In Moonlight: “Add PC manually”
    • Enter the IP address: 192.168.178.71
    • Complete pairing process

3. Firewall and Network

Section titled “3. Firewall and Network”

Verify Client-Side Firewall:

Section titled “Verify Client-Side Firewall:”
  • Windows: Allow Moonlight through Windows Firewall
  • macOS: Allow Moonlight through macOS Firewall
  • Mobile: Check network permissions

Network Test:

Section titled “Network Test:”
Terminal window
# From your client machine, test connectivity:
ping lea
telnet lea 47989

4. Display and Graphics

Section titled “4. Display and Graphics”

Check Display Configuration:

Section titled “Check Display Configuration:”
  1. Multiple Monitors: If you have multiple monitors, try disconnecting extras
  2. Display Resolution: Ensure the host display is set to 1920x1080
  3. Refresh Rate: Try 60Hz if available

Graphics Driver Issues:

Section titled “Graphics Driver Issues:”
  • Update graphics drivers on client device
  • Disable hardware acceleration in Moonlight temporarily
  • Try different rendering backends in Moonlight

5. Moonlight Client Versions

Section titled “5. Moonlight Client Versions”
Section titled “Recommended Clients:”
  • Desktop: Moonlight Qt (latest version)
  • Mobile: Moonlight from official app stores
  • Web: Try the web client at http://lea:47989

🔧 Step-by-Step Troubleshooting

Section titled “🔧 Step-by-Step Troubleshooting”

Step 1: Basic Connection Test

Section titled “Step 1: Basic Connection Test”
  1. Open a web browser on your client device
  2. Navigate to: http://lea:47989
  3. You should see the Vibeshine web interface
  4. If this works, the server is accessible

Step 2: Pair the Device

Section titled “Step 2: Pair the Device”
  1. In Moonlight, choose “Add PC manually”
  2. Enter: 192.168.178.71
  3. Complete the pairing process
  4. Check the host machine for the pairing PIN

Step 3: Test with Conservative Settings

Section titled “Step 3: Test with Conservative Settings”
  1. In Moonlight settings:
    • Resolution: 1280x720
    • FPS: 30
    • Bitrate: 5 Mbps
    • Codec: H.264
  2. Try connecting with these settings

Step 4: Gradually Increase Quality

Section titled “Step 4: Gradually Increase Quality”
  1. If basic connection works, gradually increase:

Moonlight Black Screen Troubleshooting Guide

Section titled “Moonlight Black Screen Troubleshooting Guide”

✅ Server Status Verification

Section titled “✅ Server Status Verification”

The Vibeshine (Sunshine fork) server is working correctly:

  • Status: SUNSHINE_SERVER_FREE (ready for connections)
  • Ports: All required ports are accessible (47984, 47989, 47990, 47998, 48000, 48010)
  • Encoders: NVIDIA H.264, HEVC, and AV1 encoders detected
  • Display: KMS screencasting active on HDMI-A-2 (1920x1080)
  • Network: Server accessible from client machines

🎯 Common Moonlight Black Screen Causes

Section titled “🎯 Common Moonlight Black Screen Causes”

1. Client Configuration Issues

Section titled “1. Client Configuration Issues”

Check Moonlight Settings:

Section titled “Check Moonlight Settings:”
  1. Open Moonlight on your client device
  2. Go to Settings → Streaming
  3. Verify these settings:
    • Resolution: Try 1920x1080 or lower
    • FPS: Start with 30fps, then try 60fps
    • Bitrate: Start with 10 Mbps, increase if needed
    • Codec: Try H.264 first, then HEVC

Network Settings:

Section titled “Network Settings:”
  1. Streaming Quality: Start with “Balanced” or “Smooth”
  2. Hardware Acceleration: Enable if available
  3. Audio: Enable to test if video is the only issue

2. Connection Method

Section titled “2. Connection Method”

Try Different Connection Methods:

Section titled “Try Different Connection Methods:”

  1. LAN Connection (recommended):

    Host: lea (or 192.168.178.71)
    Port: 47989

  2. Manual Pairing:

    • In Moonlight: “Add PC manually”
    • Enter the IP address: 192.168.178.71
    • Complete pairing process

3. Firewall and Network

Section titled “3. Firewall and Network”

Verify Client-Side Firewall:

Section titled “Verify Client-Side Firewall:”
  • Windows: Allow Moonlight through Windows Firewall
  • macOS: Allow Moonlight through macOS Firewall
  • Mobile: Check network permissions

Network Test:

Section titled “Network Test:”
Terminal window
## From your client machine, test connectivity:
ping lea
telnet lea 47989

4. Display and Graphics

Section titled “4. Display and Graphics”

Check Display Configuration:

Section titled “Check Display Configuration:”
  1. Multiple Monitors: If you have multiple monitors, try disconnecting extras
  2. Display Resolution: Ensure the host display is set to 1920x1080
  3. Refresh Rate: Try 60Hz if available

Graphics Driver Issues:

Section titled “Graphics Driver Issues:”
  • Update graphics drivers on client device
  • Disable hardware acceleration in Moonlight temporarily
  • Try different rendering backends in Moonlight

5. Moonlight Client Versions

Section titled “5. Moonlight Client Versions”
Section titled “Recommended Clients:”
  • Desktop: Moonlight Qt (latest version)
  • Mobile: Moonlight from official app stores
  • Web: Try the web client at http://lea:47989

🔧 Step-by-Step Troubleshooting

Section titled “🔧 Step-by-Step Troubleshooting”

Step 1: Basic Connection Test

Section titled “Step 1: Basic Connection Test”
  1. Open a web browser on your client device
  2. Navigate to: http://lea:47989
  3. You should see the Vibeshine web interface
  4. If this works, the server is accessible

Step 2: Pair the Device

Section titled “Step 2: Pair the Device”
  1. In Moonlight, choose “Add PC manually”
  2. Enter: 192.168.178.71
  3. Complete the pairing process
  4. Check the host machine for the pairing PIN

Step 3: Test with Conservative Settings

Section titled “Step 3: Test with Conservative Settings”
  1. In Moonlight settings:
    • Resolution: 1280x720
    • FPS: 30
    • Bitrate: 5 Mbps
    • Codec: H.264
  2. Try connecting with these settings

Step 4: Gradually Increase Quality

Section titled “Step 4: Gradually Increase Quality”
  1. If basic connection works, gradually increase:
    • Resolution → 1920x1080
    • FPS → 60
    • Bitrate → 20-30 Mbps

Step 5: Try Different Clients

Section titled “Step 5: Try Different Clients”
  1. Web Client: http://lea:47989
  2. Mobile App: If available
  3. Different Desktop Client: Moonlight Qt vs Moonlight PC

🚨 Advanced Troubleshooting

Section titled “🚨 Advanced Troubleshooting”

Check Server Logs in Real-time:

Section titled “Check Server Logs in Real-time:”
Terminal window
ssh lea "tail -f ~/.config/sunshine/sunshine.log"

Then try to connect from Moonlight and watch for errors.

Test Manual Stream:

Section titled “Test Manual Stream:”
Terminal window
## Install VLC on client machine
## Open VLC → File → Open Network Stream
## Enter: rtsp://192.168.178.71:48010

Reset Vibeshine/Sunshine Configuration:

Section titled “Reset Vibeshine/Sunshine Configuration:”
Terminal window
ssh lea "systemctl --user stop sunshine"
ssh lea "rm ~/.config/sunshine/sunshine.conf"
ssh lea "systemctl --user start sunshine"

📋 Server Information (for reference)

Section titled “📋 Server Information (for reference)”
  • Host: lea (192.168.178.71)
  • Package / Service: pkgs/vibeshine (Nonary’s Sunshine fork) — configured via the NixOS services.sunshine option for compatibility (modules/nixos/remote-desktop.nix)
  • Vibeshine Version: (see web UI or sunshine --version)
  • Display: 1920x1080 @ 60Hz
  • GPU: NVIDIA with NVENC encoders
  • Audio: Opus 48kHz stereo
  • State: Ready for connections

🎮 Gaming-Specific Tips

Section titled “🎮 Gaming-Specific Tips”

For Steam Games:

Section titled “For Steam Games:”
  1. Launch Steam on the host first
  2. Start the game in windowed mode initially
  3. Then connect via Moonlight
  4. Switch to fullscreen once connected

For General Applications:

Section titled “For General Applications:”
  1. Minimize CPU-intensive applications on host
  2. Close unnecessary background processes
  3. Ensure host display is active (not sleeping)

📞 If Issues Persist

Section titled “📞 If Issues Persist”
  1. Check Server Logs: Look for connection attempts in ~/.config/sunshine/sunshine.log (Vibeshine uses the same paths for compatibility)
  2. Network Analysis: Use Wireshark to analyze Moonlight traffic
  3. Alternative Clients: Try Parsec or Remote Desktop as alternatives
  4. Hardware Check: Test with a different client device

✅ Expected Working Configuration

Section titled “✅ Expected Working Configuration”

When everything is working, you should see:

  • The server shows “CLIENT CONNECTED” in logs
  • Moonlight displays your Hyprland desktop
  • Audio streams through Moonlight
  • Input (mouse/keyboard) works remotely
  • Frame rate is smooth (30-60 FPS depending on settings)

The server is properly configured - the issue is most likely on the client side or network configuration.## Vibeshine / Sunshine Connection Test Script

Vibeshine is Nonary’s fork of Sunshine, packaged in this repo as pkgs/vibeshine (see modules/nixos/remote-desktop.nix). It is still configured via the NixOS services.sunshine option — and uses the same ~/.config/sunshine/ paths, log file, and Moonlight protocol/ports — for compatibility. References to “Sunshine” below (the binary, log paths, SUNSHINE_SERVER_FREE state string, etc.) apply unchanged to Vibeshine.

Current Status ✅

Section titled “Current Status ✅”
  • Vibeshine Server: Running and responding (Moonlight-compatible)
  • Ports: All ports accessible (47984, 47989, 47990, 47998, 48000, 48010)
  • State: SUNSHINE_SERVER_FREE (ready for connections)
  • Encoders: NVIDIA H.264, HEVC, AV1 working
  • Display: KMS screencasting on 1920x1080

Test Steps

Section titled “Test Steps”

1. Basic Connectivity Test

Section titled “1. Basic Connectivity Test”
Terminal window
## Test from your Mac:
curl -s http://lea:47989/serverinfo
## Should return XML with server info

2. UDP Port Test

Section titled “2. UDP Port Test”
Terminal window
## Test UDP connectivity:
nc -v -u -z lea 47998
nc -v -u -z lea 48000
## Should succeed

3. Moonlight Connection Test

Section titled “3. Moonlight Connection Test”

Method 1: Web Interface

Section titled “Method 1: Web Interface”
  1. Open browser: http://lea:47989
  2. Should see Vibeshine web interface
  3. Click “Pair” to generate PIN
  4. Use PIN in Moonlight

Method 2: Direct Moonlight Connection

Section titled “Method 2: Direct Moonlight Connection”
  1. Open Moonlight
  2. “Add PC manually”
  3. Enter: 192.168.178.71
  4. Complete pairing process

Method 3: Test with VLC (Advanced)

Section titled “Method 3: Test with VLC (Advanced)”
Terminal window
## In VLC, open network stream:
rtsp://192.168.178.71:48010

Troubleshooting Black Screen

Section titled “Troubleshooting Black Screen”

If you get black screen in Moonlight:

Section titled “If you get black screen in Moonlight:”

  1. Check Moonlight Settings:

    • Resolution: Start with 1280x720
    • FPS: 30
    • Bitrate: 5-10 Mbps
    • Codec: H.264

  2. Check Host Display:

    • Make sure the Hyprland desktop is active
    • No screensaver running
    • Display not sleeping

  3. Network Issues:

    • Try wired connection instead of WiFi
    • Check router QoS settings
    • Disable VPN on client

  4. Client Hardware:

    • Update graphics drivers
    • Disable hardware acceleration in Moonlight
    • Try different client device

Debug Information

Section titled “Debug Information”

Server Logs (Real-time):

Section titled “Server Logs (Real-time):”
Terminal window
ssh lea "tail -f ~/.config/sunshine/sunshine.log"

Connection Test:

Section titled “Connection Test:”
Terminal window
## Watch logs while connecting:
ssh lea "tail -f ~/.config/sunshine/sunshine.log" &
## Then try Moonlight connection

Port Status:

Section titled “Port Status:”
Terminal window
ssh lea "sudo ss -tlnp | grep -E '(47984|47989|47990|48010)'"
ssh lea "sudo ss -ulnp | grep -E '(47998|48000)'"

Expected Log Output

Section titled “Expected Log Output”

When connection works, you should see:

[INFO] CLIENT CONNECTED
[INFO] Found display [wayland-0]
[INFO] Resolution: 1920x1080
[INFO] Screencasting with KMS
[INFO] Creating encoder [h264_nvenc]
[INFO] Streaming bitrate is XXXXX

Alternative Solutions

Section titled “Alternative Solutions”

If Moonlight still doesn’t work:

  1. Parsec: Alternative remote desktop
  2. RDP: Built-in Windows remote desktop
  3. VNC: Simple screen sharing
  4. NoMachine: Commercial remote desktop

Current Configuration

Section titled “Current Configuration”
  • Host: lea (192.168.178.71)
  • Display: Hyprland (Wayland) (1920x1080)
  • GPU: NVIDIA with hardware encoding
  • Audio: Opus 48kHz stereo
  • Network: All ports configured and accessible

The server is ready - the issue is likely client-side configuration or network settings.