Black Screen Diagnostic Workflow

When Sunshine, x11vnc, or any display capture tool shows a black screen, use this workflow to determine whether it's a capture/encoding problem or the GPU is genuinely outputting black pixels.

Step 1: Take a hardware screenshot

DISPLAY=:0 xwd -root -out /tmp/screen.xwd
convert /tmp/screen.xwd /tmp/screen.png
ls -la /tmp/screen.png

If the PNG is tiny (~1.3KB regardless of resolution), the framebuffer is all black. Verify with Python:

from PIL import Image
img = Image.open('/tmp/screen.png')
samples = [img.getpixel((x, y)) for y in range(0, img.height, 200)
           for x in range(0, img.width, 200)]
unique = set(samples)
# {0} means completely black — GPU is not rendering

Step 2: If framebuffer is black, check DRM connector state

for c in /sys/class/drm/card*-HDMI-*/; do
    echo "$(basename $c): status=$(cat $c/status) enabled=$(cat $c/enabled) dpms=$(cat $c/dpms)"
done

Normal output:

card1-HDMI-A-1: status=connected enabled=enabled dpms=On

Problem output (DPMS lockup):

card1-HDMI-A-1: status=connected enabled=disabled dpms=Off

Step 3: Cross-check with nvidia-settings

nvidia-settings -q EnabledDisplays -q ConnectedDisplays

Healthy: EnabledDisplays matches ConnectedDisplays bitmask. Locked: EnabledDisplays = 0x00000000 while ConnectedDisplays shows the port.

Step 4: Cross-check X11 state

DISPLAY=:0 xrandr | grep "HDMI-0"
DISPLAY=:0 xset q | grep -i "monitor\|dpms"

X11 may report "Monitor is On" and show modes available even when the kernel connector is disabled. This is a driver-level mismatch — X11's DPMS state doesn't reflect the kernel's actual state.

Resolution

If enabled=disabled and dpms=Off at the kernel level:

xset dpms force on and xrandr --output HDMI-0 --auto will NOT fix it
Writing to /sys/class/drm/card*-HDMI-*/dpms returns Permission denied even as root (NVIDIA driver read-only)
The GPU display controller needs a full power cycle
Only a reboot reliably fixes this

After reboot, X11 authorization is broken (LightDM's Xauthority is invalid for the user). See the main SKILL.md DPMS lockup pitfall for the Xauth merge fix.

If framebuffer is NOT black (screenshot shows desktop)

The problem is in the capture/streaming layer:

Sunshine: check output_name, capture method, hw_cursor
x11vnc: add -noxdamage, use novnc_proxy launcher
noVNC: check UFW allows the port, browser console for WebSocket errors

2.5 KiB Raw Blame History