Windows Wallpaper Auto-Downloader (Unsplash)

This project downloads a small daily batch of Unsplash images, rejects bright images, and copies accepted files into your slideshow folder.

Project docs

• AGENTS.md: role-based architecture and responsibilities.
• SKILLS.md: practical operation/tuning skills and command quick reference.

Features

• Uses Unsplash API (/photos/random) for automatic wallpaper downloads.
• Can also import wallpapers from local Windows Spotlight assets.
• Configurable image types via Queries and API parameters.
• Filters for monitor-friendly ratios (16:9, 16:10 by default) and rejects non-matching images.
• Brightness filtering removes light-themed images from both Unsplash and Spotlight sources.
• Saves files to archive + slideshow folders.
• Auto-syncs archive and slideshow folders for tracked files (repairs accidental manual deletions).
• Auto-removes old downloaded wallpapers (default retention: 7 days).
• Daily automation via Windows Task Scheduler.

1) Setup

1. Copy config template:
   • Copy-Item .\config.sample.json .\config.json
2. Configure using the TUI app (recommended):
   • powershell -NoProfile -ExecutionPolicy Bypass -File .\config-tui.ps1 -ConfigPath .\config.json
3. Or edit config.json manually:
   • Set Paths.SlideshowFolder to your real slideshow directory (for example: C:/Users/<you>/Pictures/Wallpapers).
   • Tune Unsplash.Queries, batch size, and filter values.
   • Optional Spotlight source settings live under WindowsSpotlight.
   • Tune cleanup retention via Cleanup.RetentionDays (default 7).
4. Set Unsplash API key in your user environment:
   • setx UNSPLASH_ACCESS_KEY "your_access_key_here"
5. Open a new terminal so the env var is available.

2) Run manually

powershell -NoProfile -ExecutionPolicy Bypass -File .\wallpaper-fetch.ps1 -ConfigPath .\config.json

TUI launcher:

powershell -NoProfile -ExecutionPolicy Bypass -File .\config-tui.ps1 -ConfigPath .\config.json

TUI quick keys:

• U Unsplash settings
• W Windows Spotlight settings
• A Add new query
• M Remove query
• F Filter settings
• P Path settings
• S Schedule settings
• C Cleanup settings
• K Set API key
• G Guided setup wizard
• V Save config
• D Dry-run now
• R Run fetch now
• I Install/update scheduled task
• X Remove scheduled task
• L Reload config
• Q Quit

Dry-run config check:

powershell -NoProfile -ExecutionPolicy Bypass -File .\wallpaper-fetch.ps1 -ConfigPath .\config.json -DryRun

3) Install daily schedule

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-daily-task.ps1 -ConfigPath .\config.json

Optional custom task name:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-daily-task.ps1 -ConfigPath .\config.json -TaskName "MyWallpaperJob"

Remove task:

powershell -NoProfile -ExecutionPolicy Bypass -File .\uninstall-daily-task.ps1 -TaskName "UnsplashWallpaperDaily"

Notes on filtering

• TargetAspectRatios: defaults include:
  • 1.7778 (16:9)
  • 1.6 (16:10)
• MaxAverageLuminance: lower value means darker overall images only.
• MaxBrightPixelRatio: limits how much of an image can be very bright.
• MinWidth and MinHeight: prevent low-resolution downloads.

Windows Spotlight source

• WindowsSpotlight.Enabled: enable/disable Spotlight import.
• WindowsSpotlight.AssetsPath: optional custom assets path; blank uses the default Windows Spotlight folder.
• WindowsSpotlight.MaxCandidatesPerRun: how many spotlight files to scan per run.
• WindowsSpotlight.MinFileSizeKB: skips tiny/non-wallpaper assets.

Notes on cleanup

• Cleanup.Enabled: turn old-file cleanup on or off.
• Cleanup.RetentionDays: remove wallpapers older than this many days.
• Cleanup.MaxFileCount: keep only this many latest wallpapers (default 50, use 0 to disable count-based cleanup).
• Cleanup removes only images tracked in this app state file.

Windows slideshow

After setting your slideshow folder in Windows Personalization settings, this script keeps that folder updated with newly approved images.