🎬 Custom Aerial Screensaver for macOS Sequoia & Tahoe

Automating corporate deployment via JumpCloud MDM

Starting from macOS Sequoia and continued in Tahoe, Apple changed how screensavers and animated wallpapers (Aerial) are stored and loaded.

The new WallpaperKit framework does not use the classic system directories previously documented in the Aerial project, which makes corporate customization challenging — especially for admins using MDM solutions.

This guide documents the correct storage path, how to replace the default Aerial video, and how to automate deployment at scale using JumpCloud.

This information is not available in Apple’s official documentation.

---

🚀 1. Where macOS stores Aerial screensaver videos in Sequoia/Tahoe

After investigation and reverse-engineering behavior of WallpaperKit, the actual storage path for Aerial assets is:

/Users/<username>/Library/Application Support/com.apple.wallpaper/aerials/videos/

Inside this folder, each Aerial video is stored as a .mov file with a UUID filename, for example:

4C108785-A7BA-422E-9C79-B0129F1D5550.mov

⚠️ Important notes

• The directory is per user, not system-wide.
• Running scripts as root will target /var/root/Library, not the user’s Library.
• WallpaperKit requires restarting WallpaperAgent to apply changes.
• UUIDs may differ depending on which Aerial scene the user selected.

---

🔧 2. How to replace the screensaver video with a custom file

The script below:

• Detects the currently logged-in user
• Locates the correct Aerial directory
• Downloads and replaces the target .mov
• Fixes permissions
• Restarts WallpaperAgent
• Works on all Sequoia/Tahoe installations
• Is fully compatible with MDM deployment

---

🟦 Replacement Script (ready for JumpCloud)

#!/bin/bash

# URL of the custom Aerial video
URL="https://yourserver.com/custom-aerial.mov"

# Detect currently logged-in user
TARGET_USER=$(stat -f "%Su" /dev/console)
USER_HOME="/Users/$TARGET_USER"

# Aerial video directory (WallpaperKit)
DEST_DIR="$USER_HOME/Library/Application Support/com.apple.wallpaper/aerials/videos"

# Name of the video UUID you want to replace
TARGET_FILE="4C108785-A7BA-422E-9C79-B0129F1D5550.mov"

FULL_PATH="$DEST_DIR/$TARGET_FILE"

echo "Logged-in user: $TARGET_USER"
echo "Target directory: $DEST_DIR"

# Ensure directory exists
mkdir -p "$DEST_DIR"

# Fix permissions
chown -R "$TARGET_USER":staff "$USER_HOME/Library/Application Support/com.apple.wallpaper"

# Backup existing file
if [ -f "$FULL_PATH" ]; then
    mv "$FULL_PATH" "${FULL_PATH}.backup"
fi

echo "Downloading custom video..."
curl -L -o "$FULL_PATH" "$URL"

# Fix ownership
chown "$TARGET_USER":staff "$FULL_PATH"

# Restart WallpaperAgent to apply
echo "Restarting WallpaperAgent..."
pkill -f WallpaperAgent 2>/dev/null

echo "✔ Custom Aerial screensaver applied successfully." 

---

# 🖥️ 3. Deploying this at scale using JumpCloud
 
This script is designed for MDM automation.

In JumpCloud:

Commands → Mac → Add Command

Paste the script

Set Run as: Logged-in User

Assign to device groups

(Optional) Schedule:

on user login

on device enrollment

nightly enforcement

Recommended hosting options for the video:

AWS S3 (public or signed URL)

Google Cloud Storage

GitHub Raw

Internal HTTPS server

# 🧠 4. Technical Notes
✔ WallpaperKit stores assets inside the user Library

There is no shared system path for Aerial screensavers.

✔ The Aerial ".mov" UUID identifies the selected scene

You can find the current video with:

ls ~/Library/Application\ Support/com.apple.wallpaper/aerials/videos/

✔ WallpaperAgent must be restarted

Otherwise the system keeps the old video in memory.

✔ Works across Sequoia / Tahoe

The behavior is consistent in both OS releases.