initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,82 @@
+# 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