Getting Started

Random Video Wallpaper runs local videos behind your normal macOS windows. This guide gets you from a fresh clone to a running wallpaper.

Requirements

Install the command line tools if needed:

xcode-select --install

git clone https://github.com/Sunwood-ai-labs/random-video-wallpaper-macos.git
cd random-video-wallpaper-macos

Start the menu bar app:

scripts/run-video-wallpaper

Choose videos or a folder from the status menu. You can also pass a folder containing videos:

scripts/run-video-wallpaper ~/Movies/wallpapers

Pass files or globs:

scripts/run-video-wallpaper ~/Downloads/vending-stigmata-loop-*.mp4

The helper script builds the release executable, creates a tiny local .app bundle, and launches it in the background.

scripts/stop-video-wallpaper

Use --check when you want to confirm that files are found without starting the desktop wallpaper:

.build/release/random-video-wallpaper --check ~/Movies/wallpapers