Skip to content

Commit dbb983e

Browse files
dnetgurudnetguru
committed
Update README with enhanced installation instructions.
1 parent 4939782 commit dbb983e

File tree

1 file changed

+113
-98
lines changed

1 file changed

+113
-98
lines changed

‎README.md‎

Lines changed: 113 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,158 @@
11
# Wallpaper Engine Controller
22

3-
A lightweight utility that automatically pauses and resumes Wallpaper Engine based on percentage desktop visibility, using an efficient, event-driven library.\
3+
A lightweight utility that automatically pauses and resumes Wallpaper Engine based on percentage desktop visibility, using an efficient, event-driven library.
44
The goal is to save CPU/GPU resources when your desktop is obscured (e.g., by fullscreen apps or windows).
55

66
## Why Use This?
77

8-
Wallpaper Engine has basic occlusion detection (pausing for maximized windows on a monitor), but it doesn't handle advanced scenarios like multiple side-by-side windows obscuring the desktop.\
9-
\
10-
This tool enables using more resource-intensive wallpapers by pausing rendering when they're not visible as well as allowing the user to specify a threshold for what percentage of the dekstop needs to be visible for the rendering to continue.\
11-
\
12-
It is recommended to specify your main monitor with `-m` (e.g., `-m 1`); if its visibility drops below the threshold, all wallpapers pause. The code supports per-monitor pause/resume, which can be enabled if Wallpaper Engine adds support for per-monitor external control in the future.\
13-
\
14-
**Note:** Wallpaper Engine currently [only supports](https://help.wallpaperengine.io/en/functionality/cli.html#pause) pausing/resuming all monitors at once—no per-monitor control via CLI.
8+
Wallpaper Engine has basic occlusion detection (pausing for maximized windows on a monitor), but it doesn't handle advanced scenarios like multiple side-by-side windows obscuring the desktop.
159

16-
## Features
10+
This tool enables using more resource-intensive wallpapers by pausing rendering when they're not visible as well as allowing the user to specify a threshold for what percentage of the desktop needs to be visible for the rendering to continue.
1711

18-
- **Event-Driven Monitoring**: Uses libvisdesk for real-time desktop visibility tracking—no wasteful polling.
19-
- **Flexible Controls**: Global or per-monitor modes (note: per-monitor pausing not yet supported by Wallpaper Engine).
20-
- **Customizable Thresholds**: Pause when visibility drops below a set percentage (0-100).
21-
- **Throttle Updates**: Configurable max frequency for visibility checks (default: 1000ms).
22-
- **32/64-Bit Support**: Compatible with both Wallpaper Engine versions.
23-
- **Graceful Shutdown**: Auto-resumes wallpapers on exit.
24-
- **Service Mode**: Run as a Windows background service for always-on operation with automatic installation.
12+
It is recommended to specify your main monitor with `-m` (e.g., `-m 1`); if its visibility drops below the threshold, all wallpapers pause. The code supports per-monitor pause/resume, which can be enabled if Wallpaper Engine adds support for per-monitor external control in the future.
2513

26-
## Prerequisites
14+
Note: Wallpaper Engine currently only supports pausing/resuming all monitors at once—no per-monitor control via CLI.
2715

28-
- Windows (tested on Windows 11).
29-
- Wallpaper Engine installed and running (as a service for background mode).
30-
- Rust (for building from source; see below).
16+
## Features
3117

32-
## Installation
18+
- Event-Driven Monitoring: Uses libvisdesk for real-time desktop visibility tracking—no wasteful polling.
19+
- Flexible Controls: Global or per-monitor modes (note: per-monitor pausing not yet supported by Wallpaper Engine).
20+
- Customizable Thresholds: Pause when visibility drops below a set percentage (0-100).
21+
- Throttle Updates: Configurable max frequency for visibility checks (default: 1000ms).
22+
- 32/64-Bit Support: Compatible with both Wallpaper Engine versions.
23+
- Graceful Shutdown: Auto-resumes wallpapers on exit.
24+
- Startup Integration:
25+
- Windows Service mode (requires Wallpaper Engine’s own service).
26+
- Windows Scheduled Task mode (runs at user logon, highest privileges).
3327

34-
### From Releases (Recommended)
28+
## Prerequisites
3529

36-
Download the latest pre-built binary from [Releases](https://github.com/dnetguru/wallpaper-engine-controller/releases) and run `wallpaper-controller.exe`.
30+
- Windows (tested on Windows 11).
31+
- Wallpaper Engine installed.
32+
- For Windows Service startup: enable Wallpaper Engine’s “High Priority mode (Run as service)” in WE settings (this installs the service and `C:\WINDOWS\SysWOW64\wallpaperservice32.exe`). In the Wallpaper Engine UI, this is called “High Priority mode.”
33+
- Rust (only if building from source; see below).
3734

38-
### Running as a Windows Service
35+
## Installation (Interactive – Recommended)
3936

40-
For automatic startup:\
37+
- Download the latest pre-built binary from Releases and simply double-click `wallpaper-controller.exe`.
38+
- Launching with no arguments opens the interactive installer (TUI).
39+
- Alternatively, run from a terminal with: `wallpaper-controller --install-tui`
4140

42-
1. Install to a permanent path and create the service in one command:
43-
```powershell
44-
wallpaper-controller --install "$HOME\.wallpaper-controller\wallpaper-controller.exe" --add-startup-service -m all -t 10
45-
```
46-
- This copies the exe to the specified path and sets up the service to run `wallpaper-controller.exe -m all -t 10` on Windows startup.
47-
- Flags (except `--install` and `--add-startup-service`) are captured; the service always runs with them.
48-
- **Note:** `--install` just copies the file. You can manually copy the file if preferred. Manually delete the file if needed.
41+
The installer guides you through:
42+
- Install directory: Provide a folder; the tool copies itself there as `wallpaper-controller.exe`.
43+
- Startup mode:
44+
- Windows Service (recommended if you’ve enabled Wallpaper Engine’s “High Priority mode”).
45+
- Scheduled Task (recommended if you are not using WE’s service) at user logon
46+
- Runtime settings: monitors to watch, visibility threshold, update rate, 64-bit WE, etc.
4947

50-
2. To change flags: Stop all running instances of `wallpaper-controller.exe`, then rerun `--add-startup-service` with new flags (this deletes and recreates the service; no `--install` needed).
48+
## Quickstart Video
5149

52-
3. Manage the service via the Services app (search "services.msc") or `sc` commands (e.g., `sc start WallpaperControllerService`; delete with `sc delete WallpaperControllerService`).
50+
[![Quickstart](https://img.youtube.com/vi/yGtkyHIibF4/0.jpg)](https://www.youtube.com/watch?v=yGtkyHIibF4)
5351

54-
4. **Note:** Requires Wallpaper Engine running as a service.
52+
### Managing the service or task (optional)
5553

56-
**Additional Note:** These flags are provided for convenience. You can run the tool without installing it as a service, e.g., via scheduled tasks or manually.
54+
- Windows Service:
55+
- Start/Stop via Services (services.msc) or PowerShell/CMD:
56+
- `sc start WallpaperControllerService`
57+
- `sc stop WallpaperControllerService`
58+
- `sc delete WallpaperControllerService` (removes the service)
59+
- Scheduled Task:
60+
- Delete via Task Scheduler UI or:
61+
- `schtasks /Delete /TN "WallpaperControllerAtLogon" /F`
5762

58-
### Building from Source
63+
## Building from Source
5964

60-
```shell
61-
git clone https://github.com/dnetguru/wallpaper-engine-controller.git
62-
cd wallpaper-engine-controller
63-
cargo build --release
65+
```shell
66+
git clone https://github.com/dnetguru/wallpaper-engine-controller.git
67+
cd wallpaper-engine-controller
68+
cargo build --release
6469
```
6570

66-
For cross-compilation on Linux:
67-
```shell
68-
rustup target add x86_64-pc-windows-gnu
69-
sudo apt install -y gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64
70-
cargo build --target x86_64-pc-windows-gnu --release
71+
Cross-compilation on Linux:
72+
```shell
73+
rustup target add x86_64-pc-windows-gnu
74+
sudo apt install -y gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64
75+
cargo build --target x86_64-pc-windows-gnu --release
7176
```
7277

7378
## Quick Start
7479

75-
```shell
76-
wallpaper-controller -m all -t 10
77-
```
80+
```shell
81+
wallpaper-controller -m all -t 10
82+
```
7883
- Monitors all displays; pauses if <10% visible.
7984

80-
List monitors first:
81-
```shell
82-
wallpaper-controller --list-monitors
83-
```
85+
List monitors first:
86+
```shell
87+
wallpaper-controller --list-monitors
88+
```
8489

85-
#### Custom threshold and update rate:
86-
This would pause Wallpaper Engine if less than 15% of your desktop is visible across all monitors. It does not start/stop wallpaper engine more frequently than every 0.5 seconds.
87-
```shell
88-
wallpaper-controller --threshold 15 --update-rate 500
90+
#### Custom threshold and update rate
91+
This pauses Wallpaper Engine if less than 15% of your desktop is visible across all monitors and won’t update more frequently than every 0.5 seconds.
92+
```shell
93+
wallpaper-controller --threshold 15 --update-rate 500
8994
```
90-
#### Specific monitors, 64-bit:
91-
This would pause Wallpaper Engine if less than 20% of your desktop is visible across monitors numbered 1 and 3. All other monitors are ignored.\
92-
The monitor numbers can be found by running the program with `-L` command and they should match the numbers shown in Windows' Display Settings.
93-
```shell
94-
wallpaper-controller -m 1,3
95+
96+
#### Specific monitors, 64-bit
97+
Pause Wallpaper Engine if less than 20% is visible across monitors 1 and 3 (numbers match Windows Display Settings).
98+
```shell
99+
wallpaper-controller -m 1,3 --64bit
95100
```
96101

97-
#### Custom path:
98-
You can specify a custom path to Wallppaper Engine installation (if you are not using the default).
99-
```shell
100-
wallpaper-controller --wallpaper-engine-path "D:\Games\WallpaperEngine" --64bit
102+
#### Custom path
103+
Specify a custom Wallpaper Engine install path if not using the default.
104+
```shell
105+
wallpaper-controller --wallpaper-engine-path "D:\\Games\\WallpaperEngine" --64bit
101106
```
102107

103108
## CLI Options
104109

105-
```sh
106-
Usage: wallpaper-controller.exe [OPTIONS]
107-
108-
Options:
109-
-m, --monitors <MONITORS>
110-
Monitors to watch, use numbers shown in Display Settings or use -L to list monitors (comma-separated, or "all" for all monitors) [default: all]
111-
-t, --threshold <THRESHOLD>
112-
Minimum visibility threshold percentage (0-100) to pause the wallpaper engine [default: 20]
113-
-p, --per-monitor
114-
Per-monitor mode - track visibility for each monitor separately (THIS IS NOT SUPPORTED BY WALLPAPER ENGINE, YET)
115-
-u, --update-rate <UPDATE_RATE>
116-
Maximum update frequency in milliseconds [default: 1000]
117-
--wallpaper-engine-path <WALLPAPER_ENGINE_PATH>
118-
Path to Wallpaper Engine executable [default: "C:\\Program Files (x86)\\Steam\\steamapps\\common\\wallpaper_engine"]
119-
--64bit
120-
Use the 64-bit version of Wallpaper Engine (wallpaper64.exe), otherwise use 32-bit (wallpaper32.exe)
121-
-L, --list-monitors
122-
List all available monitors and their IDs, then exit
123-
--disable-sentry
124-
Disable Sentry error reporting
125-
--sentry-dsn <SENTRY_DSN>
126-
Override the default Sentry error reporting DSN (for debugging purposes) [default: https://c6caa06487e9769daccfbedcd8de6324@o504783.ingest.us.sentry.io/4509839881076736]
127-
--install <INSTALL>
128-
Copy the assembly to the specified path and exit (must end with .exe)
129-
--add-startup-service
130-
Add a Windows service to run this program with the specified flags and exit
131-
-h, --help
132-
Print help
133-
-V, --version
134-
Print version
110+
Based on the current binary’s help output (summarized):
111+
112+
```
113+
Usage: wallpaper-controller.exe [OPTIONS]
114+
115+
Options:
116+
-m, --monitors <MONITORS>
117+
Monitors to watch, use numbers shown in Display Settings or use -L to list monitors (comma-separated, or "all" for all monitors) [default: all]
118+
-t, --threshold <THRESHOLD>
119+
Minimum visibility threshold percentage (0-100) to pause the wallpaper engine [default behavior: 20 if not provided]
120+
-p, --per-monitor
121+
Per-monitor mode - track visibility for each monitor separately (THIS IS NOT SUPPORTED BY WALLPAPER ENGINE, YET)
122+
-u, --update-rate <UPDATE_RATE>
123+
Maximum update frequency in milliseconds [default: 1000]
124+
-w, --wallpaper-engine-path <WALLPAPER_ENGINE_PATH>
125+
Path to Wallpaper Engine executable [default: "C:\\Program Files (x86)\\Steam\\steamapps\\common\\wallpaper_engine"]
126+
--64bit
127+
Use the 64-bit version of Wallpaper Engine (wallpaper64.exe), otherwise use 32-bit (wallpaper32.exe)
128+
-L, --list-monitors
129+
List all available monitors and their IDs, then exit
130+
--disable-sentry
131+
Disable Sentry error reporting
132+
--sentry-dsn <SENTRY_DSN>
133+
Override the default Sentry error reporting DSN (for debugging purposes)
134+
--install-tui
135+
Launch interactive installer (TUI)
136+
--install-dir <DIR>
137+
Copy the assembly into the specified directory and exit (non-interactive install)
138+
--add-startup-service
139+
Add a Windows service to run this program with the specified flags and exit
140+
--add-startup-task
141+
Add a Windows Scheduled Task to run this program at user logon and exit
142+
-h, --help
143+
Print help
144+
-V, --version
145+
Print version
135146
```
136147

148+
Notes:
149+
- The recommended setup path is the interactive installer (double-click the EXE or use `--install-tui`).
150+
- For Service installs, enable Wallpaper Engine’s “High Priority mode (Run as service)” in WE settings first (this is what WE calls the service mode).
151+
- For Scheduled Task installs, the installer automatically adds `-silent`.
152+
137153
### Silent Mode
138-
It is possible to launch this application with `-silent` which causes it completely run in the foreground, not showing a console window.\
139-
This is the default behavior when installed as a service.
140154

155+
You can launch this application with `-silent` to run in the background without showing a console window. This is the default behavior when installed as a scheduled task, and service mode runs headless as well.
141156

142157
## Contributing
143158

0 commit comments

Comments
 (0)