Video and Web Internals

Video and web internals

How video and web wallpapers are played: the AVKit path, the Metal video path, WebKit for WebM, and the web wallpaper bridge. Code lives in Video/ and Web/.

Video

Path	When	Components
AVKit (default)	MP4, MOV, M4V with Video Framework = Apple AVKit	VideoWallpaperViewModel (one decoding player and one audio player per video), WallpaperAVPlayer, VideoWallpaperView (each display's AVPlayerView shows the shared player)
Metal (experimental)	Video Framework = Metal	VideoTextureStream publishes decoded frames as Metal textures so the scene renderer draws the video, as WE draws video through its scene pipeline (a video texture on a genericimage material); effects and music sync apply
WebKit	A local WebM (VP8/VP9) that AVFoundation reports it can't play	WebKitVideoPlayer, WebKitVideoWallpaperView: the file opens as WebKit's media document with read access limited to its wallpaper folder, no network. Placement is styled on the <video>; playback state is re-applied until the document has one. Music sync applies as on the AVKit path. With the Chromium engine installed and routing web content, the same player runs in a Chromium page (ChromiumVideoWallpaperView).

• Music sync (VideoMusicSync): zoom, tilt, saturation and pace amounts, routed so both SwiftUI and the renderer see changes at once.
• VideoPlaybackProbe reports how far playback advanced and frames dropped, once a second, to the render watchdog without copying frames.
• Each video wallpaper plays its sound once, however many displays show it; different wallpapers on different displays each play theirs (WallpaperAudioRouting).

Web

Component	Role
WebWallpaperViewModel, WebWallpaperView	The WKWebView, lifecycle, sleep/wake, pausing (setPaused, media suspended)
WebEngineRouting	WebKit plays web wallpapers by default; with the optional Chromium engine installed, wallpapers that use a Chromium-only API (or whose details choose it) play in Chromium (Web/Chromium)
WebWallpaperSchemeHandler	Serves the wallpaper's files, confined to its folder, so WebGL textures and assets load
WebWallpaperPropertyBridge	wallpaperPropertyListener.applyUserProperties with WE's value shapes, and the audio listener's 128 values (clamped 0…1)
WebWallpaperMediaBridge	wallpaperRegisterMedia…Listener and window.wallpaperMediaIntegration, in WE's shapes (status, properties, thumbnail, playback, timeline)
WebPageAudio	Mutes pages on non-audible displays
WebHeartbeatGate	Pages post heartbeats to the watchdog only while visible and playing, since WebKit throttles hidden pages' timers
WebCompatPatches	Applies WE's own compatibility patches (from the assets' zcompat) to the Workshop items they are written for

Each display keeps its own page (a WKWebView can't be in two windows); only the audible display's page plays sound.

With Adjust Menu Bar Color on, a snapshot of the page is set as the macOS desktop picture of its display, so the menu bar tint matches.

User guide: Video wallpapers and Web wallpapers