The binary inside the app bundle is the CLI. Add an alias, because the real path is a mouthful:

Settings live in a dedicated preferences domain (com.dfacto.videowallpaper.settings) rather than the standard one. That is deliberate: standard defaults are keyed by bundle id inside the .app and by executable name for a bare binary, so the two would silently keep separate settings.

Installing registers a LaunchAgent at ~/Library/LaunchAgents/com.dfacto.videowallpaper.plist.

• RunAtLoad — starts at every login, including after a reboot.
• KeepAlive {SuccessfulExit: false} — a crash or a kill comes back within about ten seconds. Choosing Quit stays quit until next login. That asymmetry is deliberate: a crash should heal itself, but Quit should mean quit.
• It appears in System Settings › General › Login Itemsunder “Allow in the Background”.

Only one copy ever runs. A second launch — double-clicking the app while the login item is running — exits immediately rather than stacking a second wallpaper and a second menu bar icon.

What the table actually says

While you can see it, this costs roughly one core in total, and about three quarters of that is WindowServer compositing rather than anything this app runs. A live wallpaper on a 120 Hz Retina panel is not a free thing to want, and a page that told you otherwise would be lying by omission.

Covered, all three processes fall to near idle — the decoder stops, the app stops feeding it, and WindowServer has nothing to composite. That is the state your Mac is in for most of a working day, which is the entire argument for using this rather than a wallpaper that runs regardless.

Covering one or two of three screens saves nothing measurable, and that is not a defect — it is the direct consequence of the thing that makes extra displays nearly free. There is one decoder. It stops when the last visible desktop is covered, because until then it is still producing frames somebody can see.

On a single display — the free tier, and most laptops — that distinction disappears: covering the desktop is covering everything.

What buys that

• Stop when nothing can see it. Each window watches its own occlusion state; when none of them is visible, decoding stops. macOS reports a window as occluded only when it is fully covered by opaque windows, so a half-covering window or a transparent terminal keeps it running.
• One decode for every display.The clip is decoded once and the same frame is drawn on each screen at that screen’s own size and refresh rate. One display and three measured within a few percent of each other on every process — the cost is close to flat in screen count, which is what the Pro tier is actually selling.
• Deferred swaps. If nothing is visible when the interval fires, the swap is skipped rather than decoding a new 4K clip for nobody.
• No display-sleep lock. AVPlayer holds the display awake during playback by default; that is switched off.
• Coalesced timers and debounced display rebuilds, so an idle Mac is not woken by the wallpaper and a monitor replug does not cause a rebuild storm.

The honest caveat

While a desktop is visible this is not free, and no live wallpaper can be. The claim is narrower and checkable: it costs almost nothing when nothing can see it, and extra displays are close to free. Figures also vary a lot by clip — a high-bitrate 4K aerial costs materially more than a calm one, so treat these as one machine’s numbers rather than a spec.

Reproducing it

Sample ps -o time= for videowallpaper, VTDecoderXPCService and WindowServer across a fixed window and divide by the elapsed seconds. Give it ten seconds to settle after covering or uncovering — the first few seconds include the transition and will read high. tail -f ~/Library/Logs/videowallpaper.log prints paused (covered) and resumed, so you can see exactly when it stopped.

The repository’s README carries a different measurement: a controlled build-to-build comparison on one fixed clip, showing what the shared decode and the display-native pipeline each removed. Use that for “did the optimisation work” and this table for “what does it cost me”.

A licence is an Ed25519-signed token that looks like VW1.<payload>.<signature>. The app verifies it against a public key compiled into the binary. It never contacts a payment provider, which has three consequences worth stating plainly:

• A provider outage or account freeze cannot lock out paying customers.
• Switching merchant of record needs no client release and no re-issued tokens.
• It works with no network at all.

The trade-off, stated honestly: an offline-verifiable token is inherently copyable. Device limits (3 on Pro, 10 per Studio seat) are carried in the token and enforced honestly rather than aggressively. We think that is the right side to err on for a wallpaper.

If a subscription lapses, the app returns to the free tier — one display, one folder — and keeps running. Nothing is deleted and no settings are lost. It re-checks the token on every swap, so a renewal takes effect without a restart.