Skip to content

About

Per-game UI scaling automation for Sunshine/Moonlight streaming. Applies a per-game, per-client scaling profile when a stream starts and restores your desktop settings when it ends.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

StreamScale

English | 简体中文

Per-game UI scaling automation for Sunshine + Moonlight streaming.

Stream a PC game to a handheld and the UI becomes unreadable. A HUD laid out for a 1440p desktop turns into 6-pixel text on a 3.5" 640×480 panel. Changing the setting globally is not an option either — it would ruin the game on the desktop.

StreamScale applies a per-game, per-client scaling profile when a stream starts and restores the previous state when it ends. Your desktop and your TV keep the original settings.

Sunshine session starts
        │
        ▼
StreamScale reads SUNSHINE_APP_NAME / SUNSHINE_CLIENT_NAME
        │
        ▼
Picks the adapter for that game → backs up → writes stream-friendly values
        │
        ▼
   You play, text readable
        │
        ▼
Stream ends → StreamScale restores the exact original state

Why not just use an upscaler?

Tools like Magpie or Lossless Scaling enlarge pixels. They make a 6-pixel glyph into a 12-pixel glyph — but the screen is twice as large too, so the text is exactly as hard to read. Relative size never changes.

Making text bigger requires the game to lay out its UI differently, which only the game itself can do. That is what this project automates.

Quick start

git clone https://github.com/Cvencent/StreamScale.git StreamScale
cd StreamScale
python install\setup.py

setup.py writes a launcher and prints the exact snippet to paste into Sunshine. Then verify detection — this changes nothing:

streamscale.bat show

Once that looks right, add the printed prep-cmd to your app in the Sunshine web UI (Applications → your app → Prep Commands).

Or use the tray app

Download StreamScale.exe from the Releases page and double-click it. A tray icon appears with a Settings window that edits the config and installs the press commands into apps.json for you — the fiddliest step, done by clicking Install.

The tray is a companion, not a requirement: the scaling hooks keep working when it is closed. See StreamScale-托盘程序说明.md for the status colour table, every menu item, and a troubleshooting table (in Chinese).

To build it yourself, see runtime/README.md.

Installing

Download the latest release, extract the archive, and run StreamScale\StreamScale.exe.

The program is a folder, not a single file — _internal/ must stay beside the exe. Move or copy the whole folder, not just the exe.

Upgrading

Double-click the new package. That is the whole procedure — no need to quit the running copy first.

It finds the installed version, compares versions, asks the running instance to step aside (which restores any game settings it changed), swaps the files, and restarts from the install path. The tray icon blinks out for about a second. There are no dialogs.

Windows does not allow overwriting a running executable, which is why the old build is renamed aside rather than replaced in place. The leftover image is removed by the next launch, since a process cannot delete its own running image.

Opening an older package is refused rather than applied, so a mis-download cannot silently downgrade you.

How detection works

Sunshine injects environment variables into the process it launches. Two of them are all StreamScale needs:

Variable Meaning
SUNSHINE_APP_NAME which game is being streamed
SUNSHINE_CLIENT_NAME which device is streaming (e.g. X35S, TV)
SUNSHINE_CLIENT_WIDTH / _HEIGHT what the client asked for

No window polling, no screen scraping, no guessing. If SUNSHINE_APP_NAME is absent the user launched the game normally on the desktop, and StreamScale does nothing at all.

Games launched from inside Steam

Press commands fire once, when a stream starts. If you reach a game through Steam Big Picture, that moment arrives before the game exists, so there is nothing to configure yet.

The tray handles it by applying the profile the moment the stream starts — before any game can launch:

stream starts (Steam Big Picture)  -> profile applied immediately
you launch Brotato from Steam      -> the game reads the new value
you close Brotato                  -> settings restored

Applying early is the point. A game reads its settings file within milliseconds of starting, while the process list is polled once a second; waiting to see the game means the write lands after it has already loaded the old value. Measured live: three seconds too late, and the write had no effect.

Adapters declare what to watch via process_names.

Text is still too small

Settings → General → Text size slider. 1.0× means automatic; raise it to make text larger. Also settable as "font_scale": 1.5 in config.json.

Black bars on a 4:3 screen

Most games are laid out for 16:9, so a 4:3 handheld letterboxes them. For Godot games (Brotato) this is fixable without touching the game: the engine reads an override.cfg beside the executable and lets those project settings be replaced.

Settings → General → Screen fill: keep the game's shape (default), fill the screen at the same scale (expand — no distortion, and more of the play area becomes visible), or stretch to fit exactly (ignore — distorted).

The file is merged rather than overwritten, since Brotato's ModLoader reads it too, and the change is reverted byte-for-byte when the stream ends.

Configuration

Optional. With no config file the adapter's built-in heuristic is used. To override, create %APPDATA%\StreamScale\config.json:

{
  "enabled": true,
  "excluded_apps": ["Desktop"],
  "max_client_width": 1600,
  "state_dir": "",
  "clients": {
    "X35S": { "brotato_font_size": 2.0 }
  }
}
Key Effect
enabled master switch
excluded_apps never touch these apps
max_client_width skip clients wider than this (leaves the TV alone)
state_dir where backups live; empty = ~/.streamscale
clients per-client overrides, beat the heuristic
preapply apply at stream start, needed for Steam-launched games
font_scale text size multiplier; 1.0 = automatic
aspect_fill black bars: off / expand (no distortion) / stretch

| preapply | apply at stream start, needed for Steam-launched games | | font_scale | multiplies the automatic text size | | aspect_fill | off / expand / stretch |

Supported games

Game Mechanism Notes
Brotato font_size multiplier Godot stretch/mode = 2d, so lowering the render resolution does not help — only font_size changes UI size

Adding a game means adding a module under src/streamscale/games/ and one line in registry.py. The base class handles atomic writes, backups and dry-run, so an adapter only describes what to change.

See docs/adding-a-game.md for the full guide.

Safety

  • Every write is preceded by a backup of the full prior state.
  • Writes are atomic (temp file + replace) — a crash cannot corrupt a save.
  • If a settings file is missing or unparseable the game is skipped and the stream proceeds normally; a bad config never breaks gameplay.
  • Backups are keyed by app name, so several games can be in flight without colliding.

Back up your saves. This tool edits game settings files. It is conservative and tested, but you should still keep your own backups.

Limitations

  • Windows only for now. Detection is portable; the path resolution and launcher are not.
  • One adapter per game. There is no universal mechanism — each game exposes its UI scale differently, if at all. Games with no such setting cannot be helped by this approach.
  • The resolution→scale heuristic cannot see physical screen size. Pin an exact value in clients when the default looks wrong.

Testing

python tests\test_endtoend.py

Runs the real CLI against a temporary %APPDATA% and checks that non-streaming launches are untouched, streaming raises the value, revert restores the file byte-for-byte, and oversized clients are skipped.

License

MIT

About

Per-game UI scaling automation for Sunshine/Moonlight streaming. Applies a per-game, per-client scaling profile when a stream starts and restores your desktop settings when it ends.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages