#!/usr/bin/env node // Builds the finished reveal with ffmpeg, all of it local: the "before" photo held still for about 2 s with a // drawn loading screen (a panel, the label "loading..." and a bar that fills), a white flash that peaks on the beat, // then the "after" clip in motion. The loading screen, the freeze and the flash are never made by a model. // The file is silent by design: the user adds a trending sound in the app. The beat is printed, written to the // edit list and set as an MP4 chapter, so the sound's drop can be lined up with the first white frame. // // Usage: // node scripts/assemble-reveal.mjs --plan plan.json --out reveal.mp4 // [--before before-9x16.jpg] [--clip after.mp4] [--trim-in 0.1] [--trim-out 5] // [--hold 2] [--flash 0.25] [--label loading] [--no-dots] [--accent #ffffff] [--ui-y 0.66] [--dim 0.08] // [--no-chapters] [--crf 10-30] [--max-mb 8] [--dry-run] // // --plan gives the before photo and the clip with its trims (files.final, files.in, files.out); the flags override them. // --hold is the seconds of the before frame (1.5 to 3). --flash is how long the white takes to clear after the beat. // --ui-y is where the loading panel sits, as a fraction of the height (0.45 to 0.72). --dim darkens the before frame a little. // Requires ffmpeg and ffprobe on PATH. Node 18 or newer. No npm packages. import { spawnSync } from 'node:child_process' import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { dirname, isAbsolute, join, resolve } from 'node:path' import { writeLoader } from './loader-ui.mjs' const FLAGS = new Set(['plan', 'out', 'before', 'clip', 'trim-in', 'trim-out', 'hold', 'flash', 'label', 'no-dots', 'accent', 'ui-y', 'dim', 'no-chapters', 'crf', 'max-mb', 'dry-run']) const SWITCHES = new Set(['no-dots', 'no-chapters', 'dry-run']) const W = 720 const H = 1280 const FPS = 24 const LEAD = 2 / FPS // the white ramps up over the last two frames of the before frame function fail(message) { console.error(message) process.exit(1) } function parseFlags(argv) { const out = {} for (let i = 0; i < argv.length; i++) { const a = argv[i] if (!a.startsWith('--')) fail(`Unexpected argument "${a}". Flags look like --name value.`) const key = a.slice(2) if (!FLAGS.has(key)) fail(`Unknown flag --${key}. Allowed: ${[...FLAGS].map((f) => `--${f}`).join(', ')}`) if (SWITCHES.has(key)) { out[key] = true continue } const value = argv[i + 1] if (value === undefined || value.startsWith('--')) fail(`--${key} needs a value.`) out[key] = value i++ } return out } function num(value, name, min, max, fallback) { if (value === undefined || value === null || value === '') return fallback const n = Number(value) if (!Number.isFinite(n) || n < min || n > max) fail(`--${name} must be a number from ${min} to ${max}, got "${value}".`) return n } function run(cmd, args, label) { const r = spawnSync(cmd, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }) if (r.error?.code === 'ENOENT') fail(`${cmd} is not installed or not on PATH. Install ffmpeg (it includes ffprobe) and try again.`) if (r.status !== 0) fail(`${label} failed:\n${(r.stderr || '').split('\n').slice(-15).join('\n')}`) return r.stdout } function probe(path) { const j = JSON.parse(run('ffprobe', ['-v', 'error', '-print_format', 'json', '-show_streams', '-show_format', path], `ffprobe ${path}`)) const v = j.streams.find((s) => s.codec_type === 'video') if (!v) fail(`${path} has no video stream.`) return { width: v.width, height: v.height, duration: Number(j.format.duration), codec: v.codec_name } } const f3 = (n) => Number(n).toFixed(3) const opts = parseFlags(process.argv.slice(2)) if (!opts.out) fail('Usage: node scripts/assemble-reveal.mjs --plan plan.json --out reveal.mp4 [options]. See the header of this file for every option.') if (!/\.mp4$/i.test(opts.out)) fail('--out must end in .mp4.') let plan = {} let base = process.cwd() if (opts.plan) { if (!existsSync(opts.plan)) fail(`Plan not found: ${opts.plan}. Create it with scripts/build-plan.mjs.`) try { plan = JSON.parse(readFileSync(opts.plan, 'utf8')) } catch { fail(`${opts.plan} is not valid JSON.`) } base = dirname(resolve(opts.plan)) } const rel = (p) => (isAbsolute(p) ? p : join(base, p)) const beforePath = rel(opts.before ?? plan.subject?.prepared ?? '') const clipPath = rel(opts.clip ?? plan.files?.final ?? '') if (!opts.before && !plan.subject?.prepared) fail('No before photo. Pass --before before-9x16.jpg or set subject.prepared in the plan (scripts/prepare-before.mjs makes it).') if (!opts.clip && !plan.files?.final) fail('No after clip yet. Pass --clip after.mp4 or put the approved Kling MP4 in files.final in the plan.') if (!existsSync(beforePath)) fail(`Before photo not found: ${beforePath}`) if (!existsSync(clipPath)) fail(`After clip not found: ${clipPath}`) if (!/\.(jpe?g|png|webp)$/i.test(beforePath)) fail(`${beforePath} must be a .jpg, .png or .webp image.`) if (!/\.(mp4|mov|webm)$/i.test(clipPath)) fail(`${clipPath} is not a video. Use the MP4 the video model returned.`) const hold = num(opts.hold ?? plan.brief?.hold, 'hold', 1.5, 3, 2) const flash = num(opts.flash ?? plan.brief?.flash, 'flash', 0.1, 0.6, 0.25) const dim = num(opts.dim, 'dim', 0, 0.3, 0.08) const uiY = num(opts['ui-y'], 'ui-y', 0.45, 0.72, 0.66) const crf = num(opts.crf, 'crf', 10, 30, 20) const maxMb = opts['max-mb'] === undefined ? null : num(opts['max-mb'], 'max-mb', 1, 500) const label = opts.label ?? plan.brief?.label ?? 'loading' const accent = opts.accent ?? '#ffffff' const dots = !opts['no-dots'] && plan.brief?.dots !== false const info = probe(clipPath) const inT = num(opts['trim-in'] ?? plan.files?.in, 'trim-in', 0, 60, 0.1) const outT = Math.min(num(opts['trim-out'] ?? plan.files?.out, 'trim-out', 0.5, 60, info.duration), info.duration) if (outT <= inT) fail(`--trim-out (${outT}) must be after --trim-in (${inT}).`) if (outT > info.duration + 0.05) fail(`The trim ends at ${outT} s but the clip is ${info.duration.toFixed(2)} s long.`) const afterLen = outT - inT const total = hold + afterLen if (afterLen < flash + 2) fail(`The after part is ${afterLen.toFixed(2)} s. Keep at least ${(flash + 2).toFixed(1)} s of it, or re-roll the clip.`) if (total < 5.9 || total > 8.1) fail(`The reveal would be ${total.toFixed(2)} s. The format is 6 to 8 s: change --hold or the trims (hold ${hold} s + after ${afterLen.toFixed(2)} s).`) if (Math.abs(info.width / info.height - W / H) > 0.03) console.error(`warning: the clip is ${info.width}x${info.height}, not 9:16. It will be cropped to fill; check the edges.`) const work = mkdtempSync(join(tmpdir(), 'assemble-reveal-')) let ui try { ui = writeLoader(work, { width: W, height: H, label, dots, centreY: uiY, accent }) } catch (error) { rmSync(work, { recursive: true, force: true }) fail(error.message) } if (ui.bottom > H * 0.8) { rmSync(work, { recursive: true, force: true }) fail(`The loading panel would reach into the bottom 20% of the frame (the app's caption area). Lower --ui-y.`) } // The bar crawls to 93% and holds, then jumps to full just before the flash, so the cut lands on a full bar. const crawl = hold - 0.15 const progress = `if(lt(t,${f3(crawl)}),0.93*(1-pow(1-t/${f3(crawl)},2)),1)` const inputs = ['-loop', '1', '-framerate', String(FPS), '-t', f3(hold), '-i', beforePath, '-i', clipPath, '-i', ui.panel] for (const l of ui.labels) inputs.push('-i', l) inputs.push('-loop', '1', '-framerate', String(FPS), '-t', f3(hold), '-i', ui.strip) const stripIdx = 3 + ui.labels.length const [px, py] = ui.panel_xy const graph = [] graph.push(`[0:v]scale=${W}:${H}:flags=lanczos:force_original_aspect_ratio=increase:out_range=tv,crop=${W}:${H},setsar=1,fps=${FPS},eq=brightness=-${f3(dim)},format=yuva420p[bg]`) graph.push(`[bg][2:v]overlay=${px}:${py}:format=auto[p0]`) const gate = ui.labels.length === 3 ? ["lt(mod(t,0.9),0.3)", "between(mod(t,0.9),0.3,0.6)", "gte(mod(t,0.9),0.6)"] : ['1'] let last = 'p0' ui.labels.forEach((_, i) => { graph.push(`[${last}][${3 + i}:v]overlay=${px}:${py}:format=auto:enable='${gate[i]}'[p${i + 1}]`) last = `p${i + 1}` }) graph.push(`[${stripIdx}:v]fps=${FPS},crop=${ui.fill.w}:${ui.fill.h}:x='${ui.fill.w}*(1-(${progress}))':y=0,format=rgba[bar]`) graph.push(`[${last}][bar]overlay=${ui.fill.x}:${ui.fill.y}:format=auto,format=yuv420p,fade=t=out:st=${f3(hold - LEAD)}:d=${f3(LEAD)}:color=white,setpts=PTS-STARTPTS,settb=1/${FPS}[before]`) graph.push(`[1:v]trim=start=${f3(inT)}:end=${f3(outT)},setpts=PTS-STARTPTS,fps=${FPS},scale=${W}:${H}:flags=lanczos:force_original_aspect_ratio=increase:out_range=tv,crop=${W}:${H},setsar=1,format=yuv420p,fade=t=in:st=0:d=${f3(flash)}:color=white,settb=1/${FPS}[after]`) graph.push('[before][after]concat=n=2:v=1:a=0[vout]') const chapters = !opts['no-chapters'] let metaIdx = null if (chapters) { const ms = (s) => Math.round(s * 1000) const meta = [ ';FFMETADATA1', '[CHAPTER]', 'TIMEBASE=1/1000', 'START=0', `END=${ms(hold)}`, 'title=Before: loading', '[CHAPTER]', 'TIMEBASE=1/1000', `START=${ms(hold)}`, `END=${ms(total)}`, 'title=Beat: white flash, after starts', ].join('\n') writeFileSync(join(work, 'chapters.txt'), `${meta}\n`) inputs.push('-i', join(work, 'chapters.txt')) metaIdx = stripIdx + 1 } const common = ['-y', '-hide_banner', '-v', 'error', ...inputs, '-filter_complex', graph.join(';'), '-map', '[vout]'] if (metaIdx !== null) common.push('-map_metadata', String(metaIdx), '-map_chapters', String(metaIdx)) const video = ['-c:v', 'libx264', '-preset', 'slow', '-profile:v', 'high', '-pix_fmt', 'yuv420p', '-r', String(FPS)] const tail = ['-an', '-t', f3(total), '-movflags', '+faststart'] const beatFrame = Math.round(hold * FPS) if (opts['dry-run']) { console.log(`Filter graph:\n${graph.join(';\n')}\n\nBefore ${hold} s + after ${afterLen.toFixed(2)} s = ${total.toFixed(2)} s, ${W}x${H}. Beat at ${hold.toFixed(3)} s (frame ${beatFrame}).`) rmSync(work, { recursive: true, force: true }) process.exit(0) } if (maxMb) { const videoKbps = Math.floor((maxMb * 8 * 1024 * 0.94) / total) if (videoKbps < 600) fail(`--max-mb ${maxMb} is too small for ${total.toFixed(1)} s. Raise it.`) const passlog = join(work, 'pass') run('ffmpeg', [...common, ...video, '-b:v', `${videoKbps}k`, '-pass', '1', '-passlogfile', passlog, '-an', '-t', f3(total), '-f', 'mp4', process.platform === 'win32' ? 'NUL' : '/dev/null'], 'ffmpeg pass 1') run('ffmpeg', [...common, ...video, '-b:v', `${videoKbps}k`, '-maxrate', `${Math.round(videoKbps * 1.5)}k`, '-bufsize', `${videoKbps * 2}k`, '-pass', '2', '-passlogfile', passlog, ...tail, opts.out], 'ffmpeg pass 2') } else { run('ffmpeg', [...common, ...video, '-crf', String(crf), ...tail, opts.out], 'ffmpeg') } rmSync(work, { recursive: true, force: true }) const edl = { file: opts.out, width: W, height: H, fps: FPS, duration: Number(total.toFixed(3)), audio: 'none', chapters, beat: { seconds: Number(hold.toFixed(3)), frame: beatFrame, note: 'The first fully white frame. Line the sound\'s drop up with it. Also set as the chapter "Beat" in the MP4.', }, before: { file: beforePath, seconds: Number(hold.toFixed(3)), label: ui.text, dim, panel_y: Math.round(py), flash_lead: Number(LEAD.toFixed(3)) }, after: { file: clipPath, in: inT, out: Number(outT.toFixed(3)), seconds: Number(afterLen.toFixed(3)), flash_clear: flash }, // Used by check-reveal.mjs: the loader's bar and the flash are planned, so they are not flagged as faults. loader: { panel: ui.panel_xy.concat(ui.panel_size), fill: [ui.fill.x, ui.fill.y, ui.fill.w, ui.fill.h] }, joins: [{ at: Number((hold - LEAD).toFixed(3)), type: 'flash', d: Number((LEAD + flash).toFixed(3)) }], } writeFileSync(`${opts.out}.edl.json`, JSON.stringify(edl, null, 2)) const mb = statSync(opts.out).size / 1024 / 1024 console.log(`${opts.out} ${W}x${H} ${total.toFixed(2)} s ${mb.toFixed(2)} MB silent`) console.log(`BEAT: ${hold.toFixed(3)} s (frame ${beatFrame} at ${FPS} fps) is the first fully white frame. Put the sound's drop there.`) console.log(`Edit list: ${opts.out}.edl.json\nNext: node scripts/check-reveal.mjs --file ${opts.out} --edl ${opts.out}.edl.json`)