#!/usr/bin/env node // Joins the two approved shot clips (the wide establishing shot, then the low-angle hero moment) into one // 9:16 stunt clip with ffmpeg: trims, one hard cut, the clips' own street sound joined with a short audio // crossfade (kept in sync with the picture), an optional light grade, an optional centre crop, and a small // "AI-made" tag drawn locally with sharp and laid over the whole clip. The tag is ON by default: this format // is a realistic fake, so the file says so. Then H.264 MP4 with AAC sound and +faststart. No other text. // // Usage: // node scripts/assemble-stunt.mjs --plan stunt.json --out stunt.mp4 // [--tag "AI-made"|off] [--tag-pos top-left|top-right] [--size 720x1280] // [--grade none|clean|warm|cool] [--audio clips|none] [--audio-xfade 0-0.3] [--gain -12-12] // [--crop none|4:5|1:1] [--only 1,2] [--crf 10-30] [--max-mb 8] [--dry-run] // // The tag needs sharp (npm i sharp in the folder you run from). --tag off is for a user who asked for it: // say that the clip is then a realistic fake with nothing on it that says so. // --audio none makes a silent file (for a landing-page preview). Requires ffmpeg and ffprobe on PATH. // Node 18 or newer. 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' const FLAGS = new Set(['plan', 'out', 'tag', 'tag-pos', 'size', 'grade', 'audio', 'audio-xfade', 'gain', 'crop', 'only', 'crf', 'max-mb', 'dry-run']) const SWITCHES = new Set(['dry-run']) const GRADES = { none: 'null', clean: "curves=master='0/0.01 0.25/0.235 0.75/0.77 1/0.99',eq=saturation=1.03", warm: "colorbalance=rs=0.02:gs=0:bs=-0.02:rm=0.03:gm=0.01:bm=-0.03:rh=0.02:gh=0.01:bh=-0.03,curves=master='0/0.01 0.25/0.235 0.75/0.77 1/0.99'", cool: "colorbalance=rs=-0.02:gs=0:bs=0.03:rm=-0.02:gm=0.01:bm=0.02,curves=master='0/0.01 0.25/0.235 0.75/0.77 1/0.99',eq=saturation=0.97", } 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) 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. Pass the MP4 clips the video model returned, not stills.`) return { width: v.width, height: v.height, duration: Number(j.format.duration), hasAudio: j.streams.some((s) => s.codec_type === 'audio') } } const even = (n) => Math.max(2, Math.floor(n / 2) * 2) const f3 = (n) => Number(n).toFixed(3) const opts = parseFlags(process.argv.slice(2)) if (!opts.plan || !opts.out) fail('Usage: node scripts/assemble-stunt.mjs --plan stunt.json --out stunt.mp4 [options]. See the header of this file for every option.') if (!existsSync(opts.plan)) fail(`Plan not found: ${opts.plan}. Create it with scripts/build-plan.mjs.`) let plan try { plan = JSON.parse(readFileSync(opts.plan, 'utf8')) } catch { fail(`${opts.plan} is not valid JSON.`) } const base = dirname(resolve(opts.plan)) const rel = (p) => (isAbsolute(p) ? p : join(base, p)) const brief = plan.brief ?? {} const grade = opts.grade ?? 'clean' if (!(grade in GRADES)) fail(`--grade must be one of ${Object.keys(GRADES).join(', ')}, not "${grade}".`) const xfade = num(opts['audio-xfade'], '--audio-xfade', 0, 0.3, 0.08) const gain = num(opts.gain, '--gain', -12, 12, 0) 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 crop = opts.crop ?? 'none' if (!['none', '4:5', '1:1'].includes(crop)) fail(`--crop must be none, 4:5 or 1:1, not "${crop}".`) const audioMode = opts.audio ?? 'clips' if (!['none', 'clips'].includes(audioMode)) fail(`--audio must be none or clips, not "${audioMode}".`) const sizeMatch = (opts.size ?? '720x1280').match(/^(\d{3,4})x(\d{3,4})$/) if (!sizeMatch) fail('--size must look like 720x1280.') const [W, H] = [Number(sizeMatch[1]), Number(sizeMatch[2])] if (W % 2 || H % 2) fail('--size needs even numbers, like 720x1280.') const tagText = opts.tag ?? brief.tag ?? 'AI-made' const tagOn = tagText.toLowerCase() !== 'off' if (tagOn && !/^[A-Za-z0-9 .,'&+-]{2,24}$/.test(tagText)) fail('--tag takes 2 to 24 letters, numbers or simple punctuation, or "off".') const tagPos = opts['tag-pos'] ?? 'top-left' if (!['top-left', 'top-right'].includes(tagPos)) fail('--tag-pos must be top-left or top-right (both sit below the app\'s top bar and clear of the caption area).') if (!Array.isArray(plan.shots) || !plan.shots.length) fail('The plan has no shots.') let shots = plan.shots.filter((s) => s.clip && !s.skip) if (opts.only) { const wanted = opts.only.split(',').map((x) => Number(x.trim())) if (wanted.some((n) => !Number.isInteger(n))) fail(`--only takes shot numbers like 1,2, not "${opts.only}".`) shots = wanted.map((n) => { const s = plan.shots.find((x) => x.n === n) if (!s) fail(`--only: there is no shot number ${n}.`) if (!s.clip) fail(`--only: shot ${n} has no clip yet.`) return s }) } if (!shots.length) fail('No shot has a "clip" path yet. Add the approved MP4 paths to the plan first.') const clips = shots.map((s) => { const path = rel(s.clip) if (!existsSync(path)) fail(`Shot ${s.n}: clip not found at ${path}.`) if (!/\.(mp4|mov|webm)$/i.test(path)) fail(`Shot ${s.n}: "${s.clip}" is not a video. Use the MP4 the video model returned.`) const info = probe(path) const inT = Number(s.in ?? 0) let outT = Number(s.out ?? info.duration) if (!Number.isFinite(inT) || !Number.isFinite(outT) || inT < 0 || outT <= inT) fail(`Shot ${s.n}: "in" and "out" must be seconds with in < out.`) if (outT > info.duration + 0.05) fail(`Shot ${s.n}: "out" (${outT}s) is past the end of the clip (${info.duration.toFixed(2)}s).`) outT = Math.min(outT, info.duration) return { shot: s, path, info, inT, outT, len: outT - inT } }) if (audioMode === 'clips') for (const c of clips) if (!c.info.hasAudio) fail(`Shot ${c.shot.n} has no audio. Regenerate it with generate_audio true, or use --audio none for a silent preview.`) let outW = W let outH = H if (crop !== 'none') { const [a, b] = crop.split(':').map(Number) if (W / H > a / b) { outH = even(H); outW = even((H * a) / b) } else { outW = even(W); outH = even((W * b) / a) } } const total = clips.reduce((a, c) => a + c.len, 0) // The tag: a small dark pill with white text, drawn with sharp so the words are exact, laid over every frame. // It sits below the app's top bar (about 13.5% down; 5% in a 4:5 crop) and clear of the caption area at the bottom. const work = mkdtempSync(join(tmpdir(), 'assemble-stunt-')) let tagPng = null let tagBox = null if (tagOn) { let sharp try { sharp = (await import('sharp')).default } catch { rmSync(work, { recursive: true, force: true }) fail('The AI-made tag needs sharp. Run "npm i sharp" in the folder you run this from. Do not leave the tag out unless the user asked: pass --tag off only then.') } const fontPx = Math.max(14, Math.round(outW * 0.034)) const text = await sharp({ text: { text: `${tagText.replace(/&/g, '&')}`, font: `sans bold ${fontPx}`, rgba: true } }).png().toBuffer({ resolveWithObject: true }) const padX = Math.round(fontPx * 0.75) const padY = Math.round(fontPx * 0.42) const boxW = text.info.width + padX * 2 const boxH = text.info.height + padY * 2 const pill = await sharp(Buffer.from(``)) .composite([{ input: text.data, left: padX, top: padY }]) .png() .toBuffer() const margin = Math.round(outW * 0.05) const left = tagPos === 'top-left' ? margin : outW - margin - boxW const top = Math.round(outH * (crop === 'none' ? 0.135 : 0.05)) tagBox = { x: left, y: top, w: boxW, h: boxH } tagPng = join(work, 'tag.png') await sharp({ create: { width: outW, height: outH, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } }).composite([{ input: pill, left, top }]).png().toFile(tagPng) } const inputs = [] const graph = [] clips.forEach((c, i) => { inputs.push('-i', c.path) graph.push(`[${i}:v]trim=start=${f3(c.inT)}:end=${f3(c.outT)},setpts=PTS-STARTPTS,fps=24,scale=${W}:${H}:force_original_aspect_ratio=increase:flags=lanczos,crop=${W}:${H},setsar=1,format=yuv420p,settb=1/24[s${i}]`) }) const starts = [] let acc = 0 for (const c of clips) { starts.push(acc); acc += c.len } graph.push(`${clips.map((_, i) => `[s${i}]`).join('')}concat=n=${clips.length}:v=1:a=0,settb=1/24[cat]`) const post = [GRADES[grade]] if (crop !== 'none') post.push(`crop=${outW}:${outH}:(iw-${outW})/2:(ih-${outH})/2`) post.push('format=yuv420p') if (tagPng) { inputs.push('-i', tagPng) graph.push(`[cat]${post.join(',')}[graded]`) graph.push(`[graded][${clips.length}:v]overlay=0:0:format=auto,format=yuv420p[vout]`) } else graph.push(`[cat]${post.join(',')}[vout]`) let audioLabel = null const audioJoins = [] if (audioMode === 'clips') { clips.forEach((c, i) => { // Each clip after the first starts a little early, so the crossfade overlaps sound the picture never // shows and the sounds stay in sync with the picture. const pre = i === 0 ? 0 : Math.min(xfade, c.inT) audioJoins.push(pre) graph.push(`[${i}:a]atrim=start=${f3(c.inT - pre)}:end=${f3(c.outT)},asetpts=PTS-STARTPTS,aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo[ca${i}]`) }) let a = 'ca0' for (let i = 1; i < clips.length; i++) { const d = audioJoins[i] graph.push(d >= 0.01 ? `[${a}][ca${i}]acrossfade=d=${f3(d)}:c1=tri:c2=tri[aj${i}]` : `[${a}][ca${i}]concat=n=2:v=0:a=1[aj${i}]`) a = `aj${i}` } graph.push(`[${a}]afade=t=in:d=0.05,apad=whole_dur=${f3(total)},atrim=0:${f3(total)},afade=t=out:st=${f3(Math.max(0, total - 0.4))}:d=0.4,volume=${gain}dB[aout]`) audioLabel = 'aout' } const common = ['-y', '-hide_banner', '-v', 'error', ...inputs, '-filter_complex', graph.join(';'), '-map', '[vout]'] const video = ['-c:v', 'libx264', '-preset', 'slow', '-profile:v', 'high', '-pix_fmt', 'yuv420p', '-r', '24'] const audio = audioLabel ? ['-map', `[${audioLabel}]`, '-c:a', 'aac', '-b:a', '192k'] : ['-an'] const tailArgs = ['-t', f3(total), '-movflags', '+faststart'] if (opts['dry-run']) { rmSync(work, { recursive: true, force: true }) console.log(`Filter graph:\n${graph.join(';\n')}\n\nDuration: ${total.toFixed(2)} s, ${outW}x${outH}, audio ${audioMode}, tag ${tagOn ? `"${tagText}" ${tagPos}` : 'OFF'}`) process.exit(0) } if (maxMb) { const audioKbps = audioLabel ? 192 : 0 const videoKbps = Math.floor((maxMb * 8 * 1024 * 0.94) / total - audioKbps) if (videoKbps < 600) { rmSync(work, { recursive: true, force: true }); 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, ...audio, ...tailArgs, opts.out], 'ffmpeg pass 2') } else { run('ffmpeg', [...common, ...video, '-crf', String(crf), ...audio, ...tailArgs, opts.out], 'ffmpeg') } rmSync(work, { recursive: true, force: true }) const edl = { file: opts.out, width: outW, height: outH, duration: Number(total.toFixed(3)), grade, crop, audio: audioMode, tag: tagOn ? { text: tagText, position: tagPos, box: tagBox } : null, shots: clips.map((c, i) => ({ n: c.shot.n, beat: c.shot.beat, start: Number(starts[i].toFixed(3)), length: Number(c.len.toFixed(3)), in: c.inT, out: Number(c.outT.toFixed(3)) })), joins: starts.slice(1).map((at, i) => ({ at: Number(at.toFixed(3)), type: 'cut', d: 0, audio_crossfade: Number((audioJoins[i + 1] ?? 0).toFixed(3)) })), } writeFileSync(`${opts.out}.edl.json`, JSON.stringify(edl, null, 2)) const mb = statSync(opts.out).size / 1024 / 1024 console.log(`${opts.out} ${outW}x${outH} ${total.toFixed(2)} s ${mb.toFixed(2)} MB grade=${grade} audio=${audioMode} tag=${tagOn ? `"${tagText}"` : 'OFF'}\nEdit list: ${opts.out}.edl.json\nNext: node scripts/check-stunt.mjs --file ${opts.out} --edl ${opts.out}.edl.json`) if (!tagOn) console.log('The AI-made tag is OFF. Say so in the hand-over: this is a realistic fake with nothing on it that says so, so it needs the platform\'s AI label and a caption that says it is CGI.')