diff --git a/110_virtual_display_driver_deployment.md b/110_virtual_display_driver_deployment.md new file mode 100644 index 0000000..90a44a9 --- /dev/null +++ b/110_virtual_display_driver_deployment.md @@ -0,0 +1,82 @@ +# 110 — Virtual Display Driver Setup (Windows 11 VM) + +> Status: Planned — not yet executed +> Created: 2026-07-09 +> Purpose: Replace physical dummy HDMI plug with a software virtual display to unlock native 3440×1440 streaming resolution for Moonlight/Sunshine + +--- + +## ⚠️ Context from 2026-07-09 session (read before starting) + +- VM 110's actual reachable IP was found to be **192.168.1.250**, not the documented `192.168.1.227`. Root cause not identified (DHCP lease drift suspected). **Confirm current IP before starting** — `00_index.md` may still show the stale one until corrected. +- Secure Boot was disabled on VM 110 during unrelated troubleshooting (testing a hang that turned out unrelated). **Currently: Secure Boot = Disabled.** Decide whether to re-enable + run `qm enroll-efi-keys 110` before or after this VDD work — unrelated to VDD itself but worth resolving in the same maintenance window. +- The Windows install ISO (`windows11.iso` on `ide2`) may still have higher boot priority than the real disk. Verify `qm config 110` boot order before rebooting the VM for any reason, to avoid landing back in Windows Setup by accident. + +--- + +## Why this is needed + +The physical dummy HDMI plug currently in use has a fixed EDID that doesn't advertise ultrawide timings — Windows can't be forced into 3440×1440 through Display Settings alone because the "monitor" never claims to support it. A virtual display driver reports resolutions defined entirely in software, with no hardware EDID limitation. + +--- + +## Phase 1 — Overview + +1. Install a Virtual Display Driver (VDD) on the Windows 11 VM +2. Configure it for 3440×1440 @ 144Hz (matching the physical ultrawide monitor spec) +3. Point Sunshine's capture source at the virtual display instead of the physical dummy-plug output +4. Physically remove (or leave inert as fallback) the dummy HDMI plug +5. Test Moonlight stream at full native resolution + +--- + +## Phase 2 — Install the Virtual Display Driver + +- [ ] RDP into VM 110 (`192.168.1.250` — confirm current IP first) +- [ ] Download a maintained Virtual Display Driver release — search GitHub for `itsmikethetech virtual-display-driver` (or current actively maintained fork; check release notes for Windows 11 24H2+ compatibility given VM's Windows version) +- [ ] Reconfirm Secure Boot is still off at time of install — some display drivers require unsigned/test-signed mode +- [ ] Run the installer / register the driver per the project's install instructions +- [ ] Reboot the VM if the driver install requires it + +## Phase 3 — Configure resolution + +- [ ] Locate the VDD config file (typically JSON, e.g. `vdd_settings.xml` or similar depending on the fork) +- [ ] Add a custom mode: 3440×1440, 144Hz +- [ ] Restart the VDD service/driver (not necessarily the full VM) to apply +- [ ] Confirm the new virtual display appears in Windows Display Settings and can be set to 3440×1440 + +## Phase 4 — Point Sunshine at the virtual display + +- [ ] Open Sunshine web UI (`https://192.168.1.250:47990` — confirm current IP) +- [ ] Under display/capture configuration, select the virtual display as the capture source instead of the physical GPU output +- [ ] Save and restart the Sunshine service + +## Phase 5 — Remove physical dependency + +- [ ] With the virtual display confirmed working, physically unplug the dummy HDMI adapter from the passthrough GPU (or leave connected as an inert fallback — doesn't need to be removed for this to work, just no longer relied upon) +- [ ] Reboot VM 110 once, fully disconnected from any physical dummy plug, to confirm Windows still boots and streams correctly with only the virtual display present + +## Phase 6 — Test + +- [ ] Connect via Moonlight from CachyOS +- [ ] Set Moonlight resolution to 3440×1440 +- [ ] Confirm image is sharp, not upscaled/blurry +- [ ] Test at 144Hz if bandwidth allows; fall back to 60Hz if streaming quality suffers + +--- + +## Rollback + +If the VDD causes instability (driver conflicts, crashes, Sunshine capture failures): +- [ ] Uninstall the VDD driver +- [ ] Re-plug the physical dummy HDMI adapter +- [ ] Revert Sunshine's capture source back to the physical GPU output + +--- + +## Post-completion + +- [ ] Update this file's Status header to "Completed" with the date +- [ ] Update `homelab-overview.md` VM 110 entry noting virtual display in use +- [ ] Update `00_index.md` if the IP address discrepancy from 2026-07-09 was resolved +- [ ] Move corresponding task to "Recently Completed" in `Tasks.md`