Skip to content

About

Free, open-source live wallpaper app for macOS. Use a video or an endlessly scrolling image as your desktop wallpaper, a lightweight Wallpaper Engine alternative for Mac.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

19 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

VideoWallpaper

Build

A free, open-source live wallpaper app for macOS. It sets a video (MP4, MOV) or an endlessly scrolling image as your desktop wallpaper, from the menu bar.

Wallpaper Engine only runs on Windows. VideoWallpaper is a lightweight way to get animated wallpapers on a Mac, and it can play wallpapers from Wallpaper Engine (see below).

Built to use as little CPU, GPU and battery as possible:

  • It pauses automatically when nothing can see the desktop:
    • a fullscreen app or a window covering it entirely;
    • a locked or sleeping screen;
    • fast user switching.
  • Videos use hardware decoding, play muted, and never prevent display sleep.
  • Images are animated with Core Animation. The window server renders the motion, so the app does no per-frame work, and no animation stays attached while paused.
  • With multiple displays, every screen shares the same player or image.

Requirements

  • macOS 13 or later, on Apple Silicon
  • To build from source: Xcode or the Command Line Tools (xcode-select --install)

Install

Download

Grab VideoWallpaper.zip from the latest release, unzip it and move VideoWallpaper.app to /Applications.

The app isn't notarized by Apple, so macOS blocks it the first time. To open it anyway, try to open it once, then go to System Settings → Privacy & Security and click Open Anyway. Or run:

xattr -dr com.apple.quarantine /Applications/VideoWallpaper.app

Build from source

./build.sh install

This builds the app, copies it to /Applications and launches it. On first launch it asks you to pick a wallpaper and registers itself to open at login.

To build without installing, run ./build.sh. The app ends up in build/VideoWallpaper.app.

Usage

Everything lives in the ▶︎ menu bar icon:

Item What it does
Choose Wallpaper… Pick a video (MP4, MOV) or an image (PNG, JPG)
Pause / Resume Pause or resume manually
Speed Change playback or scroll speed
Open at Login Toggle launch at login
Quit Quit

The app remembers the chosen file and its speed. Videos and images keep separate speed settings.

Scrolling images

The image is scaled to the full screen height, tiled horizontally and scrolled left forever. For the seam to be invisible, the image's left and right edges should match up.

At 1× the scroll speed matches Wallpaper Engine's Scroll effect with speedx 0.015, which takes about 74 minutes per full lap. The menu offers 0.5× to 15×.

Videos

For the lowest power use, encode videos as H.264 or HEVC at your display's resolution. A higher resolution won't look sharper and only costs extra GPU. The menu offers 0.25× to 1×. Slowing down a 30 fps video looks choppy, so use 60 fps footage for slow motion.

Using Wallpaper Engine wallpapers

Video wallpapers ship an .mp4 that works as is. Scene wallpapers (scene.pkg) aren't videos. If the scene is a single image with the Scroll effect, you can extract that image:

  1. Get the PNG. The scene.pkg bundles .tex files. For scenes like this, the main .tex (e.g. materials/<name>.tex) has a PNG embedded in it. Copy the bytes from the \x89PNG signature through the IEND chunk.
  2. Get the original speed. It's in scene.json, under effects → passes → constantshadervalues → speedx.

Engine-specific effects such as particles are not reproduced. Workshop wallpapers belong to their creators, so use them only for yourself.

VideoWallpaper isn't affiliated with Wallpaper Engine or its developers.

How it works

All the code lives in Sources/main.swift:

  • WallpaperWindow: a borderless window at desktop level (below the icons). It's on every Space and ignores the mouse.
  • VideoSource: AVQueuePlayer + AVPlayerLooper for gapless looping.
  • ScrollingImageSource: tiles the image into a strip and moves it with an infinite CABasicAnimation. When paused, it saves the scroll phase and removes the animation.
  • AppDelegate handles three things:
    • The menu.
    • Pause logic. It watches window occlusion (debounced by 0.3 s), screen lock, display sleep and session changes.
    • Launch at login, through SMAppService.
    • The system desktop picture. When you switch Spaces, macOS shows the system picture for about a second before it draws the wallpaper window. The app sets that picture to a still of the wallpaper (stored in ~/Library/Application Support/VideoWallpaper/Desktop) on every Space you visit, so the switch looks seamless. This replaces your previous desktop picture.

Preferences are stored in the com.jaimeerrazuriz.videowallpaper defaults domain (defaults read com.jaimeerrazuriz.videowallpaper).

License

MIT

About

Free, open-source live wallpaper app for macOS. Use a video or an endlessly scrolling image as your desktop wallpaper, a lightweight Wallpaper Engine alternative for Mac.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages