Skip to content

LockScreen.md

Latest commit

 

History

History
64 lines (47 loc) · 2.38 KB

LockScreen.md

File metadata and controls

64 lines (47 loc) · 2.38 KB
Raw

Experimental Animated Lock Screen

Last reviewed: 2026-07-27

Status

CrystalSpace direct builds support an experimental animated Lock Screen on macOS 26. Sandboxed builds report the feature unavailable.

Apple exposes no public animated Lock Screen setter API. This provider uses the reversible user-level aerial-slot technique demonstrated by the MIT-licensed Wallpaper-Sync project. CrystalSpace implements the mechanism natively in Swift and does not install Python, ffmpeg, a LaunchAgent, a privileged helper, or Accessibility automation.

Requirements

  1. macOS 26 or newer.
  2. A direct, unsandboxed CrystalSpace build.
  3. An Apple animated aerial selected and downloaded in System Settings → Wallpaper.
  4. A downloaded or imported CrystalSpace video.

Apply transaction

  1. Resolve the CrystalSpace local video without modifying the original.
  2. Create a managed HEVC hvc1 MOV using AVFoundation/VideoToolbox.
  3. Read the selected aerial assetID from the current macOS 26 com.apple.wallpaper/Store/Index.plist.
  4. Validate the selected downloaded aerial.
  5. Create and validate a persistent original-aerial backup.
  6. Save recovery state before changing Apple-managed files.
  7. Atomically replace the selected aerial video.
  8. Mirror the already-selected Desktop aerial configuration into Idle.
  9. Restart WallpaperAgent and WallpaperAerialsExtension.

If any step after recovery-state creation fails, CrystalSpace attempts an automatic rollback. The desktop wallpaper engine is independent and remains usable.

Restore

Settings → Lock Screen → Restore Original Apple Aerial restores the validated video backup. CrystalSpace restores the previous wallpaper index only when the index still matches the version it wrote. If System Settings or macOS changed the index afterward, that newer configuration is preserved.

Distribution

Scripts/build-app.sh accepts:

zsh Scripts/build-app.sh release direct
zsh Scripts/build-app.sh release sandboxed

direct is the default and enables the experimental provider. sandboxed preserves App Sandbox compatibility and disables it.

Compatibility warning

The wallpaper-store format is undocumented and may change in a macOS update. The provider validates the currently observed Tahoe assetID schema and fails closed when the expected Desktop aerial configuration is absent.