Add reproducible headless desktop for the X11/NVENC capture path
A Moonlight client connecting to the x11-backend host got a black screen even though pairing, NVENC, and input injection all worked: the headless Xorg on :0 had no window manager rendering on it, so capture=x11 grabbed an empty black root window. (The wlr/kms backends don't hit this — their capture source renders for itself.) This was a hand-built path with nothing in the repo to reproduce the desktop piece. Now: - files/headless-desktop.service: Openbox session on :0, bound to xorg-headless.service, enabled via default.target for lingering boots, with a best-effort xsetroot so the desktop is visibly non-black. - lib/headless.sh: capture_backend_is_x11 + install_headless_desktop (idempotent; pulls openbox/xsetroot via the distro dispatch). - install.sh: installs the desktop unit when capture=x11 is detected. - status.sh: x11 branch now FAILs if no window manager is on :0 instead of only checking the X server answers — the gap that hid this failure. - docs: TROUBLESHOOTING §13 black-screen lesson; FOLLOWUPS P3 updated. Part of the P3 x11-backend work; --backend flag, config.sh x11 variant, and xorg-headless templates remain outstanding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -478,6 +478,29 @@ systemctl --user show $UNIT -p Environment -p Requires -p After
|
||||
# should show DISPLAY=:0 + XDG_SESSION_TYPE=x11, xorg-headless.service, no wayland/sway
|
||||
```
|
||||
|
||||
**Gotcha: black screen in Moonlight even though everything "works".** Pairing
|
||||
succeeds, NVENC loads, mouse/keyboard input reaches the host — but the client
|
||||
sees only black. Cause: the headless Xorg on `:0` is up, but **nothing is
|
||||
rendering on it**. Unlike the wlr path (where the compositor *is* the desktop),
|
||||
a bare Xorg server draws nothing on its own, so `capture = x11` grabs an empty
|
||||
black root window. Confirm with:
|
||||
|
||||
```bash
|
||||
DISPLAY=:0 xlsclients # only 'sunshine' = no WM/desktop
|
||||
DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK # 'not found' = no window manager
|
||||
```
|
||||
|
||||
Fix: run a window manager on `:0`. The installer ships a `headless-desktop.service`
|
||||
(Openbox) for exactly this and enables it whenever it detects `capture = x11`:
|
||||
|
||||
```bash
|
||||
systemctl --user enable --now headless-desktop.service
|
||||
DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK # now reports a 'window id'
|
||||
```
|
||||
|
||||
`status.sh` checks for this directly: with `capture = x11` it now FAILs if no
|
||||
window manager is present on `:0`, instead of only verifying the X server answers.
|
||||
|
||||
---
|
||||
|
||||
## Custom keybinding to escape Moonlight (Mac)
|
||||
|
||||
Reference in New Issue
Block a user