sunshine-res 0.0.1__tar.gz

sunshine_res-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+MIT License Copyright (c) 2025 iamthefij
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sunshine_res-0.0.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: sunshine-res
+Version: 0.0.1
+Summary: Sunshine script to match Linux desktop resolution to client
+License: MIT
+License-File: LICENSE
+Author: iamthefij
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# 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
+
+The project is distributed as a Poetry package. If you already have Poetry installed:
+
+```bash
+poetry install
+```
+
+Alternatively, you can install it system‑wide (or inside a virtualenv) with:
+
+```bash
+pip install .
+```
+
+The tool installs a console script called `sunshine-res` that can be invoked from anywhere.
+
+## Usage
+
+The utility accepts three commands:
+
+| Command | Description |
+|---------|-------------|
+| `do` | Set the monitor to the target resolution (as specified by the environment variables below). |
+| `undo` | Revert the monitor to the original mode that was active before the last `do`. |
+| `auto` | Toggle between the two states. If a previous `do` was performed, `undo` will be run; otherwise `do` will be executed. This is the default if no command is given. |
+
+### Configuring Sunshine
+
+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
+
+### Example
+
+```bash
+# 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; defaults are:
+
+- `SUNSHINE_CLIENT_WIDTH`  – 1920
+- `SUNSHINE_CLIENT_HEIGHT` – 1080
+- `SUNSHINE_CLIENT_FPS`    – 60
+- `SUNSHINE_CLIENT_HDR`   – false
+
+## Supported Desktop Environments
+
+| Desktop | Implementation |
+|---------|-----------------|
+| KDE | Uses `kscreen-doctor` to query and set monitor modes. |
+| COSMIC | Uses `cosmic-randr` to query and set monitor modes. |
+
+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 (`kscreen-doctor` or `cosmic-randr`) returns a JSON/KDL 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
+
+| Error | What it means | How to fix |
+|-------|----------------|------------|
+| `ERROR: Could not determine current desktop` | No desktop environment variable was found. | Make sure you are running the command from an active session. On some shells you may need to export `XDG_CURRENT_DESKTOP=KDE` or `COSMIC` manually. |
+| `Could not find resolution manager for desktop <name>` | The desktop variable contains an unsupported value. | Check the spelling of the desktop name. Supported values are `KDE` and `COSMIC`. |
+| `Did not find mode matching <width>x<height> at <output>` | The monitor does not advertise the requested resolution. | Verify that the resolution is supported by your monitor or try a different resolution. |
+| `Could not identify current mode` | The underlying command returned an unexpected format. | Ensure `cosmic-randr` or `kscreen-doctor` is installed and working. Run the command manually (`cosmic-randr list --kdl` or `kscreen-doctor --json`) to confirm. |
+| `Permission denied` | The command was unable to write to `~/.config/sunshine/last_mode.json`. | Verify that you have write permissions to `~/.config/sunshine`. |
+
+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.
+

sunshine_res-0.0.1/README.md

@@ -0,0 +1,85 @@
+# 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
+
+The project is distributed as a Poetry package. If you already have Poetry installed:
+
+```bash
+poetry install
+```
+
+Alternatively, you can install it system‑wide (or inside a virtualenv) with:
+
+```bash
+pip install .
+```
+
+The tool installs a console script called `sunshine-res` that can be invoked from anywhere.
+
+## Usage
+
+The utility accepts three commands:
+
+| Command | Description |
+|---------|-------------|
+| `do` | Set the monitor to the target resolution (as specified by the environment variables below). |
+| `undo` | Revert the monitor to the original mode that was active before the last `do`. |
+| `auto` | Toggle between the two states. If a previous `do` was performed, `undo` will be run; otherwise `do` will be executed. This is the default if no command is given. |
+
+### Configuring Sunshine
+
+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
+
+### Example
+
+```bash
+# 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; defaults are:
+
+- `SUNSHINE_CLIENT_WIDTH`  – 1920
+- `SUNSHINE_CLIENT_HEIGHT` – 1080
+- `SUNSHINE_CLIENT_FPS`    – 60
+- `SUNSHINE_CLIENT_HDR`   – false
+
+## Supported Desktop Environments
+
+| Desktop | Implementation |
+|---------|-----------------|
+| KDE | Uses `kscreen-doctor` to query and set monitor modes. |
+| COSMIC | Uses `cosmic-randr` to query and set monitor modes. |
+
+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 (`kscreen-doctor` or `cosmic-randr`) returns a JSON/KDL 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
+
+| Error | What it means | How to fix |
+|-------|----------------|------------|
+| `ERROR: Could not determine current desktop` | No desktop environment variable was found. | Make sure you are running the command from an active session. On some shells you may need to export `XDG_CURRENT_DESKTOP=KDE` or `COSMIC` manually. |
+| `Could not find resolution manager for desktop <name>` | The desktop variable contains an unsupported value. | Check the spelling of the desktop name. Supported values are `KDE` and `COSMIC`. |
+| `Did not find mode matching <width>x<height> at <output>` | The monitor does not advertise the requested resolution. | Verify that the resolution is supported by your monitor or try a different resolution. |
+| `Could not identify current mode` | The underlying command returned an unexpected format. | Ensure `cosmic-randr` or `kscreen-doctor` is installed and working. Run the command manually (`cosmic-randr list --kdl` or `kscreen-doctor --json`) to confirm. |
+| `Permission denied` | The command was unable to write to `~/.config/sunshine/last_mode.json`. | Verify that you have write permissions to `~/.config/sunshine`. |
+
+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.

sunshine_res-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "sunshine-res"
+version = "0.0.1"
+description = "Sunshine script to match Linux desktop resolution to client"
+authors = ["iamthefij"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.scripts]
+sunshine-res = "sunshine_res:main"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.4.2"
+isort = "^5.13.2"
+mypy = "^1.10.0"
+coverage = "^7.12.0"
+pre-commit = "^3.7.1"
+pytest = "^9.0.1"
+
+[tool.isort]
+force_single_line = true
+profile = "black"

sunshine_res-0.0.1/sunshine_res/__init__.py

@@ -0,0 +1,84 @@
+"""
+Resolution Management Module
+
+This module provides a system to dynamically adjust display resolution and HDR settings
+based on the user's desktop environment (KDE or Cosmic). It supports command-line
+operations to 'do' (apply a resolution), 'undo' (revert to original), or 'auto' (toggle
+between modes). The module uses platform-specific tools (kscreen-doctor for KDE,
+cosmic-randr for Cosmic) to interface with the display server.
+
+Key Features:
+- Auto-detects desktop environment (KDE/Cosmic)
+- Manages resolution and HDR settings
+- Persistent state tracking for 'undo' operations
+
+Usage:
+sunshine-res [do/undo/auto]
+"""
+
+import os
+import sys
+
+from sunshine_res.cosmic import CosmicRandr
+from sunshine_res.kde import KscreenDoctor
+from sunshine_res.types import ResolutionManager
+
+SUNSHINE_CLIENT_WIDTH = int(os.getenv("SUNSHINE_CLIENT_WIDTH", 1920))
+SUNSHINE_CLIENT_HEIGHT = int(os.getenv("SUNSHINE_CLIENT_HEIGHT", 1080))
+SUNSHINE_CLIENT_FPS = int(os.getenv("SUNSHINE_CLIENT_FPS", 60))
+SUNSHINE_CLIENT_HDR = bool(os.getenv("SUNSHINE_CLIENT_HDR")) == True
+
+
+DESKTOP_TO_CLASS: dict[str, type[ResolutionManager]] = {
+    "KDE": KscreenDoctor,
+    "COSMIC": CosmicRandr,
+}
+
+
+def main() -> None:
+    """Entry point for sunshine-res command line tool."""
+    # Get the currently listed desktop
+    current_desktop = os.getenv(
+        "XDG_CURRENT_DESKTOP",
+        os.getenv("XDG_SESSION_DESKTOP", os.getenv("SESSION_DESKTOP")),
+    )
+    if not current_desktop:
+        print("ERROR: Could not determine current desktop")
+        exit(1)
+
+    # Find a manager class that matches
+    manager: ResolutionManager
+    for desktop in current_desktop.split(":"):
+        if mc := DESKTOP_TO_CLASS.get(desktop):
+            manager = mc(
+                client_width=SUNSHINE_CLIENT_WIDTH,
+                client_height=SUNSHINE_CLIENT_HEIGHT,
+                client_fps=SUNSHINE_CLIENT_FPS,
+                client_hdr=SUNSHINE_CLIENT_HDR,
+            )
+            break
+    else:
+        print(f"Could not find resolution manager for desktop {current_desktop}")
+        exit(1)
+
+    # Read the command from args
+    command = ""
+    if len(sys.argv) < 2:
+        command = "auto"
+    else:
+        command = sys.argv[1]
+
+    # Execute command in given manager
+    if command == "auto":
+        manager.toggle()
+    elif command == "do":
+        manager.do()
+    elif command == "undo":
+        manager.undo()
+    else:
+        print(f"Unknown command {command}")
+        exit(1)
+
+
+if __name__ == "__main__":
+    main()

sunshine_res-0.0.1/sunshine_res/__main__.py

@@ -0,0 +1,4 @@
+from sunshine_res import main
+
+if __name__ == "__main__":
+    main()

sunshine_res-0.0.1/sunshine_res/cosmic.py

@@ -0,0 +1,71 @@
+import re
+from subprocess import check_call
+from subprocess import check_output
+from typing import override
+
+from sunshine_res.types import MonitorInfo
+from sunshine_res.types import MonitorMode
+from sunshine_res.types import ResolutionManager
+
+
+class CosmicRandr(ResolutionManager):
+
+    def parse_kdl(self, kdl_str: str) -> MonitorInfo:
+        output_name = ""
+        modes: list[MonitorMode] = []
+        current_mode: MonitorMode | None = None
+
+        for line in kdl_str.split("\n"):
+            line = line.strip()
+
+            if not line:
+                continue
+
+            if output := re.match(r'output\s+"(.+)"', line):
+                if output_name and output_name != output.group(1):
+                    raise ValueError(
+                        "Detected multiple output names. Check cosmic-randr."
+                    )
+                output_name = output.group(1)
+            elif mode := re.match(r"mode\s+(\d+)\s+(\d+)\s+(\d+)", line):
+                this_mode = MonitorMode(
+                    id=None,
+                    width=int(mode.group(1)),
+                    height=int(mode.group(2)),
+                    fps=int(mode.group(3)) / 1000,
+                )
+                modes.append(this_mode)
+                if "current=#true" in line:
+                    current_mode = this_mode
+
+        if not current_mode:
+            raise ValueError("Could not identify current mode. Check cosmic-randr.")
+
+        return MonitorInfo(
+            output_name=output_name,
+            hdr=False,
+            modes=modes,
+            current_mode=current_mode,
+        )
+
+    @override
+    def query_monitor_info(self) -> MonitorInfo:
+        out = check_output(["cosmic-randr", "list", "--kdl"])
+        cosmic_info = self.parse_kdl(out.decode())
+        return cosmic_info
+
+    @override
+    def apply_mode(
+        self, output_name: str, mode: MonitorMode, hdr: bool = False
+    ) -> None:
+        _ = check_call(
+            [
+                "cosmic-randr",
+                "mode",
+                output_name,
+                str(mode["width"]),
+                str(mode["height"]),
+                "--refresh",
+                str(mode["fps"]),
+            ]
+        )

sunshine_res-0.0.1/sunshine_res/kde.py

@@ -0,0 +1,102 @@
+import json
+from subprocess import check_call
+from subprocess import check_output
+from typing import TypedDict
+from typing import cast
+from typing import override
+
+from sunshine_res.types import MonitorInfo
+from sunshine_res.types import MonitorMode
+from sunshine_res.types import ResolutionManager
+from sunshine_res.types import ScreenSize
+
+
+class KScreenMode(TypedDict):
+    """Screen mode from kscreen-doctor."""
+
+    id: str
+    name: str
+    refreshRate: float
+    size: ScreenSize
+
+
+class KScreenOutput(TypedDict):
+    """Output device info from kscreen-doctor."""
+
+    connected: bool
+    currentModeId: str
+    enabled: bool
+    hdr: bool
+    id: int
+    modes: list[KScreenMode]
+    name: str
+    size: ScreenSize
+    sizeMM: ScreenSize
+
+
+class KScreenInfo(TypedDict):
+    """Screen information from kscreen-doctor."""
+
+    currentSize: ScreenSize
+    id: int
+    maxActiveOutputsCount: int
+    maxSize: ScreenSize
+    minSize: ScreenSize
+
+
+class KScreenResult(TypedDict):
+    """Result returned from kscreen-doctor."""
+
+    outputs: list[KScreenOutput]
+    screen: KScreenInfo
+
+
+class KscreenDoctor(ResolutionManager):
+
+    @override
+    def query_monitor_info(self) -> MonitorInfo:
+        out = check_output(["kscreen-doctor", "--json"])
+        screen_info = cast(KScreenResult, json.loads(out))
+
+        screen_id = screen_info["screen"]["id"]
+        output = screen_info["outputs"][screen_id]
+
+        # Get current mode info for restoring
+        modes: list[MonitorMode] = []
+        current_mode: MonitorMode | None = None
+        current_mode_id = output["currentModeId"]
+        for mode in output["modes"]:
+            new_mode = MonitorMode(
+                id=mode["name"],
+                width=mode["size"]["width"],
+                height=mode["size"]["height"],
+                fps=mode["refreshRate"],
+            )
+            if mode["id"] == current_mode_id:
+                current_mode = new_mode
+            modes.append(new_mode)
+
+        if not current_mode:
+            raise ValueError(
+                "Could not determine the current monitor mode. Check kscreen-doctor."
+            )
+
+        return MonitorInfo(
+            output_name=output["name"],
+            current_mode=current_mode,
+            modes=modes,
+            hdr=output["hdr"],
+        )
+
+    @override
+    def apply_mode(
+        self, output_name: str, mode: MonitorMode, hdr: bool = False
+    ) -> None:
+        # Set the new display mode
+        _ = check_call(
+            [
+                "kscreen-doctor",
+                f"output.{output_name}.mode.{mode['id']}",
+                f"output.{output_name}.hdr.{'enable' if hdr else 'disable'}",
+            ]
+        )

sunshine_res-0.0.1/sunshine_res/types.py

@@ -0,0 +1,123 @@
+"""Common type definitions for monitor and screen information."""
+
+import json
+from pathlib import Path
+from typing import TypedDict
+from typing import cast
+
+
+class MonitorMode(TypedDict):
+    """Generic abstraction for a monitor mode."""
+
+    id: str | None
+    width: int
+    height: int
+    fps: float
+
+
+class MonitorInfo(TypedDict):
+    """Generic a abstraction of a monitor."""
+
+    output_name: str
+    hdr: bool
+    modes: list[MonitorMode]
+    current_mode: MonitorMode
+
+
+class ScreenSize(TypedDict):
+    """Size of a screen."""
+
+    width: int
+    height: int
+
+
+class ResolutionManager:
+    """
+    Base class for managing display resolution and HDR settings.
+
+    This class serves as a blueprint for platform-specific resolution managers. Subclasses
+    must implement `query_monitor_info` and `apply_mode` to interface with the display server.
+    """
+
+    def __init__(
+        self,
+        client_width: int,
+        client_height: int,
+        client_fps: int,
+        client_hdr: bool = False,
+    ) -> None:
+        self.client_width: int = client_width
+        self.client_height: int = client_height
+        self.client_fps: int = client_fps
+        self.client_hdr: bool = client_hdr
+        self.last_mode: Path = Path("~/.config/sunshine/last_mode.json").expanduser()
+
+    def query_monitor_info(self) -> MonitorInfo:  # pragma: no cover
+        raise NotImplementedError()
+
+    def apply_mode(
+        self, output_name: str, mode: MonitorMode, hdr: bool = False
+    ) -> None:  # pragma: no cover
+        raise NotImplementedError()
+
+    def do(self) -> None:
+        monitor_info = self.query_monitor_info()
+        if (
+            monitor_info["current_mode"]["width"],
+            monitor_info["current_mode"]["height"],
+        ) == (self.client_width, self.client_height):
+            print("Resolution already matches.")
+            return
+
+        # Filter modes to matching resolution
+        matched_modes = [
+            mode
+            for mode in monitor_info["modes"]
+            if (
+                mode["height"] == self.client_height
+                and mode["width"] == self.client_width
+            )
+        ]
+
+        # Sort by fps
+        matched_modes.sort(key=lambda m: m["fps"])
+
+        if not matched_modes:
+            raise ValueError(
+                f"Did not find mode matching {self.client_width}x{self.client_height} at {monitor_info['output_name']}"
+            )
+
+        # Get the mode with the closest refreshrate but not below
+        # Eg. if 25 is requested, and 20 and 30 are offered, return 30
+        select_mode: MonitorMode = matched_modes[-1]
+        for mode in matched_modes:
+            select_mode = mode
+            if mode["fps"] >= self.client_fps:
+                break
+
+        self.apply_mode(monitor_info["output_name"], select_mode, hdr=self.client_hdr)
+
+        # Save original monitor info to file
+        if not self.last_mode.parent.exists():
+            self.last_mode.parent.mkdir(parents=True, exist_ok=True)
+
+        _ = self.last_mode.write_text(json.dumps(monitor_info))
+
+    def undo(self) -> None:
+        # Check previous mode
+        if not self.last_mode.exists():
+            return
+
+        info: MonitorInfo = cast(MonitorInfo, json.loads(self.last_mode.read_text()))
+
+        # Set the new display mode
+        self.apply_mode(info["output_name"], info["current_mode"], hdr=info["hdr"])
+
+        # Clean up file
+        self.last_mode.unlink()
+
+    def toggle(self) -> None:
+        if self.last_mode.exists():
+            self.undo()
+        else:
+            self.do()