Reference: the .livewallpaper v1 format
Format version: 1 (frozen). Verified against PrimoEngine 0.4.9, macOS 26.
File layout
A ZIP (store or deflate compression) containing:
manifest.json required, at the root (or inside ONE single top-level folder)
content/ required, the wallpaper payload
thumbnail.png optional, thumbnail shown in the app (not covered by the checksum)
Other root files are ignored. The extension may be .livewallpaper or .zip.
manifest.json
| Field | Type | Req. | Notes |
|---|---|---|---|
schemaVersion | number | yes | Always 1. |
id | string | yes | Non-empty. Stable identity; importing another package with the same id replaces the installed one. Use reverse-DNS (com.yourname.name) or a UUID. |
version | string | yes | e.g. "1.0.0". Must be a string (not a number). |
title | string | yes | Non-empty. Shown in the app. |
author | object | no | { "id": string?, "handle": string? }. |
type | string | yes | "metal", "web" or "video". On Windows, shaders use "hlsl" instead of "metal": see Windows. |
entry | string | yes | Path of the main file from the package root, e.g. content/shader.metal. Must exist. |
minMacOS | string | no | e.g. "26.0". On an older Mac the import fails. Ignored on Windows. |
checksum | string | recommended | sha256-… over content/ (algorithm below). If present it must match, on import and on every load. |
config | array | no | User settings (table below). |
capabilities | object | no | Table below. |
Unknown fields are ignored. A .metal needs type: "metal", an .html type: "web", a video
type: "video". A mismatched type doesn’t fail the import, but the wallpaper renders black.
config[]
| Field | Type | Notes |
|---|---|---|
key | string | Required. Name of the value delivered to the wallpaper. |
type | string | float, int, bool, color. Anything else (including enum) is ignored. |
label | string | Control label. Default: key. |
min, max | number | float/int. Defaults 0 and 1. |
default | number / bool / string | float/int: number (default = min); bool: true/false (default false); color: "#RRGGBB" (default "#FFFFFF"). |
note | string | Optional small print under a bool switch, for what the setting costs or needs. |
int is shown as a continuous slider and delivered as a decimal number: round it in your code.
capabilities
| Field | Type | Notes |
|---|---|---|
network | array of strings | Declare []. Currently all network access is blocked for web wallpapers, even hosts listed here. Bundle everything. |
audio | bool | Reserved. Declare it honestly. Video always plays muted. |
nowPlaying | bool | Web only. When true the page receives the track playing in Music/Spotify (see below). |
pointer | string | Web only. The key of a bool config entry; while the user has it on, the page receives where the pointer is (see below). Anything else means no pointer. |
audioReactive | bool | Metal only. When true the shader receives a live summary of the Mac’s audio (see Audio-reactive shaders). |
Checksum algorithm (normative)
- Every regular file under
content/, path relative tocontent/, using/. - Sort by UTF-8 bytes, ascending.
- For each file, feed a SHA-256 with:
UTF-8 path+ one0x00byte +file bytes. - Result:
"sha256-" + lowercase hex.
import hashlib, os
def checksum(content_dir):
rels = sorted((os.path.relpath(os.path.join(r, f), content_dir).replace(os.sep, "/")
for r, _, fs in os.walk(content_dir) for f in fs if f != ".DS_Store"),
key=lambda p: p.encode())
h = hashlib.sha256()
for rel in rels:
h.update(rel.encode()); h.update(b"\0")
h.update(open(os.path.join(content_dir, rel), "rb").read())
return "sha256-" + h.hexdigest()
Careful: if the ZIP contains a .DS_Store inside content/, the app includes it in the hash.
Don’t ship one.
Metal contract
- A single
.metalfile of MSL source, compiled on the user’s Mac. - Required functions:
vertex … v_mainandfragment float4 f_main. - Uniforms at fragment
buffer(0), using exactly this struct (32 bytes):
struct Uniforms {
float2 resolution; // drawable pixels (Retina included)
float time; // seconds since start
float speed; // config "speed" (float), default 1.0
float4 tint; // config "tint" (color) as RGB 0..1, a = 1, default white
};
- There is no
frame,mouse, or any otherconfigvalue in the shader. The only texture is the audio history, for audio-reactive shaders. - The vertex stage draws 3 vertices (a full-screen triangle); use the guide’s
v_main. fragCoord.xyis in pixels, origin top-left.- Output is
bgra8Unorm, 8-bit, opaque. - Frame rate follows the display (ProMotion); the app throttles or pauses for battery/visibility.
Forbidden (textual check, case-sensitive, comments ignored):
| Text | Reason |
|---|---|
kernel / [[kernel | compute kernels are not allowed |
device | writable device buffers are not allowed |
threadgroup | threadgroup memory is not allowed |
atomic_ | atomic operations are not allowed |
#include " | local #include is not allowed (#include <metal_stdlib> is fine) |
Audio-reactive shaders
With "capabilities": { "audioReactive": true } a Metal wallpaper moves with whatever the Mac is
playing. The shader gets a summary of the sound, never the audio itself. The first time, macOS asks
the user to allow System Audio Recording; without it (and in silence) every value is 0.
Declare this struct exactly and read it at fragment buffer(1) (192 bytes):
struct AudioUniforms {
float bands[32]; // 30 Hz…16 kHz, log-spaced, 0..1, fast attack / slow release
float4 levels; // x bass, y mid, z treble, w overall level, 0..1
float beat; // 1 on a detected beat, decays to 0 in ~0.5 s
float bassTime; // seconds that run faster with the bass: ∫(0.1 + bass) dt
float levelTime; // ∫(0.2 + level) dt
float midTime; // ∫(0.05 + mid) dt
float4 beatAges; // seconds since the last 4 beats, newest first; 9 = none
float active; // eases to 0 after ~2 s of silence: show your still look
};
fragment float4 f_main(VOut in [[stage_in]],
constant Uniforms& u [[buffer(0)]],
constant AudioUniforms& audio [[buffer(1)]],
texture2d<float> history [[texture(0)]]) // optional
- Use the
*Timevalues instead oftimefor anything that should speed up with the music (rotation, scrolling, flow). They only ever grow, so motion never jumps backwards. history(optional) is the last ~2 s ofbands: 32 wide × 64 tall,rchannel, row 0 = now. Read it withhistory.read(uint2(band, row)).r.- Thumbnails, previews and the lock screen draw with everything at 0: design a good still look.
- Without the capability, a shader that mentions
buffer(1)is rejected at import. audiois a different, older field (the wallpaper plays sound); it does not enable this.
Web environment
entrymust be an.htmlfile. Theentry’s folder becomes the root served atlwp://wallpaper/; only files inside it (and subfolders) are reachable.- Served with the right MIME type: html, js/mjs, css, json, png, jpg, gif, webp, svg, mp4/m4v,
wasm, woff/woff2, ttf. Anything else is
application/octet-stream. - Blocked: all network,
file://, navigating away, camera/microphone/location. - Storage is ephemeral. No clicks or keyboard; the pointer position only with the
pointercapability. console.error/console.warnand uncaught errors go to the app log (see Debugging).- On import the app logs non-blocking warnings if it finds
fetch(,XMLHttpRequest,WebSocket,EventSource,importScripts,http://,https://,eval(,new Function(,atob(.
Page API:
window.LiveWallpaper.config // { key: value }, ready before your scripts run
window.LiveWallpaper.onConfig = cfg => { … } // called when the user changes settings
// Only with "capabilities": { "nowPlaying": true }
window.LiveWallpaper.onNowPlaying = np => { … }
// np = { isPlaying, title, artist, album, position, duration, source, artwork? }
// position/duration in seconds; artwork = data URI, sent only once per track; keep it.
// Only with "capabilities": { "pointer": "<bool key>" }, and only while that setting is on
window.LiveWallpaper.onPointer = p => { … }
// p = { x, y, inside } in the page's CSS pixels, top-left origin, sent when the pointer moves;
// x/y can fall outside the page (another display: inside = false). null when tracking stops.
Default the gating setting to false and give it a note: tracking means the page redraws as
the pointer moves, which costs CPU and battery.
Video
.mp4,.movor.m4v, decoded by macOS (HEVC/H.264). Gapless loop, muted, fills the screen (edges cropped). Noconfig.- Importing a bare video builds the package automatically (
idderived from the content; re-importing the same video replaces it instead of duplicating).
Limits
| Limit | Value |
|---|---|
| Size per file (uncompressed) | 256 MB |
| Files per package | 4096 |
| Paths | no .., no leading / |
Plans
| Free | Premium | |
|---|---|---|
Import/share metal and web wallpapers | ✅ | ✅ |
video wallpapers | ❌ | ✅ |
Errors
Exact messages as shown in the “Could not import wallpaper” alert, and how to fix each. The two “The data couldn’t be read…” messages come from macOS and may appear in your system language.
| Message | Cause / fix |
|---|---|
Not a valid .livewallpaper (ZIP) file. | Not a ZIP (or truncated). Rebuild with pack.py. |
Corrupt archive: unsafe path '…'. | A path contains .. or starts with /. |
Corrupt archive: unsupported compression method N. | Use store or deflate (the default for zip and pack.py). |
Corrupt archive: … (other) | Damaged ZIP. Rebuild it. |
Archive or an entry exceeds the size limit. | A file > 256 MB, or more than 4096 files. |
Package has no manifest.json. | manifest.json isn’t at the ZIP root. Zip the folder’s contents, not a folder with Finder junk (__MACOSX). |
The data couldn't be read because it is missing. | A required field is missing: schemaVersion, id, version, title, type, entry (or key/type in a config entry). |
The data couldn't be read because it isn't in the correct format. | Invalid JSON or wrong type: trailing comma, "schemaVersion": "1", "version": 1, type not metal/web/video, min as a string… |
Unsupported manifest schemaVersion N (expected 1). | Use "schemaVersion": 1. |
Manifest field 'id' is missing or empty. (or title, entry) | Fill in the field. |
Wallpaper requires macOS X, which is newer than this system. | Lower minMacOS (e.g. "26.0") or remove it. |
Package checksum does not match its content (possibly corrupt or tampered). | You changed content/ after computing the checksum, or the ZIP has a .DS_Store. Re-run pack.py. |
Package entry file '…' is missing. | entry doesn’t point to an existing file. It must include content/ and match case. |
Shader rejected: … . | A forbidden construct (Metal table above). Remove/rename it. |
Shader is missing the required 'f_main' fragment function. | Name the fragment function f_main. |
Shader reads audio ([[buffer(1)]]) but the manifest doesn't declare "capabilities": { "audioReactive": true }. | Add the capability, or remove buffer(1). |
“.ext” isn't a supported video (use .mp4, .mov or .m4v). | Convert the video. |
That video is N MB — the limit is 256 MB. | Compress (HEVC) or shorten it. |
Silent failures (imports fine, but black/static):
- Metal fails to compile, or
v_mainis missing → black. Change a little at a time. typedoesn’t match the file → black.- Web: a JavaScript error, an asset outside the
entry’s folder, or anything fetched from the internet (blocked).
Debugging
Watch the app log in Terminal while the wallpaper runs:
log stream --level info --predicate 'subsystem == "com.livewallpaper.app"'
Look for Shader compile/pipeline failed (Metal compile error, with line number) and messages in
the WebConsole category (JavaScript errors).