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
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.
git clone https://github.com/Cvencent/StreamScale.git StreamScale
cd StreamScale
python install\setup.pysetup.py writes a launcher and prints the exact snippet to paste into
Sunshine. Then verify detection — this changes nothing:
streamscale.bat showOnce that looks right, add the printed prep-cmd to your app in the
Sunshine web UI (Applications → your app → Prep Commands).
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.
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.
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.
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.
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.
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.
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.
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 |
| 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.
- 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.
- 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
clientswhen the default looks wrong.
python tests\test_endtoend.pyRuns 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.
MIT