Reference: the .livewallpaper v1 format

Format version: 1 (frozen). Verified against PrimoEngine 0.4.11, 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

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[]

int is shown as a continuous slider and delivered as a decimal number: round it in your code.

capabilities

Checksum algorithm (normative)

1. Every regular file under content/, path relative to content/, using /.
2. Sort by UTF-8 bytes, ascending.
3. For each file, feed a SHA-256 with: UTF-8 path + one 0x00 byte + file bytes.
4. 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 .metal file of MSL source, compiled on the user’s Mac.
• Required functions: vertex … v_main and fragment 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, texture, or any other config value in the shader.
• The vertex stage draws 3 vertices (a full-screen triangle); use the guide’s v_main.
• fragCoord.xy is 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):

Web environment

• entry must be an .html file. The entry’s folder becomes the root served at lwp://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 mouse/keyboard input.
• console.error/console.warn and 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.

Video

• .mp4, .mov or .m4v, decoded by macOS (HEVC/H.264). Gapless loop, muted, fills the screen (edges cropped). No config.
• Importing a bare video builds the package automatically (id derived from the content; re-importing the same video replaces it instead of duplicating).

Limits

Plans

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.

Silent failures (imports fine, but black/static):

• Metal fails to compile, or v_main is missing → black. Change a little at a time.
• type doesn’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).