Referência: formato .livewallpaper v1

Versão do formato: 1 (congelada). Testado com PrimoEngine 0.4.11, macOS 26.

Estrutura do arquivo

Um ZIP (compressão store ou deflate) com:

manifest.json      obrigatório, na raiz (ou dentro de UMA única pasta de topo)
content/           obrigatório, o conteúdo do wallpaper
thumbnail.png      opcional, miniatura mostrada no app (fora do checksum)

Arquivos extras na raiz são ignorados. A extensão pode ser .livewallpaper ou .zip.

manifest.json

Campos desconhecidos são ignorados. Um .metal precisa ser type: "metal", um .html type: "web", um vídeo type: "video". Tipo errado não dá erro na importação, mas o wallpaper fica preto.

config[]

int é mostrado como slider contínuo e entregue como número decimal: arredonde no seu código.

capabilities

Algoritmo do checksum (normativo)

1. Todos os arquivos regulares sob content/, com caminho relativo a content/ usando /.
2. Ordene por bytes UTF-8 crescentes.
3. SHA-256 alimentado, para cada arquivo, com: caminho UTF-8 + byte 0x00 + bytes do arquivo.
4. Resultado: "sha256-" + hex minúsculo.

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()

Atenção: se o ZIP tiver um .DS_Store dentro de content/, ele entra no cálculo do app. Não o inclua.

Contrato Metal

• Arquivo .metal único com código-fonte MSL, compilado no Mac do usuário.
• Funções obrigatórias: vertex … v_main e fragment float4 f_main.
• Uniforms no buffer(0) do fragmento, com a struct exatamente assim (32 bytes):

struct Uniforms {
    float2 resolution;   // pixels do drawable (inclui Retina)
    float  time;         // segundos desde o início
    float  speed;        // config "speed" (float), padrão 1.0
    float4 tint;         // config "tint" (color) em RGB 0..1, a = 1, padrão branco
};

• Não existem frame, mouse, texturas nem outros valores de config no shader.
• O vértice desenha 3 vértices (triângulo de tela cheia); use o v_main do guia.
• fragCoord.xy em pixels, origem no canto superior esquerdo.
• Saída em bgra8Unorm, 8 bits, opaca.
• Taxa de quadros: segue a tela (ProMotion); o app reduz ou pausa por bateria/visibilidade.

Proibido (checagem textual, sensível a maiúsculas, comentários ignorados):

Ambiente web

• entry deve ser um .html. A pasta do entry vira a raiz servida em lwp://wallpaper/; só arquivos dentro dela (e subpastas) são acessíveis.
• Tipos servidos com MIME correto: html, js/mjs, css, json, png, jpg, gif, webp, svg, mp4/m4v, wasm, woff/woff2, ttf. Outros saem como application/octet-stream.
• Bloqueado: toda rede, file://, navegação para outra página, câmera/microfone/localização.
• Dados não persistem (armazenamento efêmero). Sem mouse/teclado.
• console.error/console.warn e erros não tratados vão para o log do app (ver Depuração).
• Na importação, o app registra avisos (não bloqueiam) se encontrar fetch(, XMLHttpRequest, WebSocket, EventSource, importScripts, http://, https://, eval(, new Function(, atob(.

API da página:

window.LiveWallpaper.config          // { key: valor }, pronto antes dos seus scripts
window.LiveWallpaper.onConfig = cfg => { … }        // chamado quando o usuário muda ajustes

// Só com "capabilities": { "nowPlaying": true }
window.LiveWallpaper.onNowPlaying = np => { … }
// np = { isPlaying, title, artist, album, position, duration, source, artwork? }
// position/duration em segundos; artwork = data URI, enviado só uma vez por faixa; guarde-o.

Vídeo

• .mp4, .mov ou .m4v, decodificado pelo macOS (HEVC/H.264). Loop sem emenda, mudo, preenche a tela (corta bordas). Sem config.
• Importar um vídeo solto cria o pacote automaticamente (id derivado do conteúdo: importar o mesmo vídeo de novo substitui em vez de duplicar).

Limites

Planos

Erros

Mensagens exatas, como aparecem no alerta “Could not import wallpaper”, e como resolver. As duas mensagens “The data couldn’t be read…” vêm do macOS e podem aparecer no idioma do sistema (ex.: “Não foi possível ler os dados…”).

Falhas silenciosas (importa, mas fica preto/parado):

• Metal não compila, ou falta v_main → preto. Teste pequenas mudanças de cada vez.
• type não corresponde ao arquivo → preto.
• Web: erro de JavaScript, asset referenciado fora da pasta do entry, ou algo buscado na internet (bloqueado).

Depuração

Veja o log do app no Terminal enquanto o wallpaper roda:

log stream --level info --predicate 'subsystem == "com.livewallpaper.app"'

Procure Shader compile/pipeline failed (erro de compilação Metal, com linha) e mensagens da categoria WebConsole (erros de JavaScript).