Multi-Monitor Setups

The Go server serves filtered images. A companion CLI can also apply wallpapers locally on supported desktops. Its platform adapters vary: macOS supports all displays or a 1-based desktop index, Linux supports detected backends, while the Windows system adapter currently targets all displays. Unsupported per-monitor selections return clear errors rather than silently changing all screens. When you need more control, make one filtered request per display and use your desktop’s native wallpaper command.

The pattern

Request a wallpaper tuned to each screen’s shape, then set them independently:

#!/usr/bin/env sh
set -eu

base="http://your-server:8519/api/wallpapers/random/image"

# An ultrawide for the main display, a portrait for the vertical one.
curl --fail --silent "$base?aspect_ratio=ultrawide" --output /tmp/wall-main.jpg
curl --fail --silent "$base?orientation=portrait"   --output /tmp/wall-side.jpg

# Apply with your desktop's per-monitor wallpaper command, for example:
# (placeholder — substitute the correct command for your environment)
# set-wallpaper --monitor 0 /tmp/wall-main.jpg
# set-wallpaper --monitor 1 /tmp/wall-side.jpg

Caution

The per-monitor wallpaper command is desktop-specific and left as a placeholder. GNOME, KDE Plasma, macOS and Windows each expose different mechanisms for setting a wallpaper on a specific display.

Tips

• Use aspect_ratio and orientation to match each monitor’s geometry.
• Use min_width/min_height to avoid upscaling a small image onto a large panel.
• Schedule the script with cron or a timer.

Related

• Filter reference
• Retrieving images