A real-time SRCNN upscaler for any X-Window (X11 or XWayland) on GNU/Linux. It uses CuNNy neural networks to perform 2x (or 4x) upscaling to full screen while preserving aspect ratio. Mouse clicks and motion are automatically forwarded to the original window.
- Neural-Network upscaling using SRCNNs trained for high-quality upscaling of visual novels and illustrations.
- Model selection from 9 variants with variable quality/performance trade-offs.
- Hardware accelerated using Vulkan compute.
- Tile-Based processing that upscales only the frame regions that change, reducing GPU load for mostly static content.
- Customizable output geometry: scaling mode (fit, stretch, cover), offset, crop and zoom.
- Input forwarding as if interacting directly with the original window.
- GNU/Linux (X11 or Wayland with XWayland)
- Vulkan-capable GPU (NVIDIA, AMD, Intel)
- Python 3.10 or newer
- Qt XCB plugin
Important
Qt XCB plugin
This library is not installed by default on most desktop environments.
pipx install linux-rt-upscalerRequired development packages (click to expand)
sudo apt update
sudo apt install gcc make libvulkan-dev libx11-dev libxcb1-dev libx11-xcb-dev \
libxext-dev libxdamage-dev libxfixes-devsudo dnf install gcc make vulkan-loader-devel libX11-devel libxcb-devel libX11-xcb-devel \
libXext-devel libXdamage-devel libXfixes-develsudo pacman -S base-devel vulkan-devel libx11 libxcb libxext libxdamage libxfixessudo zypper install gcc make vulkan-devel libX11-devel libxcb-devel libX11-xcb-devel \
libXext-devel libXdamage-devel libXfixes-develgit clone https://github.com/baronsmv/linux-rt-upscaler.git
cd linux-rt-upscaler
pip install -e .After installing, you can add a desktop entry so the GUI appears in your application menu:
curl -fsSL https://raw.githubusercontent.com/baronsmv/linux-rt-upscaler/refs/heads/main/scripts/desktop_integration.sh \
-o /tmp/desktop_integration.sh
less /tmp/desktop_integration.sh # always review scripts before running them
sh /tmp/desktop_integration.shAfter installation, the upscale-gui and upscale commands will be available globally:
upscale-guiThe GUI displays live thumbnails of every open valid window. Click one to start upscaling that window.
Use the right panel to adjust any setting, and the left panel to create profiles that automatically apply when a matching window is detected, or when selected manually.
# Upscale the currently active window
upscale
# Interactively select from visible windows
upscale -s
# Run a command and upscale its window
upscale -- <command>
# Choose a specific model (examples)
upscale -m 8x32 # Highest quality, slowest
upscale -m veryfast # Maximum performance
# Perform 4x upscaling (two 2x passes)
upscale -2
# Crop 100 pixels from top and left, then upscale
upscale --crop-top 100 --crop-left 100For a full list of options and examples:
upscale --help| Shortcut | Action |
|---|---|
Alt+Shift+S |
Pause upscaling |
Alt+Shift+Escape |
Exit upscaling |
Alt+Shift+P |
Take a lossless screenshot |
Alt+Shift+M |
Switch to the next model |
Alt+Shift+G |
Cycle output geometry (fit, stretch, cover) |
Alt+Shift++ / - |
Zoom in / Zoom out |
Alt+Shift+↑ / ↓ / ← / → |
Pan the upscaled content |
All hotkeys can be customised in the configuration file.
You can define named configuration profiles in your YAML config file. Profiles let you quickly switch settings for different games or applications without typing long command lines each time.
Create a config file (e.g., ~/.config/linux-rt-upscaler/config.yaml) and add a top-level profiles key. Each profile is a dictionary with an optional match section and an options section.
If no profile is selected manually, the program checks all profiles that have a match section against the title of the target window. If a profile matches (any match criterion is sufficient), its options are applied automatically.
# General defaults (lowest priority)
model: 3x12
double_upscale: true
# Profiles that override if matched
profiles:
game:
match:
title: "Danganronpa" # Exact match (case-insensitive)
title_contains: "ronp" # Or substring match (case-insensitive)
title_regex: "Dangan.*" # Or regular expression (case-insensitive)
options:
model: 4x24
double_upscale: trueA more detailed example is included here.
- Selects a window using X11 to find the target window by PID or WM_CLASS.
- Captures the window's pixels using XShm and XDamage.
- Upscales with SRCNN compute shaders to a 2x (or 4x) larger image.
- Scales with a Lanczos2 shader to fill the monitor.
- Renders in a overlay window that bypasses the window manager (so it always stays on top).
- Forwards mouse events to the original window.
- Addition of more SRCNN models (FSRCNNX planned).
-
Native Wayland support(on hold: Wayland capture is deeply compositor-specific and currently doesn’t align with the XShm/XDamage pipeline.)
Synthetic mouse events (clicks, motion, wheel) sent by the overlay are ignored by:
- Wine and Proton versions older than 10.0 (GE-Proton10 + UMU works).
- Some native applications like Firefox.
For more details, see issue #7.
This project stands on the shoulders of several open-source works, mantained by amazing people:
- L65536, for the original RealTimeSuperResolutionScreenUpscalerforLinux, which demonstrated the feasibility of real-time SRCNN upscaling on Linux and served as a proof-of-concept for this project.
- funnyplanter, for the incredible CuNNy neural network upscaling models.
- Compushady, which served as an invaluable Vulkan foundation during early development.
- PySide6, the Qt binding that powers the entire graphical interface and overlay window.
- xcffib, the XCB binding used for window management, monitor querying and event forwarding.
- Pillow, the Python Imaging Library, used for saving screenshots and rendering OSD messages.
- PyYAML, the YAML parser used for configuration file operations.