Spendlik/Claude_Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
Claude_Homelab/110_virtual_display_driver_deployment.md

4.4 KiB
Raw Permalink Blame History

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