Streaming
The Hyper-V console only shows the basic Hyper-V display, not what the GPU draws. To see the VM with the GPU, GpuVM installs a streaming server inside the VM and opens it with a client on the host.
Components
Section titled “Components”| Component | Where | Role | Pinned version |
|---|---|---|---|
| Sunshine | VM | Captures the virtual display and encodes with NVENC. | v2026.914.233613 |
| Virtual Display Driver | VM | A monitor drawn by the GPU. | 25.7.23 |
| nefcon | VM | Command-line driver installer; creates the virtual display device. | v1.14.0 |
| usbip-win2 | VM | Plugs in GpuVM’s USB speaker, which Sunshine captures. | 0.9.8.0 |
| ViGEmBus | VM | Virtual gamepad bus: Sunshine creates on it the controllers Moonlight forwards. | v1.22.0 |
| Moonlight | Host | Shows the VM. | Installed separately |
The installers are downloaded on the host when the VM is created, verified against the SHA-256 pinned in streaming/components.json and copied to the VM’s disk. The guest downloads nothing. They are kept in a cache folder (in %ProgramData%\GpuVM when installed).
nefcon is pinned to v1.14.0, the version the official VDD install script uses, even though v1.21.0 exists. ViGEmBus 1.22.0 is its last release (the project is archived); it is installed the first time a VM opens.
Sunshine
Section titled “Sunshine”Sunshine runs inside the VM. Its username and password are generated when the VM is created; on the host they are stored encrypted with DPAPI. The password travels in plain text to the guest only for the install and is deleted afterwards.
Each time you start and open a VM, GpuVM reads Sunshine’s display list through its API, sets output_name to the virtual display and restarts Sunshine if that changed, so it never captures the Hyper-V display by mistake. When GpuVM has already turned the Hyper-V display off, it also sets dd_configuration_option to disabled: if Sunshine changes the display on every session, it re-tests all its encoders and the first frame takes 22 to 27 s instead of about 2 s (lab 008). Changing the resolution or FPS still costs 10 to 15 s, because Sunshine sees the display change; GpuVM sets the display before the rest of the work and restarts Sunshine right away, so that time overlaps with it. Otherwise it uses ensure_only_display.
Work inside the VM that lasts until Windows restarts (display mode, capture mode, audio) is done once per boot, through one PowerShell Direct session, and Windows readiness is read from Hyper-V’s heartbeat. Opening a VM that is already on takes about 7 to 10 s until the first frame; from off, about 55 s to the picture, mostly Windows booting and Sunshine starting (it tests its encoders before its API answers). connect returns only when Moonlight shows the first frame, and when the VM is already open in Moonlight it brings that window to the front instead of opening another.
Capture modes
Section titled “Capture modes”Sunshine can capture the virtual display in two ways, chosen per machine in Picture and control → Capture or with Set-GpuVMCapture -Name <vm> -Mode wgc|ddx:
| Mode | In the app | How Sunshine runs | Shows | Doesn’t show |
|---|---|---|---|---|
wgc (Windows.Graphics.Capture) |
Fast (the default) | In the signed-in user’s session, started by a logon task (conhost --headless, so no console window); the service is set to manual. |
The picture about 2.6 s after connecting, and programs in exclusive fullscreen at any resolution. | Windows’ administrator prompts (they are drawn on the secure desktop); GpuVM shows and answers them. |
ddx (desktop duplication) |
Classic | As a Windows service (SYSTEM). | Everything, including Windows’ administrator prompts. | Programs in exclusive fullscreen: black. After connecting, the picture can stay black until something on screen changes. |
With ddx, desktop duplication restarts silently at the start of each session, so the picture can stay black for a while after Moonlight connects (its first real frame takes about 6 s even when the whole screen changes), and it gets no new frames from the virtual display while a program is in exclusive fullscreen. The mode is applied right away if the VM is running and checked on every Start and open; when it’s already set, Sunshine isn’t restarted. Applying it needs the guest password. VMs that never chose a mode use wgc.
Administrator prompts
Section titled “Administrator prompts”With wgc, Windows’ administrator prompts (UAC) can’t be streamed, and the Hyper-V console can’t show them either: it doesn’t see the GPU display. GpuVM brings them to the host instead:
- Watcher in the VM. On the first open, GpuVM installs
guest/admin-prompt.ps1inC:\Program Files\GpuVM\AdminPrompt(only administrators can change it) as theGpuVM-AdminPrompttask, which runs as SYSTEM from boot. When a prompt opens, it reads the program and publisher and publishes them through Hyper-V’s data exchange (KVP); when it closes, it publishes that too. - Card on the host. The app reads that data every 2 s (
Get-GpuVMAdminPrompt, about 100 ms, no PowerShell Direct) and shows an always-on-top card with the program, the publisher, Allow and Deny. A prompt shows on the host about a second after it opens. - Answer.
Resolve-GpuVMAdminPromptgoes through PowerShell Direct with the guest password; the script starts a one-time helper as SYSTEM on the secure desktop of the console session, which presses Yes or No with UI Automation, only if the prompt open is still the one shown. An answer takes about 5 s.
Only the host can order an answer: nothing in the VM can approve a prompt for itself, and a prompt that changed in the meantime is never answered.
Virtual display
Section titled “Virtual display”The Virtual Display Driver adds a monitor drawn by the GPU. It is installed with nefcon, and only the certificate that signed the driver is trusted.
- After the first boot the VM restarts once on its own to leave the virtual display as its only display.
- If the virtual display works, the Hyper-V display is turned off so Windows and Sunshine use the virtual one (
disableHyperVVideoin the profile). - On every Start and open, with the guest password saved, the virtual display is kept as the only and primary display of the VM. GPU-P VMs get an extra hidden 1024×768 output of the shared GPU; if it became the primary one, new windows (Steam, installers) would open where the stream doesn’t show them. When it’s already set, nothing is changed, so Sunshine doesn’t re-test its encoders.
- If something fails, the VM is still reachable over Remote Desktop.
Moonlight
Section titled “Moonlight”Moonlight on the host shows the VM. Pairing is automatic: Moonlight generates the PIN and GpuVM hands it to Sunshine through its API. The paired client is this PC’s name.
- To pair again: Pair Moonlight again in the machine’s ⋯ menu, or
./gpuvm.ps1 connect -Name <vm> -Pair. - The resolution, frame rate, V-Sync, frame pacing, mouse, codec and bitrate are set in the machine’s Picture and control section (or with
Set-GpuVMStreamingClient), or per connection:
./gpuvm.ps1 connect -Name win11 -Resolution 2560x1440 -Fps 120 -BitrateKbps 40000 -Codec HEVCCodecs: auto, H.264, HEVC, AV1. Moonlight opens the Desktop app of Sunshine by default.
Frame rate, V-Sync and latency
Section titled “Frame rate, V-Sync and latency”An FPS of 0 (Monitor in the app) means the refresh rate of the host monitor Moonlight opens on, read every time the VM opens. When the VM’s virtual display lacks that rate, GpuVM adds it to the display’s modes, so the VM draws exactly one frame per monitor refresh. At the monitor’s own rate V-Sync adds no latency, so the picture never tears without giving anything up, and stutters halve compared with a rate that doesn’t match the monitor.
From a key, click, mouse move or gamepad button on the host to the change in Moonlight’s picture takes about 16.6 ms (median) at 120 FPS or more; the same PC without streaming takes 5.6 ms, so the stream adds about 11 ms. At 60 FPS it adds one more host frame. Codec and window mode don’t change the median. Frame pacing gives the most even motion at 60 FPS; at 120 FPS and above it adds stutters, so only the Movies and video use turns it on.
Gamepads
Section titled “Gamepads”Moonlight forwards the controllers connected to the host, and Sunshine creates them inside the VM on ViGEmBus, so Windows in the VM sees an Xbox 360 controller. GpuVM downloads the driver on the host, checks its SHA-256, copies it into the VM and installs it the first time the VM opens; Sunshine restarts to see it. A button press reaches Moonlight’s picture in about 17 ms.
Hyper-V Generation 2 VMs have no sound card. GpuVM gives the VM its own USB speaker: a small server inside the VM (GpuVMAudio.exe) presents itself as a USB audio device (48 kHz, stereo), usbip-win2 plugs it in, and Windows drives it with its built-in USB audio driver as if it were real hardware. It shows up as Speakers (GpuVM Audio) and Sunshine captures it (virtual_sink).
- Nothing leaves the VM: the server listens on
127.0.0.1only, runs asLOCAL SERVICEand its program lives inC:\Program Files\GpuVM\Audio, where only administrators can write. - usbip-win2 installs only its client, silently. Its drivers are signed by Microsoft: no test mode, no certificate of its own. GpuVM checks both and uninstalls it if either fails.
- The speaker is persistent: usbip-win2 plugs it in again every time Windows starts, so no restart or sign-in is needed. Start and open checks it in the background on the first open after each boot, plugs it in again if it was lost and updates the server when GpuVM brings a new one.
- VMs created with VB-CABLE move to the speaker the next time they are opened. VB-CABLE’s output is silent to Sunshine inside a VM, so the earlier sound came from Steam Streaming Speakers (labs 011 and 012).
Profile settings
Section titled “Profile settings”The streaming section of the profile sets the defaults:
"streaming": { "provider": "sunshine", // or "none" to create the VM without streaming "virtualDisplay": true, "disableHyperVVideo": true, "audio": "usb", // or "none" to skip audio "sunshine": { }, // extra keys for sunshine.conf "client": { "app": "Desktop", "resolution": "1920x1080", "fps": 0, "vsync": true, "framePacing": false, "mouse": "capture", "bitrateKbps": 0, "codec": "auto" }}fps is 10–480, or 0 for the host monitor’s refresh rate. vsync and framePacing (true/false) are passed to Moonlight; frame pacing is turned off whenever V-Sync is off, because Moonlight only paces frames with V-Sync. mouse is capture (the VM takes the mouse, for games) or absolute (the pointer moves freely, as in remote desktop). client also accepts performanceOverlay (true/false) and displayMode (fullscreen, windowed, borderless), only passed to Moonlight when the profile defines them. captureSystemKeys (never, fullscreen, always; fullscreen if not set) decides when Alt+F4, Alt+Tab and the Windows key go to the VM; Ctrl+Alt+Shift+Q always quits the stream.
Moonlight is started as the signed-in user, without administrator rights, even though the GpuVM service runs elevated: it talks to a server the VM controls.
Updating components
Section titled “Updating components”./gpuvm.ps1 components-update -WhatIf # see whether newer versions existIt looks up the latest GitHub release of each component and updates version, URL and SHA-256 in streaming/components.json. usbip-win2 stays on 0.9.8.0 and ViGEmBus on its last release, 1.22.0 (hold in the file). A new version isn’t tested: validate it in a lab before creating VMs with it. The app can’t run this command.