What it does

Plays any video file as your desktop wallpaper — looped, fullscreen, behind all your icons and windows. Works across all connected monitors. Pauses when you lock your screen, resumes when you unlock. Keeps playing after sleep/wake and monitor hotplug.

# Set a video
dynawall set ~/Movies/cyberpunk-city-4k.mp4

# Go
dynawall start

# Shuffle a random video from your collection
dynawall random ~/Wallpapers/

# Check status
dynawall status
# running  video=/Users/you/Wallpapers/aurora-4k.mp4

Install

macOS 12+ + Xcode CLI Tools (xcode-select --install)

# Try it now — no install needed
npx dynawall set ~/path/to/video.mp4
npx dynawall start

# Or install globally
npm i -g dynawall

All commands

dynawall set <video>       # Choose a video file
dynawall start             # Start wallpaper
dynawall stop              # Stop wallpaper
dynawall restart           # Restart (pick up new video after set)
dynawall random <dir>      # Random video from a folder
dynawall status            # Running? Which video?
dynawall list              # View video history

Multi-monitor

Each connected display gets its own fullscreen video window. Plug in a new monitor? It auto-detects and adds a window. Unplug? Cleanly removes it. No config needed.

Lock screen behavior

• Lock → video pauses (saves battery on laptops)
• Unlock → video resumes from where it stopped
• Sleep → gracefully tears down
• Wake → rebuilds and resumes

Random wallpaper

Got a folder full of 4K wallpapers? Point dynawall at it:

dynawall random ~/Wallpapers/

Supports MP4, MOV, M4V, MKV, WebM. Picks one at random, sets it, and if already running, restarts with the new video.

Pro tip — random wallpaper on login:

echo 'dynawall random ~/Wallpapers/ && dynawall start' >> ~/.zprofile

How it works

  you run: npx dynawall start
                │
                ▼
         ┌──────────┐
         │  cli.js   │  Node.js CLI — parses args, manages process
         └─────┬────┘
               │ spawns
               ▼
   ┌───────────────────┐
   │   dynawall-core    │  Compiled from WallpaperCore.swift
   │                     │
   │  • NSWindow per    │  Borderless window at desktop level
   │    monitor          │
   │  • AVPlayer loop   │  Hardware-accelerated video playback
   │  • Health timer    │  Auto-recovers if playback stalls
   │  • Event listener  │  Screen/sleep/wake/lock/unlock
   └───────────────────┘

No Electron. No WebKit. Pure macOS native APIs — AVPlayer + NSWindow + NSWorkspace.

Source-transparent

The entire native core is one file: WallpaperCore.swift — 135 lines. It compiles on your machine during npm install using your local swiftc. No pre-built binaries. No binary blobs. Read it, audit it, compile it yourself.

Requirements

• macOS 12+ (Monterey / Ventura / Sonoma / Sequoia)
• Xcode Command Line Tools
• Node.js 16+

License

MIT