ray
83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|