Skip to content

Setting Up Sunshine and Moonlight for 4K HDR Game Streaming in Debian Trixie

This guide explains how to turn your Debian Linux gaming PC into a game streaming server with Sunshine and Moonlight. Unlike a standard installation of Sunshine, you will install a virtual monitor for game streaming. A virtual monitor enables you to stream content in a higher resolution and refresh rate than your computer’s primary display. It also enables HDR support, even if your primary monitor does not support HDR.

Understanding Key Terms

This guide uses the following key terms.

Term Description
Sunshine host A computer, typically a gaming PC, running the Sunshine streaming server.
Moonlight client A streaming device, typically a smart TV or digital media player, running the Moonlight streaming client. The Moonlight streaming client is available from major app stores, including the Apple App Store and Google Play Store.
Virtual monitor A dummy monitor created entirely by software. Sunshine uses the virtual monitor to render games at a higher resolution and refresh rate than your computer’s physical monitor. This guide explains how to create a virtual monitor using Linux kernel configuration settings.
Extended Display Identification Data (EDID) Data sent from a television to the host to communicate display capabilities. When you create a virtual display, you use an EDID metadata file to tell the Linux kernel the capabilities of the virtual monitor.
initramfs.img The initial RAM file system image. It contains files Linux uses to boot the operating system. To create a virtual monitor, you add an EDID metadata file to initramfs.img.
Standard Dynamic Range (SDR) A video standard for displaying brightness and contrast.
High Dynamic Range (HDR) A video standard offering enhanced brightness and contrast compared to SDR. If your Moonlight client supports HDR, you can optionally enable it on the virtual monitor.

Installing Prerequisites

To follow this guide, you must first:

  • Install Debian Trixie.
  • Install the GNOME desktop environment using the Wayland compositor.
  • Install the most recent kernel modules for your graphics card.
  • Install a gaming client. This guide assumes you are using the Steam gaming client in Steam Big Picture mode.
  • Install the Moonlight app on your Moonlight client.
  • Connect your Sunshine host and your Moonlight client to a LAN using a hard-wired Ethernet connection.

Installing Sunshine

Sunshine is the streaming server you install on your gaming computer.

Installing Required Packages

Sunshine requires several packages, which are available from Debian repositories.

To install the prerequisite packages:

  1. Open a terminal window.
  2. Install the packages.
    sudo apt install miniupnpc libayatana-appindicator3-1

Downloading and Installing the Sunshine Package

To install Sunshine:

  1. Open https://github.com/LizardByte/Sunshine/releases/ in a browser.
  2. Click the latest release, then download the sunshine-debian-trixie-amd64.deb file.
  3. Install the sunshine-debian-trixie-amd64.deb file.
    sudo dpkg -i ~/Downloads/sunshine-debian-trixie-amd64.deb

Running Sunshine

To run Sunshine:

  1. Grant Sunshine the ability to capture data from Wayland.
    sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))
  2. Run Sunshine.
    sunshine
  3. Open https://localhost:47990/ in a browser.
  4. Set the administrative username and password.
  5. Log in to Sunshine.

Configuring Sunshine

To configure Sunshine:

  1. Select the Configuration tab, then select the Advanced tab.
  2. Set Force a Specific Capture Method to KMS.
  3. Click Save, then click Apply.
  4. Select the Audio/Video tab.
  5. Set the following options:
    • Display Id or config.output_name_unix: Set to 0.
    • Maximum Bitrate: Set to 0.
  6. Click Save, then click Apply.

Installing a Virtual Monitor

By default, you are limited to streaming using the resolution, refresh rate, and features supported by your PC monitor. If your television can use a higher resolution or refresh rate or use additional features, you can configure a virtual monitor. The virtual monitor enables you to render and stream content that matches your Moonlight client’s capabilities.

Downloading EDID Data

You create a virtual monitor by downloading Extended Display Identification Data (EDID) firmware matching the capabilities of your Moonlight client. The EDID firmware tells your Sunshine host the capabilities of the virtual monitor.

To download EDID firmware:

  1. Open https://git.linuxtv.org/v4l-utils.git/tree/utils/edid-decode/data/ in a browser.
  2. Select and download a firmware file for a television with the same features as your Moonlight client. To download the file, click plain in the row of the file.
    For example, if your television supports 4K@120Hz HDR10, download firmware for a television with the same specifications.

Adding Firmware to the Initial Ramdisk

To create the virtual monitor, you must load the EDID firmware into the initial ramdisk (initramfs.img) at the earliest point in the Linux boot process.

To add the firmware file to the initramfs.img file:

  1. Move the EDID firmware file you downloaded in the previous section to the /usr/lib/firmware folder and add the .bin file extension. Replace firmware-file with the name of the EDID file you downloaded.
    sudo mv ~/Downloads/firmware-file /usr/lib/firmware/firmware-file.bin
  2. Create a new hook script for initramfs-tools.
    sudo nano /etc/initramfs-tools/hooks/addEDID-Sunshine.sh
  3. Enter the following script into the file. Replace firmware-file with the name of the EDID file you downloaded. 
    #!/bin/sh
# Copy local EDID monitor description data

PREREQ=""
prereqs()
{
    echo "$PREREQ"
}

case $1 in
prereqs)
    prereqs
    exit 0
    ;;
esac

. /usr/share/initramfs-tools/hook-functions

# Begin real processing below this line

EDID_DATA="/usr/lib/firmware/firmware-file.bin"

if [ ! -f "$EDID_DATA" ]; then
    exit 0
fi

add_firmware "$(basename $EDID_DATA)"

exit 0
  4. Press Ctrl + X, press Y, then press Enter to save the file and close Nano.
  5. Grant the execute permission to the new hook script.
    sudo chmod +x /etc/initramfs-tools/hooks/addEDID-Sunshine.sh
  6. Regenerate the initramfs.img file.
    sudo update-initramfs -u -v

Creating the Virtual Monitor

You create the virtual monitor during system boot by passing instructions to the Linux kernel. To create the virtual monitor:

  1. Identify a free HDMI port.
    for p in /sys/class/drm/*/status; do con=${p%/status}; echo -n "${con#*/card?-}: "; cat $p; done
  2. Pick a disconnected HDMI port and note the identifier.
  3. Open your default GRUB configuration file. 
    sudo nano /etc/default/grub
  4. Find the line starting with GRUB_CMDLINE_LINUX_DEFAULT, then enter the following inside the quotation marks after any existing text. Replace HDMI-identifier with the identifier from step 2. Replace firmware-file with the EDID file you downloaded. 
    drm.edid_firmware=HDMI-identifier:firmware-file.bin video=HDMI-identifier:e
  5. Press Ctrl + X, press Y, then press Enter to save the file.
  6. Regenerate your GRUB configuration.
    sudo update-grub
  7. Reboot your computer. 
    sudo reboot

When you reboot your computer, GNOME might default to the virtual monitor, making the login and desktop screens inaccessible. To resolve this issue:

  1. Press Enter, enter your password, then press Enter.
  2. Right-click on the desktop, then select Display Settings.
  3. Select the virtual monitor from the list of displays.
  4. Turn off the toggle next to the display name.
  5. Click Apply.
  6. When prompted, click Keep Changes.
  7. Close the GNOME Control Center window.

Configuring the Monitor in Sunshine

To configure the monitor in Sunshine, you can create a script to automatically switch the primary monitor whenever you start or end a streaming session. When you start a streaming session, the script enables the virtual monitor and disables your PC monitor. When you end a streaming session, the script disables the virtual monitor and re-enables your PC monitor.

Creating the Monitor Script

To create the script:

  1. Get the name of your PC monitor and virtual monitor. 
    gdctl show
  2. Create the script file. 
    nano ~/.config/sunshine/setMoonlightMonitor.sh
  3. To stream in SDR mode, use the following script. Replace pc-monitor and virtual-monitor with the values identified in step 1.
    #!/bin/bash

# Set primary monitor to virtual monitor for Moonlight streaming
if [[ $1 == "start" ]]; then
    gdctl set --logical-monitor --primary --monitor virtual-monitor --color-mode default --x 0 --y 0 --scale 0 --transform normal

# Set primary monitor to physical monitor after streaming. 
elif [[ $1 == "stop" ]]; then
    gdctl set --logical-monitor --primary --monitor pc-monitor --x 0 --y 0 --scale 0 --transform normal
fi

  4. To stream in HDR mode, use the following script. Replace pc-monitor and virtual-monitor with the values identified in step 1.

    #!/bin/bash

# Set primary monitor to virtual monitor for Moonlight streaming
if [[ $1 == "start" ]]; then
    gdctl set --logical-monitor --primary --monitor virtual-monitor --color-mode bt2100 --x 0 --y 0 --scale 0 --transform normal

# Set primary monitor to physical monitor after streaming. 
elif [[ $1 == "stop" ]]; then
    gdctl set --logical-monitor --primary --monitor pc-monitor --x 0 --y 0 --scale 0 --transform normal
fi

    Note

    The above scripts assume you use one monitor. If you use multiple monitors, add additional gdctl lines to the stop section for each monitor. Only set the --primary flag for your primary monitor.

  5. Press Ctrl + X, press Y, then press Enter to save the script and exit Nano.

  6. Grant the executable permission to the script file.
    chmod +x ~/.config/sunshine/setMoonlightMonitor.sh

Enabling the Monitor Script in Sunshine

To configure Sunshine to use the monitor script:

  1. Run Sunshine if it is not already running.
    sunshine
  2. Open https://localhost:47990/ in a browser.
  3. Log in to Sunshine.
  4. Select the Applications tab.
  5. Click Edit for an application. If you use Steam Big Picture mode, edit the Steam Big Picture application.
  6. If there are no commands, click Add Commands. Otherwise, click the green + icon to add a new set of commands.
  7. Enter the script in the Do Command field. Replace user with your username. 
    /home/user/.config/sunshine/setMoonlightMonitor.sh start
  8. Enter the script in the Undo Command field. Replace user with your username.
    /home/user/.config/sunshine/setMoonlightMonitor.sh stop
  9. Click Save.

Setting Up Moonlight

Moonlight is the streaming client that runs on your streaming device. Moonlight is available from major app stores, including the Apple App Store and Google Play Store. Before continuing, ensure you have installed Moonlight.

Note

These steps assume you installed Moonlight on an Android TV device. The steps may differ for other streaming devices.

Configuring Moonlight

To configure Moonlight:

  1. Run the Moonlight app.
  2. Select the Settings icon.
  3. Set the following options:
    • Video resolution: Select your Moonlight client's resolution.
    • Video frame rate: Select your Moonlight client's frame rate.
    • Video bitrate: Select 150 Mbps.
    • Enable HDR (Experimental): Select this option only if you enabled HDR mode on the virtual monitor.
  4. Return to the main menu.

Pairing Your Sunshine Host to Moonlight

To pair your Sunshine host to Moonlight:

  1. On your Sunshine host, run Sunshine if it is not already running. 
    sunshine
  2. On your Moonlight client, run the Moonlight app.
  3. Select your Sunshine host.
    A PIN displays on the screen.
  4. On your Sunshine host, open https://localhost:47990/ in a browser.
  5. Log in to Sunshine.
  6. Select the PIN tab.
  7. Enter the PIN displayed on your Moonlight client, enter a Device Name, then click Send.
    Moonlight pairs to your Sunshine host. You can now stream programs.

Testing the Configuration

To test the configuration:

  1. Run Sunshine if it is not already running.
    sunshine
  2. Run the Moonlight app.
  3. From Moonlight, select your Sunshine host, then launch Steam Big Picture.
    Your primary monitor shuts off and the television streams content at the correct resolution.

Deactivating the Virtual Monitor

You can deactivate the virtual monitor in both your GNOME user session and the GNOME Display Manager (GDM) login session. This prevents applications and the login screen from opening on the wrong monitor or with incorrect settings when you are not using Sunshine.

Deactivating the Virtual Monitor in Your GNOME User Session

To deactivate the virtual monitor for your user session:

  1. Run the monitor script with the stop flag.
    ~/.config/sunshine/setMoonlightMonitor.sh stop
  2. Open the GNOME Control Center. 
    gnome-control-center
  3. Select Displays from the navigation pane.
  4. Select the virtual monitor from the list of displays.
  5. Turn off the toggle next to the display name.
  6. Click Apply.
  7. When prompted, click Keep Changes.
  8. Close the GNOME Control Center window.

GNOME no longer uses the virtual monitor when you are not streaming.

Deactivating the Virtual Monitor in Your GDM Login Session

To deactivate the virtual monitor in your GDM login session:

  1. Copy the Wayland monitor configuration to the GDM configuration folder.
    sudo cp ~/.config/monitors.xml /var/lib/gdm3/.config/monitors.xml
  2. Grant the GDM user access to the copied monitors.xml file.
    sudo chown Debian-gdm:Debian-gdm /var/lib/gdm3/.config/monitors.xml
  3. Reboot your computer.
    sudo reboot
    The computer reboots.

The login prompt now displays correctly on your primary monitor.