Note: This guide is written before this PR is merged upstream. In the future, it's likely that most of this will be managed automatically by the Recalbox-Moonlight integration. However, the Sunshine configuration is still up to you, the user.
- Your computer runs Windows. For a computer running GNU/Linux, the virtual display configuration might be similar but I am not going to cover it.
- Your Recalbox and PC are in the same LAN. We won't cover Moonlight-over-the-Internet, it's not the point.
- You're administrator of your Windows PC (you need to be able to setup a Windows driver)
- Your Recalbox is accessible with hostname
recalbox.local(should be the default). - Your CRT is a 4:3 TV (not 16:9) that supports 60 Hz RGB. Thus, the resolution will be 640x480 and the streaming target will be 60 fps (120 fps is also feasible and may give you smoother renders). We will configure for RGB 60 Hz and 50 Hz. If you decide to display it as composite, it will work as well (might be useful for some EGA games like Maniac Mansion)
- Sunshine, the Moonlight server - this exposes your apps
- Virtual Display Driver Control - this lets you create a virtual display and configure its resolutions.
- Install Sunshine by following the docs. Then, connect to the Sunshine control panel using your web browser (right click on the tray icon for Sunshine and click "Open Sunshine")
- Decompress Virtual Display Driver control somewhere on your drive (not a temporary location). I will assume
C:\Progs\VirtualDisplayDriverControl\is your chosen path.
- Launch
VDD Control.exe. It will requests elevated privileges (accept) before opening its GUI. - Navigate to Tools -> XML Editor.
- Do not change anything in "General Settings".
- In "Refresh Rates", delete every entry. This will remove all "default refresh rates" which are not helpful.
- In "Resolutions", add the following entries (width x height @ refresh rate):
- 640 x 480 @ 60
- 768 x 576 @ 50
- 640 x 480 @ 120
- 768 x 576 @ 100
- Click on "Save Changes". You will get a message indicating that the config has been saved, and then a warning that you may safely ignore by clicking Yes
Note: if you output on a monitor with different specs, feel free to set instead the relevant resolutions. Likewise, if you use the monitor in a tate setup, feel free to add vertical resolutions as well. The important thing is to provide the native refresh rates and the x 2 refresh rate. However, this cannot go beyond 120 Hz, this is the hard limit of Moonlight and Sunshine.
- Open the Display settings (where you usually are able to set the resolution and refresh rate for your regular monitor).
- Click "Install Driver" in VDD Control. Your screen may go dark for a second, and a new display will appear in the Display settings (you may need to re-open it).
- If you have already installed the driver before, you may find yourself with 2 virtual displays. See the Troubleshooting section to handle that
- If you update the VDD config again, you may click "Restart Driver" to take the new config in account.
I think recent versions of Windows have ssh.exe installed by default. Check this by running in a console (Terminal in the start menu or cmd.exe) ssh -V. If it gives you an error, you don't have the ssh client and you may download PuTTY or Kitty. I will not cover that.
- Navigate to the Recalbox control panel and under the Services section, ensure the SSH protocol is enabled. If you can't access that control panel, don't panic. Using your controller, press start to open the Recalbox OSD, go to Advanced settings, and enable "Web manager". You may need to reboot, and then you'll have SSH access
Note: as of now, this step is done manually. In the future, it might be obsoleted and handled automatically. In particular, we may be able to automatically inject the desired resolution into Moonlight configuration (but this requires a patch in upstream Moonlight).
Note 2: this step may need to be repeated at each system update.
Using the SSH client of your computer, open a shell to your recalbox (not covered by this guide).
Then, use the following commands. We will explain them one after the other.
Note: the # sign indicates a comment. Anything after a pound sign is not interpreted as a shell instruction
# this lets people not familiar with the best editor in the world, vi, edit files. Other people will use export EDITOR=vim </troll>:
export EDITOR=nano
# this lets us edit system-protected recalbox files, necessary to adjust the config:
mount -o remount,rw /
# this opens the template for moonlight configs to let you edit it
$EDITOR /recalbox/share_init/system/configs/moonlight/moonlight.confYou then find yourself in a text editor. Using the arrows of your keyboard, change the lines that look like
width = 1280
height = 720
fps = 60
to be instead
width = 640
height = 480
fps = 120
Note: if you want to use a 50Hz TV, or a VGA screen with a different resolution, set the right entries there.
Warning: importantly, you cannot (as of the current state of the code) add
# commentsat the end of each line. Instead, ensure each of these lines starts strictly with the config directive (width, height, fps), then the sequence " = ", then the value, then immediately, a newline (press Enter). (the code change referenced at the beginning of this document addresses this).
Then, save and quit the text editor. To exit nano, press "Ctrl+x" (this is what ^X means, ^ is the traditional designation of the control key in the Unix world). When it asks you to save, press "y" (as in "yes"), then enter to confirm the file name.
note for translators: the commands in Nano will always be in English I suppose.
It's now time to prepare for the reboot of your Recalbox. Follow these instructions, in the SSH terminal again:
# This puts the system files in read-only mode again to prevent their
mount -o remount,ro /
# This leaves the SSH environment:
exitIf you want to avoid leaving the SSH access open, navigate back to the Web UI and disable the service, and then proceed to reboot the Recalbox using any means you desire (press Start -> Quit -> Restart Recalbox, or use the Web UI to do the same). This ensures the configs are persisted and everything is reloaded.
Restart Sunshine (right click on the Sunshine tray icon, click "Restart"). Then, connect to the Web UI again, and navigate to the Troubleshooting tab (rightmost). Under the logs section you will see a bunch of text. Near the top you should see something like
[2026-07-20 16:41:45.882]: Info: Currently available display devices:
[
// [...]
{
"device_id": "{303774d3-836f-50df-81e9-f9341094d630}",
"display_name": "\\\\.\\DISPLAY6",
"edid": {
"manufacturer_id": "MTT",
"product_code": "1337",
"serial_number": 518463207
},
"friendly_name": "VDD by MTT",
"info": {
"hdr_state": null,
"origin_point": {
"x": -768,
"y": -8
},
"primary": false,
"refresh_rate": {
"type": "rational",
"value": {
"denominator": 1,
"numerator": 50
}
},
"resolution": {
"height": 576,
"width": 768
},
"resolution_scale": {
"type": "rational",
"value": {
"denominator": 100,
"numerator": 100
}
}
}
},
]
Look for the one that matches "VDD by MTT". A few lines before that text "VDD by MTT", there will be a unique identifier following the format {303774d3-836f-50df-81e9-f9341094d630} (8 hex characters 0-9 + a-f, then 3 times 4 hex characters, then 12 hex characters, separated by hyphens, surrounded by { braces }. Copy that string. It's the unique identifier of your target virtual screen.
Note: If you cannot find that screen , perhaps you need to activate the display. To do that, open the Settings app, click the new display that appears, and select the option "Extend desktop to this display". Be mindful that if you lose your mouse pointer, it may be hiding on that virtual display that has no output until Recalbox is configured.
In the Sunshine Web UI navigate to the Configuration tab (second one from the right). Then click on the "Audio/Video" tab (third one).
Follow these simple steps.
Under "Display Id", paste the ID you found in the previous step.
Note: if you have to reinstall the virtual display driver for whatever reason at some point, this ID may change. In that case, you just have to update this ID and the rest can remain identical
Click the drawer "Advanced display device options". This reveals a set of options. Set them as follows:
- Device configuration: "Verify that display is enabled". We recommend leaving it enabled because otherwise some apps like Big Picture fail to attach to it. Disable it manually when you're not using it to avoid losing apps on that virtual display.
- Resolution: importantly, set "Use resolution provided by the client (default)". This lets Recalbox set the adequate resolution, provided you configured it in VDD Control.
- Refresh rate: "Use FPS value provided by the client". (likewise)
- HDR: "Switch on/off...". (likewise, although it's doubtful your CRT is capable of rendering the HDR gamut)
- Leave unchecked "Config revert on disconnect"
Save the config. Sunshine will ask to be restarted, accept it.
Follow the general guide for Moonlight on Recalbox.
Start one of your apps. The resolution should be fine.
Open the Device Manager app (Execute aka. Win+R -> devmgmt.msc, navigate to Display Adapters, right-click on Virtual Display Driver, and click Uninstall device. Confirm. I recommend you do this on all entries of "Virtual Display Driver" because they are not especially well-ordered so it's safer to remove them all and to redo the config in Sunshine afterwards.
Open the Device Manager (see previous entry), right click on Virtual Display Driver, click "Disable device", wait a few seconds, then right-click again and "Enable device". Things should be fine again. If it malfunctions, uninstall using the previous entry's guidance and start over.
It can happen when reloading the config or if there's a glitch. In general, just restarting the driver, and then the app (you may have to kill it first), fixes the issue. If not, reboot. If not, uninstall the driver and start over. You will have to reconfigure Sunshine a bit after that (just 1 entry).
You may have previously setup Moonlight and so the pre-existing configs do not use the adjusted resolution.
In that case, clean the configs using /recalbox/scripts/moonlight/Moonlight.sh clean <host> and re-init them.
Verify in the Display settings of Windows that the resolution set for your screen matches what you requested.
Head over to Discord and ask around. Be thorough in your description.