#!/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.')