@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/model/bench.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const ENTRYPOINT = 'entrypoint.py';
+export function findBench(env = process.env, here = import.meta.dirname) {
+    const tried = [
+        env.FUNPIXEL_BENCH_DIR,
+        resolve(here, '..', '..', 'bench'),
+        resolve(here, '..', '..', '..', '..', 'crates', 'funpixel-blender', 'py'),
+    ].filter((d) => !!d);
+    const dir = tried.find((d) => existsSync(join(d, ENTRYPOINT)));
+    if (dir)
+        return { dir };
+    return {
+        missing: "the Blender bench scripts are missing from this funtools install (they ship in its bench/ folder) — " +
+            'reinstall funtools, set FUNPIXEL_BENCH_DIR to a copy of them, or use the hosted bench: funtools gen inspect --asset <id>',
+    };
+}
+export const LOCAL_VERBS = {
+    inspect: { writes: false },
+    normalize: { writes: true, bench: 'normalize_transform' },
+    decimate: { writes: true, bench: 'decimate' },
+    render: { writes: true, bench: 'render_turntable' },
+    finalize: { writes: true },
+    level: { writes: true, bench: 'build_level' },
+};
+const FORMATS = ['glb', 'gltf', 'fbx'];
+export function refusal(path, bytes) {
+    const ext = path.split('.').pop()?.toLowerCase() ?? '';
+    if (!FORMATS.includes(ext))
+        return `${ext || 'this'} files are not taken; use a .glb, .gltf or .fbx`;
+    if (ext !== 'glb')
+        return null;
+    if (bytes.length < 20 || bytes.toString('latin1', 0, 4) !== 'glTF')
+        return 'not a GLB (no glTF header)';
+    const jsonLen = bytes.readUInt32LE(12);
+    if (bytes.toString('latin1', 16, 20) !== 'JSON' || 20 + jsonLen > bytes.length)
+        return 'not a GLB (no JSON chunk)';
+    let gltf;
+    try {
+        gltf = JSON.parse(bytes.toString('utf8', 20, 20 + jsonLen));
+    }
+    catch {
+        return 'not a GLB (unreadable JSON chunk)';
+    }
+    const blocked = (gltf.extensionsRequired ?? []).filter((e) => e === 'EXT_meshopt_compression' || e === 'KHR_texture_basisu');
+    return blocked.length
+        ? `it is compressed with ${blocked.join(' and ')}, which Blender cannot import — use the hosted bench (funtools gen inspect), or the uncompressed original`
+        : null;
+}
+export function benchArgs(verb, modelPath, outPath, opts, proofDir) {
+    if (verb === 'level') {
+        const size = opts.size === undefined ? 768 : Number(opts.size);
+        if (!Number.isInteger(size) || size < 256 || size > 1024)
+            return 'level takes --size 256-1024 (pixels)';
+        return { spec_path: resolve(modelPath), out_path: resolve(outPath), out_dir: resolve(proofDir ?? '.'), size };
+    }
+    const format = modelPath.split('.').pop()?.toLowerCase() ?? '';
+    const base = { model_path: resolve(modelPath), format };
+    if (verb === 'inspect')
+        return base;
+    if (verb === 'render') {
+        const frames = opts.frames === undefined ? 8 : Number(opts.frames);
+        const size = opts.size === undefined ? 512 : Number(opts.size);
+        if (!Number.isInteger(frames) || frames < 1 || frames > 12)
+            return 'render takes --frames 1-12';
+        if (!Number.isInteger(size) || size < 64 || size > 1024)
+            return 'render takes --size 64-1024 (pixels)';
+        return { ...base, out_dir: resolve(outPath), frames, size };
+    }
+    if (verb === 'finalize')
+        return { ...base, out_path: resolve(outPath) };
+    if (verb === 'decimate') {
+        const t = Number(opts.targetTriangles);
+        if (!Number.isInteger(t) || t < 100 || t > 200_000)
+            return 'decimate needs --target-triangles 100-200000';
+        return { ...base, out_path: resolve(outPath), target_triangles: t };
+    }
+    const h = opts.heightM === undefined ? 0 : Number(opts.heightM);
+    if (!Number.isFinite(h) || (h !== 0 && (h < 0.01 || h > 1000)))
+        return '--height-m is 0 (keep the size) or 0.01-1000 metres';
+    return { ...base, out_path: resolve(outPath), height_m: h };
+}
+export const readModel = (path) => readFileSync(path);

package/dist/model/blender.js

@@ -0,0 +1,106 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+export const MIN_VERSION = [4, 2];
+export const RESULT_BEGIN = '---FUNPIXEL-RESULT-BEGIN---';
+export const RESULT_END = '---FUNPIXEL-RESULT-END---';
+const realFs = {
+    exists: existsSync,
+    list: (dir) => { try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    } },
+};
+export function parseVersion(text) {
+    const m = /Blender\s+(\d+)\.(\d+)/.exec(text);
+    return m ? [Number(m[1]), Number(m[2])] : null;
+}
+export const newEnough = ([major, minor]) => major > MIN_VERSION[0] || (major === MIN_VERSION[0] && minor >= MIN_VERSION[1]);
+export function candidates(env, platform, fs = realFs) {
+    const out = [];
+    if (platform === 'darwin') {
+        for (const root of ['/Applications', join(env.HOME ?? homedir(), 'Applications')]) {
+            out.push(join(root, 'Blender.app', 'Contents', 'MacOS', 'Blender'));
+        }
+    }
+    if (platform === 'win32') {
+        for (const pf of [env.ProgramFiles, env['ProgramFiles(x86)']].filter((p) => !!p)) {
+            const foundation = join(pf, 'Blender Foundation');
+            const versions = fs.list(foundation)
+                .filter((d) => /^Blender \d+\.\d+/.test(d))
+                .sort((a, b) => compareVersions(parseVersion(b), parseVersion(a)));
+            for (const d of versions)
+                out.push(join(foundation, d, 'blender.exe'));
+        }
+    }
+    const exe = platform === 'win32' ? 'blender.exe' : 'blender';
+    for (const dir of (env.PATH ?? '').split(delimiter))
+        if (dir)
+            out.push(join(dir, exe));
+    return out.filter((p) => fs.exists(p));
+}
+function compareVersions(a, b) {
+    const [x, y] = [a ?? [0, 0], b ?? [0, 0]];
+    return x[0] - y[0] || x[1] - y[1];
+}
+function versionOf(bin) {
+    const r = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 30_000 });
+    return r.status === 0 ? parseVersion(r.stdout) : null;
+}
+export function findBlender(env = process.env, platform = process.platform, fs = realFs, version = versionOf) {
+    const explicit = env.FUNPIXEL_BLENDER_BIN;
+    const list = explicit ? [explicit] : candidates(env, platform, fs);
+    let tooOld = null;
+    for (const bin of list) {
+        const v = version(bin);
+        if (v && newEnough(v))
+            return { bin, version: v };
+        if (v)
+            tooOld = `${bin} is Blender ${v.join('.')}`;
+    }
+    const want = MIN_VERSION.join('.');
+    if (tooOld)
+        return { missing: `${tooOld}; local mode needs Blender ${want} or newer — install it from blender.org, or set FUNPIXEL_BLENDER_BIN` };
+    if (explicit)
+        return { missing: `FUNPIXEL_BLENDER_BIN=${explicit} does not run as Blender — point it at the Blender executable` };
+    return { missing: `no Blender found — install Blender ${want} or newer from blender.org, or set FUNPIXEL_BLENDER_BIN to its executable` };
+}
+export function parseEnvelope(stdout) {
+    const start = stdout.lastIndexOf(RESULT_BEGIN);
+    const end = stdout.lastIndexOf(RESULT_END);
+    if (start < 0 || end < start)
+        return { ok: false, error: 'Blender exited without an answer (the bench entrypoint did not run)' };
+    try {
+        const v = JSON.parse(stdout.slice(start + RESULT_BEGIN.length, end));
+        return v && v.ok ? { ok: true, result: v.result } : { ok: false, error: String(v?.error ?? 'the verb failed') };
+    }
+    catch {
+        return { ok: false, error: 'Blender answered something that is not the bench envelope' };
+    }
+}
+export function runVerb(bin, entrypoint, verb, args, timeoutMs = 300_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, [
+            '-b', '--factory-startup', '--disable-autoexec', '--python-exit-code', '1',
+            '-P', entrypoint, '--', verb, JSON.stringify(args),
+        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+        child.stdout.setEncoding('utf8').on('data', (d) => { out += d; });
+        child.stderr.setEncoding('utf8').on('data', (d) => { err = (err + d).slice(-4000); });
+        child.on('error', (e) => { clearTimeout(timer); reject(e); });
+        child.on('close', () => {
+            clearTimeout(timer);
+            const env = parseEnvelope(out);
+            if (!env.ok && !out.includes(RESULT_BEGIN) && err.trim()) {
+                resolve({ ok: false, error: `${env.error}: ${err.trim().split('\n').slice(-1)[0]}` });
+            }
+            else
+                resolve(env);
+        });
+    });
+}

package/dist/model/clips.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+const JSON_CHUNK = 0x4e4f534a;
+export function gltfJson(bytes) {
+    if (bytes.subarray(0, 4).toString('latin1') === 'glTF') {
+        if (bytes.length < 20)
+            throw new Error('a GLB shorter than its header');
+        const len = bytes.readUInt32LE(12);
+        if (bytes.readUInt32LE(16) !== JSON_CHUNK || 20 + len > bytes.length)
+            throw new Error('the GLB has no JSON chunk first');
+        return JSON.parse(bytes.subarray(20, 20 + len).toString('utf8'));
+    }
+    const text = bytes.toString('utf8').trimStart();
+    if (!text.startsWith('{'))
+        throw new Error('neither a GLB nor glTF JSON (an FBX or OBJ: export a GLB first)');
+    return JSON.parse(text);
+}
+export function judgeClips(names) {
+    const named = names.filter((n) => typeof n === 'string' && n.trim() !== '');
+    const unnamed = names.length - named.length;
+    const seen = new Map();
+    for (const n of named)
+        seen.set(n.toLowerCase(), (seen.get(n.toLowerCase()) ?? 0) + 1);
+    const duplicates = [...seen].filter(([, c]) => c > 1).map(([n]) => n);
+    const unique = [...new Map(named.map((n) => [n.toLowerCase(), n])).values()];
+    const collisions = [];
+    for (const a of unique)
+        for (const b of unique) {
+            if (a !== b && b.toLowerCase().includes(a.toLowerCase()))
+                collisions.push([a, b]);
+        }
+    const verdict = !names.length ? 'not_observed' : collisions.length || duplicates.length || unnamed ? 'fail' : 'pass';
+    return { verdict, clips: named, collisions, duplicates, unnamed };
+}
+export const modelClips = (path) => judgeClips((gltfJson(readFileSync(path)).animations ?? []).map((a) => (typeof a?.name === 'string' ? a.name : null)));

package/dist/model/finalize.js

@@ -0,0 +1,33 @@
+import { mkdirSync, renameSync, rmSync } from 'node:fs';
+export async function finalizeLocal(run, p, keepClips) {
+    const repaired = await run('normalize_materials', { model_path: p.model, format: p.format, out_path: p.out });
+    if (!repaired.ok)
+        return repaired;
+    let clips = null;
+    if (keepClips.length) {
+        const tmp = `${p.out}.pruned.glb`;
+        const pruned = await run('prune_clips', { model_path: p.out, format: 'glb', out_path: tmp, keep: keepClips });
+        if (!pruned.ok) {
+            rmSync(tmp, { force: true });
+            return pruned;
+        }
+        renameSync(tmp, p.out);
+        const r = pruned.result ?? {};
+        clips = { kept: r.clips_kept, dropped: r.clips_dropped, missing: r.clips_missing, bytes_before: r.bytes_before, bytes_after: r.bytes_after };
+    }
+    mkdirSync(p.proofDir, { recursive: true });
+    const shot = await run('render_turntable', { model_path: p.out, format: 'glb', out_dir: p.proofDir, frames: 4, size: 512 });
+    const proof = shot.ok
+        ? { rendered: true, front: shot.result?.front, contact_sheet: shot.result?.contact_sheet }
+        : { rendered: false, error: shot.error, look_at_it: 'No proof picture: do not assume the model looks right.' };
+    return {
+        ok: true,
+        result: {
+            out_path: p.out,
+            materials_fixed: repaired.result?.materials_fixed ?? [],
+            materials_total: repaired.result?.materials_total,
+            clips,
+            proof,
+        },
+    };
+}

package/dist/motion/checks.js

@@ -0,0 +1,173 @@
+import { EDGE_S, SAMPLE_EVERY_S, timeOf } from "./contract.js";
+export const CHECK_IDS = ['repeatable', 'safe_zone', 'overlaps', 'seam', 'blank'];
+export const SAMPLE_STEP = 4;
+export const BLANK_SHARE = 0.995;
+export const BLANK_TOLERANCE = 10;
+export const SEAM_FLOOR = 0.004;
+export const SEAM_STEPS = 2;
+const DETAIL_KEEP = 8;
+export function frameStats(img, step = SAMPLE_STEP) {
+    const w = Math.max(1, Math.floor(img.width / step)), h = Math.max(1, Math.floor(img.height / step));
+    const rgb = new Uint8Array(w * h * 3);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const s = ((y * step) * img.width + x * step) * 4, d = (y * w + x) * 3;
+            rgb[d] = img.data[s];
+            rgb[d + 1] = img.data[s + 1];
+            rgb[d + 2] = img.data[s + 2];
+        }
+    }
+    const bins = new Uint32Array(4096), sums = new Float64Array(4096 * 3);
+    const n = w * h;
+    for (let i = 0; i < n; i++) {
+        const r = rgb[i * 3], g = rgb[i * 3 + 1], b = rgb[i * 3 + 2];
+        const k = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4);
+        bins[k]++;
+        sums[k * 3] += r;
+        sums[k * 3 + 1] += g;
+        sums[k * 3 + 2] += b;
+    }
+    let top = 0;
+    for (let k = 1; k < 4096; k++)
+        if (bins[k] > bins[top])
+            top = k;
+    const colour = [0, 1, 2].map((c) => Math.round(sums[top * 3 + c] / Math.max(1, bins[top])));
+    let near = 0;
+    for (let i = 0; i < n; i++) {
+        if (Math.abs(rgb[i * 3] - colour[0]) <= BLANK_TOLERANCE && Math.abs(rgb[i * 3 + 1] - colour[1]) <= BLANK_TOLERANCE && Math.abs(rgb[i * 3 + 2] - colour[2]) <= BLANK_TOLERANCE)
+            near++;
+    }
+    return { w, h, rgb, share: near / n, colour };
+}
+export function meanDiff(a, b) {
+    if (a.w !== b.w || a.h !== b.h)
+        return 1;
+    let s = 0;
+    for (let i = 0; i < a.rgb.length; i++)
+        s += Math.abs(a.rgb[i] - b.rgb[i]);
+    return s / (a.rgb.length * 255);
+}
+export const median = (xs) => {
+    if (!xs.length)
+        return 0;
+    const s = [...xs].sort((a, b) => a - b), m = s.length >> 1;
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+const r4 = (x) => Math.round(x * 10000) / 10000;
+const sec = (f, fps) => `${Math.round(timeOf(f, fps) * 100) / 100} s`;
+const hex = (c) => `#${c.map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+const luma = (c) => 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+export function blankCheck(stats, judged, fps) {
+    const seen = judged.filter((f) => stats.has(f));
+    if (!seen.length)
+        return { id: 'blank', state: 'not_observed', says: `no frame at least ${EDGE_S} s from both ends to judge (the scene is too short)`, value: null, detail: [] };
+    const blank = seen.filter((f) => stats.get(f).share >= BLANK_SHARE);
+    const runs = [];
+    for (const f of blank) {
+        const last = runs.at(-1);
+        if (last && last[1] === f - 1)
+            last[1] = f;
+        else
+            runs.push([f, f]);
+    }
+    const detail = runs.slice(0, DETAIL_KEEP).map(([a, b]) => {
+        const c = stats.get(a).colour;
+        const word = luma(c) < 24 ? 'black' : 'one colour';
+        return `${a === b ? `frame ${a} (${sec(a, fps)})` : `frames ${a}–${b} (${sec(a, fps)}–${sec(b, fps)})`}: ${word} ${hex(c)} (${Math.round(stats.get(a).share * 1000) / 10}% of the frame)`;
+    });
+    return blank.length
+        ? { id: 'blank', state: 'fail', says: `${blank.length} of ${seen.length} judged frame(s) nearly one colour, in ${runs.length} stretch(es)`, value: blank.length, detail, runs: runs.length }
+        : { id: 'blank', state: 'pass', says: `none of ${seen.length} judged frame(s) is nearly one colour (the first and last ${EDGE_S} s are not judged)`, value: 0, detail: [] };
+}
+export function seamCheck(o) {
+    if (!o.loop)
+        return { id: 'seam', state: 'skip', says: 'not a loop (__MOTION__.loop is not true): no seam to measure', value: null, detail: [] };
+    if (!o.wrap || !o.first)
+        return { id: 'seam', state: 'not_observed', says: 'the wrap frame (the one after the last) was not rendered', value: null, detail: [] };
+    const seam = meanDiff(o.wrap, o.first);
+    const step = median(o.steps);
+    const allowed = Math.max(SEAM_FLOOR, SEAM_STEPS * step);
+    const lastVsFirst = o.last ? meanDiff(o.last, o.first) : null;
+    const facts = { seam: r4(seam), step: r4(step), allowed: r4(allowed), last_vs_first: lastVsFirst === null ? null : r4(lastVsFirst) };
+    const words = `the wrap differs from the first frame by ${r4(seam * 100)}% (an ordinary step is ${r4(step * 100)}%, allowed ${r4(allowed * 100)}%)`;
+    return seam > allowed
+        ? { id: 'seam', state: 'fail', says: `the loop pops at the wrap: ${words}`, value: 1, detail: ['make the last frame run into the first: every looping animation\'s period divides the scene\'s length, and its 0% and 100% keyframes match'], ...facts }
+        : { id: 'seam', state: 'pass', says: `the loop wraps cleanly: ${words}`, value: 0, detail: [], ...facts };
+}
+const named = (s, fps, text) => `${sec(s.frame, fps)}: ${text}`;
+export function safeZoneCheck(samples, fps) {
+    const seen = samples.filter((s) => s.layout && ((s.layout.counts?.texts ?? 0) + (s.layout.counts?.controls ?? 0)) > 0);
+    if (!seen.length) {
+        return { id: 'safe_zone', state: 'not_observed', says: samples.some((s) => s.layout) ? 'no text or control in the page at any sampled frame (text drawn on a canvas is not seen)' : 'layout was not read at any sampled frame', value: null, detail: [] };
+    }
+    const found = new Map();
+    for (const s of seen) {
+        for (const i of s.layout.unsafe?.items ?? []) {
+            const k = `unsafe ${i.name} ${i.side}`;
+            if (!found.has(k))
+                found.set(k, named(s, fps, `${i.name} outside the safe zone (${i.side})`));
+        }
+        for (const i of s.layout.clipped?.items ?? []) {
+            const k = `clipped ${i.name} ${i.side}`;
+            if (!found.has(k))
+                found.set(k, named(s, fps, i.side === 'clip' ? `${i.name} cut by ${i.by ?? 'what it sits in'} (${i.shown}% shown)` : `${i.name} cut by the ${i.side} edge`));
+        }
+    }
+    const detail = [...found.values()];
+    return detail.length
+        ? { id: 'safe_zone', state: 'fail', says: `${detail.length} piece(s) of text or control outside the safe zone or cut`, value: detail.length, detail: detail.slice(0, DETAIL_KEEP), samples: seen.length }
+        : { id: 'safe_zone', state: 'pass', says: `text and controls inside the safe zone at ${seen.length} sampled frame(s) (first, every ${SAMPLE_EVERY_S} s, last)`, value: 0, detail: [], samples: seen.length };
+}
+export function overlapsCheck(samples, fps) {
+    const seen = samples.filter((s) => s.layout && (s.layout.counts?.texts ?? 0) >= 2);
+    if (!seen.length) {
+        return { id: 'overlaps', state: 'not_observed', says: samples.some((s) => s.layout) ? 'fewer than two pieces of text in the page at every sampled frame: nothing to overlap (text drawn on a canvas is not seen)' : 'layout was not read at any sampled frame', value: null, detail: [] };
+    }
+    const found = new Map();
+    for (const s of seen) {
+        for (const i of s.layout.overlaps?.items ?? []) {
+            const k = [i.a, i.b].sort().join(' × ');
+            if (!found.has(k))
+                found.set(k, named(s, fps, `${i.a} over ${i.b} (${i.px} px²)`));
+        }
+    }
+    const detail = [...found.values()];
+    return detail.length
+        ? { id: 'overlaps', state: 'fail', says: `${detail.length} pair(s) of text painted over each other`, value: detail.length, detail: detail.slice(0, DETAIL_KEEP), samples: seen.length }
+        : { id: 'overlaps', state: 'pass', says: `no text over text at ${seen.length} sampled frame(s)`, value: 0, detail: [], samples: seen.length };
+}
+export function repeatCheck(a, b) {
+    if (!b)
+        return { id: 'repeatable', state: 'skip', says: 'not asked (--prove renders the scene twice and compares every frame)', value: null, detail: [] };
+    if (!a.length || !b.length)
+        return { id: 'repeatable', state: 'not_observed', says: 'one of the two renders made no frame', value: null, detail: [] };
+    const n = Math.max(a.length, b.length);
+    const differ = [];
+    for (let i = 0; i < n; i++)
+        if (a[i] !== b[i])
+            differ.push(i);
+    return differ.length
+        ? { id: 'repeatable', state: 'fail', says: `${differ.length} of ${n} frame(s) differ between two renders, first at frame ${differ[0]}`, value: differ.length, detail: [`something in the scene is not on the held clock (a video, a worker, audio time, \`new Date()\`, requestIdleCallback): draw from the frame number or performance.now()`] }
+        : { id: 'repeatable', state: 'pass', says: `two renders, ${n} frame(s), every frame byte-identical`, value: 0, detail: [] };
+}
+export function verdictOf(checks) {
+    const s = checks.map((c) => c.state).filter((x) => x !== 'skip');
+    if (s.includes('fail'))
+        return 'fail';
+    return s.includes('pass') ? 'pass' : 'not_observed';
+}
+export function boardParts(checks, key) {
+    const by = (id) => checks.find((c) => c.id === id);
+    const observed = (c) => !!c && (c.state === 'pass' || c.state === 'fail') && c.value !== null;
+    const out = { errors: {}, overlaps: {}, seams: {} };
+    const blank = by('blank');
+    if (observed(blank))
+        out.errors[key] = { value: typeof blank.runs === 'number' ? blank.runs : blank.value, by: 'motion', detail: blank.detail.slice(0, 5) };
+    const lay = [by('safe_zone'), by('overlaps')].filter(observed);
+    if (lay.length)
+        out.overlaps[key] = { value: lay.reduce((s, c) => s + c.value, 0), by: 'motion', detail: lay.flatMap((c) => c.detail).slice(0, 5) };
+    const seam = by('seam');
+    if (observed(seam))
+        out.seams[key] = { value: seam.value, by: 'motion', detail: seam.state === 'fail' ? [seam.says] : [] };
+    return out;
+}

package/dist/motion/contract.js

@@ -0,0 +1,177 @@
+import { SAFE } from "../trailer/placement.js";
+export const ASPECTS = { '9:16': [1080, 1920], '16:9': [1920, 1080], '1:1': [1080, 1080], '4:5': [1080, 1350] };
+export const ASPECT_NAMES = Object.keys(ASPECTS);
+export const DEFAULTS = { fps: 30, seconds: 5, aspect: '9:16' };
+export const LIMITS = { fps: [1, 60], side: [16, 3840], frames: [1, 3600] };
+export const SAMPLE_EVERY_S = 0.5;
+export const EDGE_S = 0.5;
+export function formatOf(w, h) {
+    const r = h / w;
+    return r >= 1.5 ? '9x16' : r >= 1.1 ? '4x5' : r <= 1 / 1.3 ? '16x9' : '1x1';
+}
+export const safeFor = (w, h) => ({ ...SAFE[formatOf(w, h)] });
+const finite = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+export function parseSize(s) {
+    const m = String(s).trim().match(/^(\d+)\s*[x×]\s*(\d+)$/i);
+    if (!m)
+        return `--size is WxH in pixels (1080x1920), not "${s}"`;
+    const width = Number(m[1]), height = Number(m[2]);
+    const [lo, hi] = LIMITS.side;
+    if ([width, height].some((v) => v < lo || v > hi))
+        return `--size: each side is ${lo} to ${hi} pixels`;
+    if (width % 2 || height % 2)
+        return `--size ${width}x${height}: each side must be even (H.264 at yuv420p halves the colour planes)`;
+    return { width, height };
+}
+export function readDeclared(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const r = raw;
+    const d = {};
+    const seconds = finite(r.seconds), frames = finite(r.frames), fps = finite(r.fps);
+    if (seconds !== undefined && seconds > 0)
+        d.seconds = seconds;
+    if (frames !== undefined && frames >= 1)
+        d.frames = Math.round(frames);
+    if (fps !== undefined && fps > 0)
+        d.fps = fps;
+    if (typeof r.size === 'string') {
+        const s = parseSize(r.size);
+        if (typeof s !== 'string')
+            d.size = s;
+    }
+    else if (Array.isArray(r.size) && r.size.length === 2) {
+        const s = parseSize(`${r.size[0]}x${r.size[1]}`);
+        if (typeof s !== 'string')
+            d.size = s;
+    }
+    else if (r.size && typeof r.size === 'object') {
+        const o = r.size;
+        const s = parseSize(`${o.width}x${o.height}`);
+        if (typeof s !== 'string')
+            d.size = s;
+    }
+    if (typeof r.aspect === 'string' && ASPECT_NAMES.includes(r.aspect))
+        d.aspect = r.aspect;
+    if (typeof r.loop === 'boolean')
+        d.loop = r.loop;
+    if (r.safe && typeof r.safe === 'object') {
+        const o = r.safe;
+        const k = ['top', 'right', 'bottom', 'left'];
+        if (k.every((x) => { const v = finite(o[x]); return v !== undefined && v >= 0 && v < 0.5; }))
+            d.safe = Object.fromEntries(k.map((x) => [x, o[x]]));
+    }
+    return d;
+}
+export function plan(asked, declared = {}) {
+    const from = {};
+    const [flo, fhi] = LIMITS.fps;
+    let fps;
+    if (asked.fps !== undefined) {
+        if (!Number.isInteger(asked.fps) || asked.fps < flo || asked.fps > fhi)
+            return `--fps is a whole number from ${flo} to ${fhi} (30 or 60 for most work)`;
+        fps = asked.fps;
+        from.fps = 'flag';
+    }
+    else if (declared.fps !== undefined && Number.isInteger(declared.fps) && declared.fps >= flo && declared.fps <= fhi) {
+        fps = declared.fps;
+        from.fps = 'scene';
+    }
+    else {
+        fps = DEFAULTS.fps;
+        from.fps = 'default';
+    }
+    if (asked.seconds !== undefined && asked.frames !== undefined)
+        return '--seconds or --frames, not both';
+    let frames;
+    if (asked.frames !== undefined) {
+        if (!Number.isInteger(asked.frames))
+            return '--frames is a whole number';
+        frames = asked.frames;
+        from.length = 'flag';
+    }
+    else if (asked.seconds !== undefined) {
+        if (!(asked.seconds > 0))
+            return '--seconds is a number above 0';
+        frames = framesFor(asked.seconds, fps);
+        from.length = 'flag';
+    }
+    else if (declared.frames !== undefined) {
+        frames = declared.frames;
+        from.length = 'scene';
+    }
+    else if (declared.seconds !== undefined) {
+        frames = framesFor(declared.seconds, fps);
+        from.length = 'scene';
+    }
+    else {
+        frames = framesFor(DEFAULTS.seconds, fps);
+        from.length = 'default';
+    }
+    const [lo, hi] = LIMITS.frames;
+    if (frames < lo || frames > hi)
+        return `${frames} frames: a render is ${lo} to ${hi} frames (${hi / 60} s at 60 fps)`;
+    let size;
+    if (asked.size !== undefined && asked.aspect !== undefined)
+        return '--size or --aspect, not both';
+    if (asked.size !== undefined) {
+        const s = parseSize(asked.size);
+        if (typeof s === 'string')
+            return s;
+        size = s;
+        from.size = 'flag';
+    }
+    else if (asked.aspect !== undefined) {
+        if (!ASPECT_NAMES.includes(asked.aspect))
+            return `--aspect is ${ASPECT_NAMES.join(', ')}`;
+        const [width, height] = ASPECTS[asked.aspect];
+        size = { width, height };
+        from.size = 'flag';
+    }
+    else if (declared.size) {
+        size = declared.size;
+        from.size = 'scene';
+    }
+    else if (declared.aspect) {
+        const [width, height] = ASPECTS[declared.aspect];
+        size = { width, height };
+        from.size = 'scene';
+    }
+    else {
+        const [width, height] = ASPECTS[DEFAULTS.aspect];
+        size = { width, height };
+        from.size = 'default';
+    }
+    const loop = declared.loop === true;
+    from.loop = declared.loop === undefined ? 'default' : 'scene';
+    const safe = declared.safe ?? safeFor(size.width, size.height);
+    from.safe = declared.safe ? 'scene' : 'default';
+    return { fps, frames, seconds: frames / fps, frame_ms: 1000 / fps, width: size.width, height: size.height, loop, safe, from };
+}
+export function framesFor(seconds, fps) {
+    return Math.max(1, Math.round(seconds * fps));
+}
+export const timeOf = (frame, fps) => frame / fps;
+export const frameFile = (frame) => `${String(frame + 1).padStart(6, '0')}.png`;
+export const FRAME_PATTERN = '%06d.png';
+export function sampleFrames(frames, fps, every = SAMPLE_EVERY_S) {
+    const out = new Set([0]);
+    const step = Math.max(1, Math.round(every * fps));
+    for (let f = step; f < frames; f += step)
+        out.add(f);
+    out.add(frames - 1);
+    return [...out].sort((a, b) => a - b);
+}
+export function judgedForBlank(frames, fps, edge = EDGE_S) {
+    const out = [];
+    const first = Math.ceil(edge * fps - 1e-9), last = frames - 1 - Math.ceil(edge * fps - 1e-9);
+    for (let f = first; f <= last; f++)
+        out.push(f);
+    return out;
+}
+export function safeInsets(p) {
+    return {
+        top: Math.round(p.safe.top * p.height), bottom: Math.round(p.safe.bottom * p.height),
+        left: Math.round(p.safe.left * p.width), right: Math.round(p.safe.right * p.width),
+    };
+}

package/dist/motion/encode.js

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { FRAME_PATTERN } from "./contract.js";
+export function ffmpegBin() {
+    const r = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore', shell: false });
+    return r.status === 0 ? 'ffmpeg' : null;
+}
+export function encodeArgs(o) {
+    const args = ['-hide_banner', '-loglevel', 'error', '-y', '-framerate', String(o.fps), '-i', join(o.framesDir, FRAME_PATTERN)];
+    if (o.audio)
+        args.push('-i', o.audio);
+    args.push('-map', '0:v');
+    if (o.audio)
+        args.push('-map', '1:a', '-af', 'apad');
+    if (o.container === 'mp4') {
+        args.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-pix_fmt', 'yuv420p', '-r', String(o.fps));
+        if (o.audio)
+            args.push('-c:a', 'aac', '-b:a', '192k', '-ar', '48000');
+        args.push('-movflags', '+faststart');
+    }
+    else {
+        args.push('-c:v', 'libvpx-vp9', '-b:v', '0', '-crf', '32', '-row-mt', '1', '-pix_fmt', 'yuv420p', '-r', String(o.fps));
+        if (o.audio)
+            args.push('-c:a', 'libopus', '-b:a', '128k', '-ar', '48000');
+    }
+    args.push('-t', String(Math.round(o.seconds * 1e6) / 1e6), '-fflags', '+bitexact', '-flags:v', '+bitexact');
+    if (o.audio)
+        args.push('-flags:a', '+bitexact');
+    args.push('-map_metadata', '-1', o.out);
+    return args;
+}
+export function encode(bin, o) {
+    const r = spawnSync(bin, encodeArgs(o), { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+    if (r.status === 0)
+        return { ok: true };
+    return { ok: false, error: (r.stderr || r.error?.message || `ffmpeg exited ${r.status}`).trim().split('\n').slice(-3).join(' ') };
+}