by cwizou | 2025-09-15 16:04:19+00:00
Awesome stuff !

I've been trying to make a library/cli to set the wallpaper/screensaver to use in the next version of Aerial (https://github.com/AerialScreensaver/PaperSaver) on individual screens and been toying around a lot with that whole WallpaperAgent subsystem (and obviously everything Aerial like the manifests, etc, before that), so I may have some insights/questions if you have time ?

From what I've seen there are multiple parts to the way that macOS subsystem works :

- Apple fetches the manifest (json file) with their own videos in (only) 240FPS

- It gets ingested in '/Library/Application Support/com.apple.idleassetsd/Aerial.sqlite' for some reason

- Apple pulls the videos in '/Library/Application Support/com.apple.idleassetsd/Customer/4KSDR240FPS' but renames them through a UUID (despite them having individual keys in the JSON)

Adding videos and sections in System Settings, you can do by manipulating that sqlite and killing WallpaperAgent (or maybe something else) before doing it, but as far as I remember (I only toyed with that part last year during Sequoia beta, so probably misremembering), macOS will periodically pull the manifest again and (fairly often) erase all your changes.

As far as I know, what you select then gets saved per screen/space in `~/Library/Application\ Support/com.apple.wallpaper/Store/Index.plist` (with a lovely Base-64 coding thrown in for fun).

The last part to this is a SystemWallpaperURL key stored in `~/Library/Preferences/com.apple.wallpaper.plist` which I believe (not 100% sure), contains the "special" video that gets played on a cold boot login (as far as I know it's a separate state from the "classic" Lock Screen).

So if I may :

- Do your videos show up on a cold boot too (that separate state I mentionned?) or just the "classic" Lock Screen? My rough guess is the cold boot lock screen can only display videos that are on the System Volume that's mounted before the user volume, so that one is probably fully out of reach.

- How hard did you have to workaround working with restricted paths ? Apple (for some good reasons) restricts hard access to files in user folders, and at that point the only safe place I can reasonably find (outside of containers, but that's a whole other story with screensavers) is `/Users/Shared`. Are you using that folder too?

- Are you messing with the sqlite db, or are you injecting via a reversed engineered api?

- Did you try editing `~/Library/Application\ Support/com.apple.wallpaper/Store/Index.plist` to set your video wallpapers or are you just relying on them being integrated in System Settings?

Since Sequoia, right now Apple broke the way we could set a screensaver via terminal. I got that part working (setting per screen/space) in PaperSaver, but the wallpaper part (basically just switching to another user selected image, not even a video, but this has to be done per space for which we don't have a public api for), I can't seem to get quite right yet, so any insight you have on that would be welcome. Take care and again awesome effort on your launch, this is a non trivial system with so many pitfalls, it takes a bunch of dedication to make it work with so many subtle problems in every corner.