sunshine-res

sunshine-res is a small command‑line utility that automatically adjusts your display resolution and HDR settings to match a target resolution that your game or application expects. It works on modern Linux desktop environments that expose a standard way to query and set display modes.

Installation

You can install sunshine-res system‑wide (or inside a virtualenv) with:

pipx install sunshine-res

The tool installs a console script called sunshine-res that can be invoked from anywhere.

Usage

The utility accepts three commands:

Configuring Sunshine

After installing sunshine-res, you must configure Sunshine to use the utility.

1. Open Sunshine and go to the Configuration tab (probably https://localhost:47990/config)
2. In the Command Preparations section, click "+ Add" to add a new command
3. Set the do and undo commands to sunshine-res do and sunshine-res undo respectively
4. Save

Multiple outputs

Sunshine-res will only manage the resolution of a single display output. By default, it will use the first one present reported by the relevant control tool. This is probably fine for many users, but if you have multiple displays and require specifying a particular display, you can append --target-output/-o followed by the display name reported by the appropriate command line tool for your desktop environment.

Eg.

sunshine-res --target-output HDMI-2 auto

If you are unsure of what output name to use, look at the outputs listed by the appropriate tool for your desktop environement, in the Supported Desktop Environments table.

Supersampling

Rather than having the server match the client resolution exactly, a supersampling factor can be added to instruct the server to render higher resolution images than your client and allow the client to downscale them.

This can be done by adding the --supersample option to the sunshine-res command.

Eg.

sunshine-res --supersample 1.5 auto

This would attempt to render at 1.5× the target resolution, so if the target is 1920×1080, the server would render at the nearest resolution at or greater than 2880×1620 and the client would downscale to 1920×1080. Since the client may not support arbitrary resolutions, the server will choose the closest available mode that is at least as large as the supersampled resolution.

Example

# Set resolution to 1920×1080 @ 60 Hz, HDR disabled
SUNSHINE_CLIENT_WIDTH=1920 SUNSHINE_CLIENT_HEIGHT=1080 SUNSHINE_CLIENT_FPS=60 SUNSHINE_CLIENT_HDR=false sunshine-res do

# Revert to original resolution
sunshine-res undo

# Toggle
sunshine-res

Environment variables are optional and typically set by Sunshine; defaults are:

• SUNSHINE_CLIENT_WIDTH – 1920
• SUNSHINE_CLIENT_HEIGHT – 1080
• SUNSHINE_CLIENT_FPS – 60
• SUNSHINE_CLIENT_HDR – false

Supported Desktop Environments

The tool automatically detects the current desktop by inspecting the XDG_CURRENT_DESKTOP, XDG_SESSION_DESKTOP, or SESSION_DESKTOP environment variables. If no supported desktop is detected, the command will exit with an error.

How It Works

1. Detect Desktop – The first step is to determine whether you are running KDE or Cosmic.
2. Query Current Mode – The relevant command (eg. kscreen-doctor or cosmic-randr) returns a description of the current monitor configuration.
3. Find Matching Mode – The tool searches the available modes for one that matches the target resolution and has the closest refresh rate that is not below the requested SUNSHINE_CLIENT_FPS.
4. Apply Mode – The chosen mode is applied with the same HDR setting you requested.
5. Persist State – The original monitor state is written to ~/.config/sunshine/last_mode.json so that undo can restore it later.

Common Errors & Troubleshooting

If you encounter an unhandled exception, try running the command with the -v flag (if implemented) or inspect the stack trace. The project is open source, so feel free to file an issue.