Skip to content

joeseesun/qiaomu-cut-skill

qiaomu-cut

Verified

把一句话需求转成可复现、可验收视频工程的乔木智能剪辑导演。Use when the user asks to create, plan, edit, remix, explain, narrate, subtitle, animate, composite, or render a video—including one-line requests such as “制作一个科普视频:介绍 LLM 中的 RL”. Builds English-learning movie mixes, person profiles, explainers, code-drawn motion graphics (UI morph loops, showreels, kinetic-type promos, line-art/pixel/Three.js animation, lyric MVs), product launch videos, cinematic shorts, social clips, course/PPT videos, AI image/video/TTS/music-assisted stories, stock-footage stories, or multi-source montage. Routes across 33台词, ClipSeek/open media, local files, ListenHub, image generation, HTML/SVG/Canvas motion graphics with beat-grid storyboards and determinism probes, Manim, ffmpeg-full, captions, sound design, frame-0 video covers with YouTube thumbnails, and release checks.

FileKindSize
SKILL.mdskill md54.0 KB
agents/interface.yamlconfig17.2 KB
agents/openai.yamlconfig323 B
assets/explainer-social/base.cssother24.9 KB
assets/explainer-social/component-runtime.jsscript41.1 KB
assets/explainer-social/scene-shell.htmlother829 B
assets/motion-kit/qiaocut-motion.jsscript8.2 KB
assets/qiaomu-profile/qiaomu_avatar.jpegbinary5.6 MB
assets/qiaomu-profile/qiaomu_reward_qr.pngbinary515.9 KB
assets/qiaomu-profile/qiaomu_wechat_public_account_qr.jpgbinary8.3 KB
references/ad-concept-library.mdmarkdown6.5 KB
references/aesthetic-preferences.mdmarkdown3.0 KB
references/brand-card-templates.mdmarkdown1.6 KB
references/chinese-font-themes.mdmarkdown804 B
references/cinematic-techniques.mdmarkdown2.8 KB
references/code-motion-direction.mdmarkdown11.1 KB
references/cover-thumbnail-method.mdmarkdown6.4 KB
references/english-mix-fast-path.mdmarkdown6.0 KB
references/explainer-autopilot.mdmarkdown11.1 KB
references/feedback-evolution.mdmarkdown37.6 KB
references/ffmpeg-full.mdmarkdown1.7 KB
references/incremental-production.mdmarkdown4.4 KB
references/licensing.mdmarkdown1.9 KB
references/listenhub-provider.mdmarkdown12.6 KB
references/motion-prompt-patterns.mdmarkdown9.3 KB
references/movie-montage-fast-path.mdmarkdown4.4 KB
references/qiaocut-ir.mdmarkdown4.2 KB
references/renderer-engines.mdmarkdown3.3 KB
references/schemas/qiaocut.timeline.v1.schema.jsonconfig7.2 KB
references/social-safe-zones.mdmarkdown3.3 KB
references/source-adapters.mdmarkdown5.7 KB
references/source-selection-gate.mdmarkdown2.5 KB
references/styles/cinematic.mdmarkdown475 B
references/styles/explainer.mdmarkdown1.5 KB
references/styles/social-short.mdmarkdown383 B
references/timeline-schema.mdmarkdown12.2 KB
references/trust-boundary.mdmarkdown3.0 KB
references/workflows.mdmarkdown7.5 KB
scripts/adapters/33tc.jsscript2.1 KB
scripts/adapters/33tc_cli.jsscript4.8 KB
scripts/adapters/clipseek.jsexecutablescript5.4 KB
scripts/adapters/listenhub.jsscript35.7 KB
scripts/adapters/listenhub_cli.jsexecutablescript2.1 KB
scripts/adapters/local.jsscript2.4 KB
scripts/audio_beats.jsscript17.5 KB
scripts/bilingual_typography_smoke.jsscript1.4 KB
scripts/bootstrap_listenhub.shexecutablescript5.4 KB
scripts/bootstrap_macos.shexecutablescript2.5 KB
scripts/brand_templates.jsscript2.4 KB
scripts/brand_templates_smoke.jsscript869 B
scripts/complete_sentence.jsscript3.9 KB
scripts/component_motion_smoke.jsscript21.2 KB
scripts/concept_smoke.jsscript5.6 KB
scripts/cover.jsscript9.1 KB
scripts/cover_smoke.jsscript5.1 KB
scripts/english_mix.jsscript24.1 KB
scripts/english_mix_smoke.jsscript5.7 KB
scripts/explainer_beats.jsscript6.7 KB
scripts/explainer_beats_smoke.jsscript4.8 KB
scripts/explainer_cognitive_timing_smoke.jsscript5.8 KB
scripts/explainer_e2e_smoke.jsscript7.4 KB
scripts/explainer_pipeline.jsscript49.3 KB
scripts/explainer_pipeline_smoke.jsscript12.7 KB
scripts/explainer_spec.jsscript51.4 KB
scripts/explainer_timing.jsscript8.6 KB
scripts/fetch_generated.jsexecutablescript17.4 KB
scripts/ffmpeg_retry_shim_smoke.jsscript2.3 KB
scripts/file_narration_smoke.jsexecutablescript6.6 KB
scripts/ingest_asset.jsexecutablescript15.0 KB
scripts/kinetic_caption_smoke.jsscript1.4 KB
scripts/license_report.jsexecutablescript2.3 KB
scripts/listenhub_narration.jsexecutablescript11.0 KB
scripts/listenhub_smoke.jsexecutablescript26.7 KB
scripts/local_preferences.jsscript1.8 KB
scripts/motion_studio.jsscript55.9 KB
scripts/motion_studio_smoke.jsscript11.0 KB
scripts/movie_montage.jsscript24.7 KB
scripts/movie_montage_smoke.jsscript4.0 KB
scripts/qcut.jsexecutablescript40.8 KB
scripts/release_check.jsscript7.0 KB
scripts/render_project.jsscript85.1 KB
scripts/render_scene.jsscript26.4 KB
scripts/renderers/ass.jsexecutablescript2.7 KB
scripts/renderers/bilingual_ass.jsscript12.6 KB
scripts/renderers/html_scene.jsexecutablescript3.9 KB
scripts/renderers/procedural_music.jsscript7.6 KB
scripts/scene_content_cache.jsscript3.2 KB
scripts/scene_renderer_smoke.jsscript2.8 KB
scripts/security_smoke.jsscript10.2 KB
scripts/sentence_boundary_smoke.jsscript1.6 KB
scripts/setup_deps.jsscript8.4 KB
scripts/shims/ffmpegexecutablescript3.0 KB
scripts/source_review.jsexecutablescript5.1 KB
scripts/timeline_features_smoke.jsscript3.7 KB
scripts/trigger_eval.pyexecutablescript2.5 KB
scripts/validate_skill.pyexecutablescript3.1 KB
scripts/verify_marswave_vendor.jsexecutablescript3.5 KB
scripts/verify_video.jsexecutablescript3.4 KB

scripts/motion_studio.js

View on GitHub
#!/usr/bin/env node
'use strict';

/*
 * qcut motion — code-drawn motion design studio.
 *
 *   init   scaffold motion-brief.json (inputs → direction → structure → build →
 *          gotchas → start), a pure-time scene and the motion kit
 *   check  storyboard-before-code gate: contiguous shots, cuts on the beat grid,
 *          banned list, dead time, one idea per shot, determinism lint
 *   probe  stills at every cut + midpoints, reverse/cold seek determinism proof,
 *          loop seam check and a contact sheet — before any full render
 *   diversity  a batch of films must be genuinely different concepts (archetype, music, structure…)
 *   cover  frame 0 is the cover: render ?cover=<variant> at t=0 as a 2x master,
 *          1280-wide JPG thumbnails and 360/168 feed previews, then gate them
 *   render draft (half resolution, no blur) or final (sub-frame motion blur),
 *          music + peak-aligned SFX, loudness normalization, verification
 */

const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const { spawnSync } = require('child_process');
const { captureBrowserScene, captureStills, projectPath } = require('./render_scene');
const { analyzeBeats, peakOffset } = require('./audio_beats');
const { verifyVideo } = require('./verify_video');
const { lumaStats, checkCover, exportThumbnails, LIMITS: COVER_LIMITS } = require('./cover');

class UsageError extends Error {}

const SCHEMA = 'qiaocut.motion-brief.v1';
const KIT_SOURCE = path.join(__dirname, '..', 'assets', 'motion-kit', 'qiaocut-motion.js');

const BASE_BANNED = ['bouncy/elastic easing', 'particle bursts', 'lens flares', 'neon glows', 'camera shake', 'dead time with nothing changing', 'anything that looks like a template'];

const STYLES = {
  'product-promo': {
    title: '高端极简产品片',
    canvas: { width: 1920, height: 1080, fps: 60, duration: 20 },
    bpm: 120,
    direction: 'High-end minimal. One idea per shot, lots of empty space, one accent color, one clean sans with tight tracking.',
    camera: ['masked type reveals', 'match cuts measured at runtime', 'one smooth camera language', 'motion-blurred whip onto the hero', 'push cuts on stats'],
    banned: ['shockwave rings', 'particle bursts', 'RGB split', 'camera shake', 'lens flares', 'neon glows', 'grid floors', 'flashing backgrounds', 'bouncy easing', 'placeholder cards instead of real UI/footage'],
    structure: ['hook lands word by word on the beats', 'one hook word morphs into the product UI; cursor types and clicks', 'the drop: a shape opens out of the button into a new scene', 'key feature as big type', 'real UI/footage hero moment', 'proof: big stats on push cuts', 'logo reveal', 'fade to black'],
    inputs: ['product name + one-line promise', '3–5 UI moments to show', 'one accent color', 'real screenshots/clips the user owns', 'licensed song with a clear drop (optional)']
  },
  'ui-morph-loop': {
    title: 'UI 形态变换循环',
    canvas: { width: 1440, height: 1440, fps: 60, duration: 14 },
    bpm: 120,
    loop: true,
    direction: 'Dribbble-level UI motion. One shape, never cut: every state is the same element morphing size, radius and color while its content swaps with a short blur. A cursor drives every change with real clicks and drags. Springs everywhere, a tiny overshoot at most.',
    camera: ['camera zooms so each state fills the frame', 'no cuts — continuous morph', 'last frame equals first frame'],
    banned: ['bouncy easing', 'particle bursts', 'glows', 'gradients on UI chrome', 'mismatched icon strokes', 'dead time', 'anything that looks like a template'],
    structure: ['button', 'loader', 'check', 'dynamic island', 'player with play/pause morph', 'scrub → volume slider stretching past max', 'toggle on the beat', 'knob → liquid tab indicator', 'tabs → self-drawing chart', 'collapse to ⌘K → type → toast → back to button'],
    inputs: ['8–12 UI states', 'black/white or one accent color', 'licensed ~120 BPM song (optional)']
  },
  showreel: {
    title: '动态设计 Showreel',
    canvas: { width: 1920, height: 1080, fps: 60, duration: 15 },
    bpm: 128,
    direction: 'A motion designer showing range in 15 seconds: typographic, geometric and camera craft, each beat a new idea, one coherent palette.',
    camera: ['kinetic typography', 'match cuts', 'whip pans', 'dramatic cuts on downbeats', 'orbiting camera'],
    banned: BASE_BANNED,
    structure: ['cold-open typographic hit', 'geometric transformation', 'camera move through layers', 'kinetic type sequence', 'signature end card'],
    inputs: ['name/brand for the end card', 'palette or reference', 'licensed track (optional)']
  },
  'line-art-explainer': {
    title: '线稿/手绘讲解动画',
    canvas: { width: 1920, height: 1080, fps: 30, duration: 45 },
    bpm: null,
    direction: 'Light, playful line art drawn on in real time; each concept is literally drawn when the narration names it. Paper texture, one ink color plus one accent.',
    camera: ['draw-on strokes', 'slow push toward the active drawing', 'wipe-by-stroke transitions', 'callout labels drawn by hand'],
    banned: ['generic infographic look', 'stock clip-art', 'glossy 3D', 'photoreal faces', 'text walls'],
    structure: ['hook drawing', 'setup', 'mechanism step 1', 'mechanism step 2', 'mechanism step 3', 'payoff', 'outro'],
    inputs: ['topic or script / narration audio', 'subtitle language(s)', 'target platform']
  },
  'lyric-mv': {
    title: '歌词 MV / 动态排版 MV',
    canvas: { width: 1080, height: 1920, fps: 30, duration: 30 },
    bpm: 100,
    direction: 'The lyrics are the protagonist: big kinetic typography whose rhythm follows the vocal line; a strong visual hook in the first two seconds.',
    camera: ['word-by-word hits on vocal onsets', 'scale/position jumps on downbeats', 'hand-drawn texture layer', 'chorus gets the biggest visual idea'],
    banned: ['karaoke bar look', 'lyric text over busy footage without contrast', 'random effects unrelated to lyrics', 'dead time in instrumental gaps'],
    structure: ['visual hook', 'verse', 'pre-chorus build', 'chorus drop', 'outro'],
    inputs: ['song audio the user has rights to', 'lyrics with timing or a clean vocal', 'mood/reference images']
  },
  'pixel-art': {
    title: '像素动画',
    canvas: { width: 1280, height: 720, fps: 60, duration: 10 },
    bpm: null,
    loop: true,
    direction: 'Polished 16-bit sprite animation: fixed low logical resolution scaled by an integer factor, fixed palette, every coordinate snapped to the pixel grid, 8–12 fps pose feel.',
    camera: ['integer-scaled blit, imageSmoothingEnabled=false', 'state machine: idle → charge → act → recover', '1–2 px screen shake only on impact'],
    banned: ['sub-pixel positions', 'anti-aliasing', 'gradients or shadowBlur', 'colors outside the palette', 'vector shapes scaled down'],
    structure: ['idle', 'charge', 'action', 'recover → loop'],
    inputs: ['character/subject', 'palette mood', 'loop or story']
  },
  'cinematic-3d': {
    title: '代码电影 / Three.js 场景',
    canvas: { width: 1920, height: 1080, fps: 30, duration: 60 },
    bpm: null,
    direction: 'A cinematic film that happens to be rendered with code: atmosphere, scale, weather and light carry emotion; research-accurate staging; never a strategy-game or infographic look.',
    camera: ['establishing aerial', 'slow dolly through smoke/volumetrics', 'rack focus between layers', 'map inserts only when they explain'],
    banned: ['generic infographic look', 'strategy-game camera', 'primitive box figures', 'floating/sliding characters', 'unmotivated camera spins'],
    structure: ['establish world', 'stakes', 'turning point', 'climax', 'aftermath'],
    inputs: ['topic + facts to be accurate about', 'visual references (paintings, stills)', 'narration or not']
  }
};

function parseArgs(argv) {
  const positional = [];
  const flags = {};
  for (let index = 0; index < argv.length; index += 1) {
    const token = argv[index];
    if (!token.startsWith('--')) { positional.push(token); continue; }
    const equal = token.indexOf('=');
    if (equal > 2) { flags[token.slice(2, equal)] = token.slice(equal + 1); continue; }
    const next = argv[index + 1];
    if (!next || next.startsWith('--')) flags[token.slice(2)] = true;
    else { flags[token.slice(2)] = next; index += 1; }
  }
  return { positional, flags };
}

function round(value, digits = 3) {
  const scale = 10 ** digits;
  return Math.round(value * scale) / scale;
}

function sha256File(file) {
  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
}

function writeJson(file, value) {
  fs.mkdirSync(path.dirname(file), { recursive: true });
  const temporary = `${file}.tmp-${process.pid}`;
  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
  fs.renameSync(temporary, file);
}

function readBrief(root) {
  const file = path.join(root, 'motion-brief.json');
  if (!fs.existsSync(file)) throw new Error('motion-brief.json not found. Run qcut motion init first.');
  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
  catch (error) { throw new Error(`motion-brief.json is not valid JSON: ${error.message}`); }
}

function loadGrid(root, brief) {
  const ref = brief.audio && brief.audio.beatGrid;
  if (ref) {
    const file = projectPath(root, ref, 'audio.beatGrid');
    if (fs.existsSync(file)) return JSON.parse(fs.readFileSync(file, 'utf8'));
  }
  const bpm = Number(brief.audio && brief.audio.bpm);
  if (bpm > 0) {
    const duration = Number(brief.canvas.duration);
    const period = 60 / bpm;
    const first = Number(brief.audio.firstDownbeat || 0);
    const beats = [];
    for (let time = first; time <= duration + 1e-6; time += period) beats.push(round(time));
    return { bpm, beatsPerBar: 4, beats, downbeats: beats.filter((_, index) => index % 4 === 0), firstDownbeat: first, synthetic: true };
  }
  return null;
}

// Non-loop films open on the cover (s00, two beats or 1 s): frame 0 = thumbnail.
function coverSeconds(bpm) {
  return bpm ? round((2 * 60) / bpm) : 1;
}

function storyboardSkeleton(style, canvas, bpm, options = {}) {
  const cover = options.cover ? coverSeconds(options.coverBpm || bpm) : 0;
  const body = canvas.duration - cover;
  const beats = style.structure.length;
  const barSeconds = bpm ? (4 * 60) / bpm : null;
  const shots = [];
  if (cover) {
    shots.push({
      id: 's00',
      cover: true,
      start: 0,
      end: cover,
      idea: 'TODO: cover = frame 0 = thumbnail (references/cover-thumbnail-method.md): one archetype, one focal point, ≤ 6 CJK / 4 words, hold ≤ 0.7 s then exit on the beat',
      onScreenText: options.title || '',
      camera: 'locked-off cover; exit in the last 0.3 s',
      transitionIn: 'frame 0',
      events: [{ at: 0, what: 'cover fully readable' }]
    });
  }
  let cursor = 0;
  for (let index = 0; index < beats; index += 1) {
    let end = index === beats - 1 ? body : (body * (index + 1)) / beats;
    if (barSeconds) end = index === beats - 1 ? body : Math.max(cursor + barSeconds, Math.round(end / barSeconds) * barSeconds);
    end = Math.min(body, round(end));
    if (end <= cursor) continue;
    shots.push({
      id: `s${String(index + 1).padStart(2, '0')}`,
      start: round(cursor + cover),
      end: round(end + cover),
      idea: `TODO: ${style.structure[index]}`,
      onScreenText: '',
      camera: 'TODO',
      transitionIn: index === 0 ? (cover ? 'cut from the cover on the downbeat' : 'cold open') : 'TODO',
      events: []
    });
    cursor = end;
  }
  if (shots.length && shots[shots.length - 1].end < canvas.duration) shots[shots.length - 1].end = canvas.duration;
  return shots;
}

function sceneTemplate(brief) {
  const { width, height } = brief.canvas;
  return `<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=${width}, height=${height}">
<title>${String(brief.title).replace(/</g, '&lt;')}</title>
<style>
  /* No CSS transitions/animations: every style is computed inside seek(t). */
  html, body { margin: 0; width: ${width}px; height: ${height}px; overflow: hidden; background: #f4f3f1; }
  body { font-family: "Geist", "Inter", "PingFang SC", "Noto Sans CJK SC", system-ui, sans-serif; color: #0b0b0c; }
  #stage { position: absolute; inset: 0; }
  .shape { position: absolute; left: 50%; top: 50%; background: #0b0b0c; }
  .label { position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%); color: #f4f3f1; font-weight: 600; letter-spacing: -0.02em; white-space: nowrap; }
</style>
</head>
<body>
<div id="stage">
  <div class="shape" id="shape"></div>
  <div class="label" id="label"></div>
</div>
<script src="../lib/qiaocut-motion.js"></script>
<script>
  // Starter scene: one element morphing between storyboard states on springs.
  // Replace freely, but keep seek(t) a pure function of t.
  const M = window.QiaoCutMotion;
  const DURATION = ${brief.canvas.duration};
  const SHOTS = ${JSON.stringify(brief.storyboard.map((shot) => ({ start: shot.start, end: shot.end, text: shot.onScreenText || '' })))};
  const shape = document.getElementById('shape');
  const label = document.getElementById('label');
  const unit = Math.min(${width}, ${height}) / 1080;
  label.style.fontSize = (56 * unit) + 'px';
  // Measure every label once at load (deterministic) so the container can
  // spring to fit its content; empty labels collapse to a dot.
  const SIZES = SHOTS.map((shot) => {
    label.textContent = shot.text;
    const w = shot.text ? label.offsetWidth + 96 * unit : 40 * unit;
    const h = shot.text ? label.offsetHeight + 56 * unit : 40 * unit;
    return { w, h, r: h / 2 };
  });
  const key = (prop) => SHOTS.map((shot, i) => ({ t: shot.start, value: SIZES[i][prop] }));
  const W = key('w'); const H = key('h'); const R = key('r');

  function seek(t) {
    const spring = { response: 0.42, damping: 0.86 };
    const w = M.springTrack(t, W, spring);
    const h = M.springTrack(t, H, spring);
    const r = M.springTrack(t, R, spring);
    shape.style.width = w + 'px';
    shape.style.height = h + 'px';
    shape.style.borderRadius = r + 'px';
    shape.style.transform = 'translate(-50%, -50%)';
    const found = SHOTS.findIndex((shot) => t >= shot.start && t < shot.end);
    const index = found < 0 ? SHOTS.length - 1 : found;
    const swapAt = SHOTS[index].start + 0.09;
    const s = M.swap(t, swapAt, 0.18);
    const incoming = t >= swapAt || index === 0;
    label.textContent = incoming ? SHOTS[index].text : SHOTS[index - 1].text;
    label.style.opacity = index === 0 && t < swapAt ? 1 : incoming ? s.incoming : s.outgoing;
    label.style.filter = 'blur(' + s.blur.toFixed(2) + 'px)';
    const fade = M.progress(t, DURATION - 0.4, DURATION);
    document.getElementById('stage').style.opacity = ${brief.loop ? '1' : '1 - fade'};
  }
  M.register(seek, { duration: DURATION });
  seek(0);
</script>
</body>
</html>
`;
}

function commandInit(root, flags) {
  const styleId = String(flags.style || 'product-promo');
  const style = STYLES[styleId];
  if (!style) throw new UsageError(`Unknown style: ${styleId}. Choose one of ${Object.keys(STYLES).join(', ')}.`);
  fs.mkdirSync(root, { recursive: true });
  const briefFile = path.join(root, 'motion-brief.json');
  if (fs.existsSync(briefFile) && !flags.force) throw new Error('motion-brief.json already exists. Re-run with --force to replace it.');
  const canvas = {
    width: Number(flags.width || style.canvas.width),
    height: Number(flags.height || style.canvas.height),
    fps: Number(flags.fps || style.canvas.fps),
    duration: Number(flags.duration || style.canvas.duration)
  };
  if (canvas.width % 2 || canvas.height % 2) throw new UsageError('width and height must be even.');
  let grid = null;
  let music = null;
  if (flags.audio) {
    const audio = projectPath(root, String(flags.audio), '--audio', true);
    music = path.relative(root, audio);
    grid = analyzeBeats(audio, { bpm: flags.bpm, displaySource: music });
    writeJson(path.join(root, 'reports', 'beat-grid.json'), grid);
  }
  const bpm = grid ? grid.bpm : (flags.bpm ? Number(flags.bpm) : style.bpm);
  const brief = {
    schema: SCHEMA,
    title: String(flags.title || style.title),
    style: styleId,
    canvas,
    loop: Boolean(flags.loop || style.loop),
    inputs: { ask: style.inputs, provided: {}, missing: [] },
    direction: {
      oneLine: String(flags.direction || style.direction),
      references: [],
      palette: [],
      typography: [],
      cameraLanguage: style.camera,
      banned: style.banned
    },
    audio: {
      music: music ? { path: music, inPoint: 0 } : null,
      bpm: bpm || null,
      firstDownbeat: grid ? 0 : 0,
      beatGrid: grid ? 'reports/beat-grid.json' : null,
      sfx: [],
      loudnessLUFS: -14
    },
    cover: Boolean(flags.loop || style.loop) ? null : {
      frame: 0,
      holdSeconds: 0.7,
      exitSeconds: 0.3,
      promise: 'TODO: what the viewer gets, in one sentence (the title explains, the cover shows)',
      archetype: 'TODO: before-after | product-hero | big-number | face-emotion | result-first | series',
      variants: { a: 'TODO: main concept (also frame 0 of the film)', b: 'TODO: alternative for Test & Compare' },
      method: 'references/cover-thumbnail-method.md'
    },
    concept: {
      archetype: 'TODO: manifesto-typography | kinetic-typography | silhouette-dance | spatial-flight | product-hero | before-after | one-day | user-story',
      reference: 'TODO: name a real ad or film (e.g. Apple iPod Silhouette, Apple Vision Pro launch film)',
      device: 'TODO: the one mechanism that recurs through the whole film',
      tempo: bpm || null,
      musicStyle: 'TODO: e.g. solo-piano-waltz | trap-house-808 | funk-house | cinematic-ambient-no-drums',
      typeStyle: 'TODO: e.g. serif-STSong | heavy-grotesque | rounded | ultralight',
      palette: [],
      camera: 'TODO',
      structure: 'TODO: the beats of the film in one line',
      method: 'references/ad-concept-library.md'
    },
    storyboard: [],
    build: { scene: 'scenes/main.html', motionBlurSubframes: 3, shutter: 0.5 },
    gotchas: [
      'Never put will-change on anything the camera scales, or text renders blurry.',
      'Never set opacity or filter on a preserve-3d element; fade its wrapper instead.',
      'Text swapping inside a morphing container needs its own enter/exit timing.',
      'Measure element positions at runtime for match cuts.',
      'A loop needs the last frame identical to the first, cursor position and speed included.'
    ],
    approval: { mode: String(flags.mode || 'ask'), storyboardApproved: false, note: 'ask: show the storyboard on the beat grid and wait for approval before final render; autopilot: one-line request, proceed after probe passes.' }
  };
  if (grid) {
    brief.audio.firstDownbeat = grid.firstDownbeat;
    brief.audio.note = `Beat grid from music: ${grid.bpm} BPM, first downbeat ${grid.firstDownbeat}s${grid.drop ? `, drop at ${grid.drop.time}s` : ''}. Set audio.music.inPoint so video t=0 lands on a downbeat.`;
  }
  const gridForSkeleton = grid ? null : bpm;
  brief.storyboard = storyboardSkeleton(style, canvas, gridForSkeleton, { cover: Boolean(brief.cover), title: brief.title, coverBpm: bpm });
  if (grid) {
    // Snap skeleton cuts to real downbeats (or beats when bars are scarce).
    const frame = 1 / canvas.fps;
    const coverShot = brief.storyboard[0] && brief.storyboard[0].cover ? brief.storyboard.shift() : null;
    if (coverShot) {
      // End the cover on the real beat nearest to two beats in, so the hook lands on the grid.
      const snapped = nearest(grid.beats.filter((time) => time > frame), coverShot.end);
      if (snapped != null) coverShot.end = round(snapped);
    }
    const floor = coverShot ? coverShot.end : 0;
    const inside = (list) => list.filter((time) => time > floor + frame && time < canvas.duration - frame);
    let candidates = inside(grid.downbeats);
    if (candidates.length < brief.storyboard.length - 1) candidates = inside(grid.beats);
    const count = Math.min(brief.storyboard.length, candidates.length + 1);
    const cuts = [];
    for (let k = 1; k < count; k += 1) {
      const pick = candidates[Math.min(candidates.length - 1, Math.round((k * candidates.length) / count) - (k === count ? 1 : 0))];
      if (pick != null && (!cuts.length || pick > cuts[cuts.length - 1])) cuts.push(pick);
    }
    const bounds = [floor, ...cuts, canvas.duration];
    brief.storyboard = brief.storyboard.slice(0, bounds.length - 1).map((shot, index) => ({ ...shot, start: round(bounds[index]), end: round(bounds[index + 1]) }));
    if (coverShot) brief.storyboard.unshift(coverShot);
  }
  writeJson(briefFile, brief);
  const sceneFile = path.join(root, 'scenes', 'main.html');
  if (!fs.existsSync(sceneFile) || flags.force) {
    fs.mkdirSync(path.dirname(sceneFile), { recursive: true });
    fs.writeFileSync(sceneFile, sceneTemplate(brief));
  }
  fs.mkdirSync(path.join(root, 'lib'), { recursive: true });
  fs.copyFileSync(KIT_SOURCE, path.join(root, 'lib', 'qiaocut-motion.js'));
  for (const directory of ['assets', 'renders', 'reports']) fs.mkdirSync(path.join(root, directory), { recursive: true });
  return {
    ok: true,
    project: root,
    style: styleId,
    canvas,
    bpm: brief.audio.bpm,
    beatGrid: brief.audio.beatGrid,
    shots: brief.storyboard.length,
    next: 'Fill motion-brief.json (direction, references, storyboard ideas/camera/events), rewrite scenes/main.html, then run qcut motion check.'
  };
}

function commandScene(root, flags) {
  const brief = readBrief(root);
  const scene = projectPath(root, (brief.build && brief.build.scene) || 'scenes/main.html', 'build.scene');
  if (fs.existsSync(scene) && !flags.force) throw new Error(`${path.relative(root, scene)} exists. Re-run with --force to regenerate the starter scene.`);
  fs.mkdirSync(path.dirname(scene), { recursive: true });
  fs.writeFileSync(scene, sceneTemplate(brief));
  fs.mkdirSync(path.join(root, 'lib'), { recursive: true });
  fs.copyFileSync(KIT_SOURCE, path.join(root, 'lib', 'qiaocut-motion.js'));
  return { ok: true, scene: path.relative(root, scene), shots: brief.storyboard.length };
}

const DETERMINISM_LINT = [
  { pattern: /Math\.random\s*\(/, message: 'Math.random() makes frames non-reproducible; use QiaoCutMotion.random(index, seed).' },
  { pattern: /\bset(?:Timeout|Interval)\s*\(/, message: 'Timers carry state between frames; compute from t inside seek(t).' },
  { pattern: /\bDate\.now\s*\(|\bperformance\.now\s*\(/, message: 'Wall-clock time breaks seeking; use the t passed to seek(t).' },
  { pattern: /requestAnimationFrame\s*\(/, message: 'requestAnimationFrame loops are not seekable; register seek(t) with QiaoCutMotion.register.' },
  { pattern: /transition\s*:\s*(?!none)[^;]*\d/, message: 'CSS transitions animate outside the seek clock; compute styles from t instead.' }
];

function lintScene(file) {
  const errors = [];
  const warnings = [];
  const text = fs.readFileSync(file, 'utf8');
  const stripped = text.replace(/<script[^>]+src=[^>]+><\/script>/g, '');
  for (const rule of DETERMINISM_LINT) if (rule.pattern.test(stripped)) errors.push(rule.message);
  if (/will-change/.test(text)) warnings.push('will-change found: never put it on anything the camera scales (blurry text).');
  if (/preserve-3d/.test(text) && /(opacity|filter)\s*:/.test(text)) warnings.push('preserve-3d plus opacity/filter found: fade a wrapper, not the preserve-3d element.');
  if (/cubic-bezier\([^)]*-?\d*\.?\d+\s*,\s*-?\d*\.?\d+\s*,\s*-?\d*\.?\d+\s*,\s*(1\.[1-9]|[2-9])/.test(text)) warnings.push('Overshooting cubic-bezier found: overshoot should come from springs only.');
  if (!/__QIAOCUT_SET_TIME__|QiaoCutMotion\.register|M\.register|\.register\(/.test(text) && !/@keyframes/.test(text)) {
    errors.push('Scene exposes no seek clock: call QiaoCutMotion.register(seek) or define window.__QIAOCUT_SET_TIME__.');
  }
  return { errors, warnings };
}

function nearest(values, target) {
  let best = null;
  for (const value of values) if (best == null || Math.abs(value - target) < Math.abs(best - target)) best = value;
  return best;
}

function cjkAwareLength(text) {
  const value = String(text || '');
  const cjk = (value.match(/[\u3400-\u9fff]/g) || []).length;
  const words = value.replace(/[\u3400-\u9fff]/g, ' ').split(/\s+/).filter(Boolean).length;
  return { cjk, words };
}

function checkBrief(root, brief) {
  const errors = [];
  const warnings = [];
  const add = (list, code, message, extra = {}) => list.push({ code, message, ...extra });
  if (brief.schema !== SCHEMA) add(errors, 'schema', `schema must be ${SCHEMA}.`);
  const canvas = brief.canvas || {};
  const fps = Number(canvas.fps);
  const duration = Number(canvas.duration);
  if (!(canvas.width > 0 && canvas.height > 0 && fps > 0 && duration > 0)) add(errors, 'canvas', 'canvas needs width, height, fps and duration.');
  const frame = fps > 0 ? 1 / fps : 1 / 30;
  const direction = brief.direction || {};
  if (!String(direction.oneLine || '').trim()) add(errors, 'direction', 'direction.oneLine must state the look in one sentence.');
  if (!Array.isArray(direction.banned) || direction.banned.length < 3) add(errors, 'banned-list', 'direction.banned needs at least 3 explicit bans to suppress template look.');
  if (!Array.isArray(direction.references) || direction.references.length === 0) {
    add(warnings, 'references', 'No reference image/video: references beat adjectives. Add one or record {kind:"none", why}.');
  }
  const approval = brief.approval || {};
  const missing = (brief.inputs && brief.inputs.missing) || [];
  if (approval.mode === 'ask' && missing.length) add(errors, 'inputs-missing', `Ask the user for: ${missing.join('; ')}.`);
  const shots = Array.isArray(brief.storyboard) ? brief.storyboard : [];
  if (!shots.length) add(errors, 'storyboard-empty', 'Write the storyboard before any scene code.');
  const grid = loadGrid(root, brief);
  const beats = grid ? grid.beats.map((time) => time - Number((brief.audio && brief.audio.music && brief.audio.music.inPoint) || 0)).filter((time) => time >= -frame) : null;
  const downbeats = grid ? grid.downbeats.map((time) => time - Number((brief.audio && brief.audio.music && brief.audio.music.inPoint) || 0)) : null;
  const barSeconds = grid ? (4 * 60) / grid.bpm : null;
  const ids = new Set();
  let cursor = 0;
  shots.forEach((shot, index) => {
    const label = shot.id || `storyboard[${index}]`;
    if (!shot.id) add(errors, 'shot-id', `${label} needs an id.`);
    else if (ids.has(shot.id)) add(errors, 'shot-id', `Duplicate shot id ${shot.id}.`);
    ids.add(shot.id);
    const start = Number(shot.start);
    const end = Number(shot.end);
    if (!(end > start)) add(errors, 'shot-time', `${label} needs start < end.`);
    if (Math.abs(start - cursor) > frame + 1e-6) add(errors, 'shot-contiguity', `${label} starts at ${start}s but the previous shot ended at ${round(cursor)}s (gap/overlap).`);
    cursor = end;
    for (const field of ['idea', 'camera']) {
      const value = String(shot[field] || '').trim();
      if (!value || /^todo\b/i.test(value)) add(errors, 'shot-unwritten', `${label}.${field} is not written yet.`);
    }
    if (index > 0 && !String(shot.transitionIn || '').trim()) add(warnings, 'transition', `${label} has no transitionIn; name the cut (match cut, whip, push, hard cut on downbeat…).`);
    const { cjk, words } = cjkAwareLength(shot.onScreenText);
    if (cjk > 18 || words > 12) add(warnings, 'one-idea', `${label} on-screen text is long (${cjk} CJK / ${words} words); one idea per shot.`);
    if (beats && index > 0) {
      const near = nearest(beats, start);
      if (near == null || Math.abs(near - start) > frame + 1e-6) add(errors, 'off-grid', `${label} cut at ${start}s is off the beat grid (nearest beat ${near == null ? 'n/a' : round(near)}s).`);
      else if (downbeats && Math.abs(nearest(downbeats, start) - start) > frame + 1e-6) add(warnings, 'not-downbeat', `${label} cut at ${start}s is on a beat but not a downbeat.`);
    }
    const events = Array.isArray(shot.events) ? shot.events : [];
    const limit = barSeconds ? barSeconds * 2 : 4;
    if (end - start > limit + frame && events.length === 0) add(warnings, 'dead-time', `${label} lasts ${round(end - start)}s with no events[]; something should happen on every beat or bar.`);
    for (const event of events) {
      const at = Number(event && event.at);
      if (!(at >= start && at <= end)) add(errors, 'event-time', `${label} event at ${event && event.at} is outside the shot.`);
    }
  });
  if (!brief.loop) {
    // Frame 0 is the cover (references/cover-thumbnail-method.md): never open on black.
    const cover = brief.cover;
    if (!cover || typeof cover !== 'object') add(errors, 'cover-missing', 'Non-loop films open on a cover: add brief.cover {frame:0, holdSeconds, promise, archetype, variants} and make storyboard[0] the cover shot (see references/cover-thumbnail-method.md).');
    else {
      for (const field of ['promise', 'archetype']) {
        const value = String(cover[field] || '').trim();
        if (!value || /^todo\b/i.test(value)) add(errors, 'cover-unwritten', `cover.${field} is not written yet.`);
      }
      if (Number(cover.holdSeconds) > 0.7 + frame) add(warnings, 'cover-hold', `cover.holdSeconds ${cover.holdSeconds}s: hold the full cover for at most 0.7 s, then exit on the beat.`);
      const first = shots[0];
      if (first && !(first.cover === true || first.id === 's00')) add(warnings, 'cover-shot', `storyboard[0] (${first.id}) is not the cover shot; mark it cover:true or id s00.`);
      if (first && Number(first.end) - Number(first.start) > 1.5 + frame) add(warnings, 'cover-length', `The cover shot lasts ${round(Number(first.end) - Number(first.start))}s; keep it ≤ 1.5 s so the hook arrives fast.`);
      const text = cjkAwareLength(first && first.onScreenText);
      if (text.cjk > 6 || text.words > 4) add(warnings, 'cover-text', `Cover text is ${text.cjk} CJK / ${text.words} words; keep ≤ 6 CJK or ≤ 4 words.`);
    }
  }
  {
    // One film, one concept (references/ad-concept-library.md). Older briefs without a concept only warn.
    const concept = brief.concept;
    if (!concept || typeof concept !== 'object') add(warnings, 'concept-missing', 'No brief.concept: name the archetype, a real reference ad, the recurring device, music style and type style (references/ad-concept-library.md).');
    else {
      for (const field of ['archetype', 'reference', 'device', 'musicStyle', 'typeStyle', 'structure']) {
        const value = String(concept[field] || '').trim();
        if (!value || /^todo\b/i.test(value)) add(errors, 'concept-unwritten', `concept.${field} is not written yet.`);
      }
      if (!Array.isArray(concept.palette) || concept.palette.length < 2) add(warnings, 'concept-palette', 'concept.palette should list at least two colours.');
    }
  }
  if (shots.length && Math.abs(cursor - duration) > frame + 1e-6) add(errors, 'storyboard-duration', `Storyboard ends at ${round(cursor)}s but canvas.duration is ${duration}s.`);
  const audio = brief.audio || {};
  if (audio.music && audio.music.path) {
    try { projectPath(root, audio.music.path, 'audio.music.path', true); }
    catch (error) { add(errors, 'music', error.message); }
    if (!audio.music.license) add(warnings, 'music-license', 'audio.music.license is empty; only use music whose license allows the intended (commercial) use.');
  }
  for (const [index, cue] of (audio.sfx || []).entries()) {
    try { projectPath(root, cue.path, `audio.sfx[${index}].path`, true); }
    catch (error) { add(errors, 'sfx', error.message); }
    if (!(Number(cue.at) >= 0 && Number(cue.at) < duration)) add(errors, 'sfx-time', `audio.sfx[${index}].at must be inside the video.`);
  }
  let lint = { errors: [], warnings: [] };
  const build = brief.build || {};
  try {
    const scene = projectPath(root, build.scene || 'scenes/main.html', 'build.scene', true);
    lint = lintScene(scene);
  } catch (error) {
    add(errors, 'scene', error.message);
  }
  for (const message of lint.errors) add(errors, 'determinism', message);
  for (const message of lint.warnings) add(warnings, 'gotcha', message);
  const awaitingApproval = approval.mode !== 'autopilot' && approval.storyboardApproved !== true;
  return {
    ok: errors.length === 0,
    status: errors.length ? 'blocked' : awaitingApproval ? 'awaiting-storyboard-approval' : 'ready',
    errors,
    warnings,
    grid: grid ? { bpm: grid.bpm, beats: grid.beats.length, synthetic: Boolean(grid.synthetic) } : null,
    shots: shots.length,
    storyboard: shots.map((shot) => ({ id: shot.id, start: shot.start, end: shot.end, idea: shot.idea, camera: shot.camera, transitionIn: shot.transitionIn }))
  };
}

function commandCheck(root) {
  const brief = readBrief(root);
  const result = checkBrief(root, brief);
  writeJson(path.join(root, 'reports', 'motion-check.json'), { checkedAt: new Date().toISOString(), ...result });
  return result;
}

function ffmpegPath() {
  const candidates = [process.env.QIAOMU_FFMPEG, '/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg', '/usr/local/opt/ffmpeg-full/bin/ffmpeg', '/opt/homebrew/bin/ffmpeg', 'ffmpeg'];
  for (const candidate of candidates) {
    if (!candidate) continue;
    if (!candidate.includes('/')) {
      const found = spawnSync('which', [candidate], { encoding: 'utf8' });
      if (found.status === 0) return found.stdout.trim();
    } else if (fs.existsSync(candidate)) return candidate;
  }
  throw new Error('ffmpeg is required.');
}

function runFfmpeg(args, cwd) {
  const result = spawnSync(ffmpegPath(), args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
  if (result.status !== 0) throw new Error(`ffmpeg failed: ${String(result.stderr || '').slice(-1500)}`);
  return result;
}

function psnr(root, a, b) {
  const result = spawnSync(ffmpegPath(), ['-hide_banner', '-i', a, '-i', b, '-lavfi', 'psnr', '-f', 'null', '-'], { cwd: root, encoding: 'utf8' });
  const match = /average:(inf|[\d.]+)/.exec(result.stderr || '');
  if (!match) return null;
  return match[1] === 'inf' ? Infinity : Number(match[1]);
}

async function commandProbe(root, flags) {
  const brief = readBrief(root);
  const check = checkBrief(root, brief);
  if (!check.ok) return { ok: false, stage: 'check', errors: check.errors };
  const { width, height, duration } = brief.canvas;
  let times = [];
  if (flags.times) times = String(flags.times).split(',').map(Number).filter((value) => value >= 0 && value <= duration);
  else {
    for (const shot of brief.storyboard) {
      times.push(Number(shot.start) + 0.001, (Number(shot.start) + Number(shot.end)) / 2);
      for (const event of shot.events || []) times.push(Number(event.at));
    }
    times.push(Math.max(0, duration - 1 / brief.canvas.fps));
  }
  times = [...new Set(times.map((time) => round(Math.min(duration, Math.max(0, time)))))].sort((a, b) => a - b);
  const limit = Number(flags.max || 32);
  if (times.length > limit) times = times.filter((_, index) => index % Math.ceil(times.length / limit) === 0);
  if (brief.loop) times = [...new Set([0, ...times, duration])].sort((a, b) => a - b);
  else if (!times.includes(0)) times = [0, ...times];
  const outDir = path.join(root, 'reports', 'motion-probe');
  fs.rmSync(outDir, { recursive: true, force: true });
  const scene = projectPath(root, brief.build.scene, 'build.scene', true);
  const capture = await captureStills({ projectRoot: root, source: scene, width, height, times, outDir, scale: Number(flags.scale || (width > 1280 ? 0.5 : 1)) });
  // Byte mismatches from Chrome raster history (layer promotion changes text
  // antialiasing by one level on a few pixels) are noise; real state leaks are not.
  if (capture.determinism) {
    const nameFor = (time) => `t${time.toFixed(3).replace('.', '_')}.png`;
    for (const item of capture.determinism.mismatches) {
      const value = item.file ? psnr(root, path.join('reports', 'motion-probe', nameFor(item.time)), item.file) : null;
      item.psnr = value === Infinity ? 'inf' : value;
      item.rasterNoise = value === Infinity || (value != null && value >= 50);
    }
    const real = capture.determinism.mismatches.filter((item) => !item.rasterNoise);
    capture.determinism.deterministic = real.length === 0;
    capture.determinism.rasterNoiseOnly = capture.determinism.mismatches.length - real.length;
    capture.determinism.rule = 'frames must match byte-for-byte, or differ only by raster noise (PSNR >= 50 dB)';
  }
  let loop = null;
  if (brief.loop) {
    const first = capture.stills.find((item) => item.time === 0);
    const last = capture.stills.find((item) => item.time === round(duration));
    const value = first && last ? psnr(root, first.file, last.file) : null;
    loop = { firstFrame: first && first.file, lastFrame: last && last.file, psnr: value === Infinity ? 'inf' : value, seamless: value === Infinity || (value != null && value >= 40) };
  }
  const columns = Math.min(6, capture.stills.length);
  const sheet = path.join(outDir, 'contact-sheet.jpg');
  const inputs = capture.stills.map((item) => item.file);
  const rows = Math.ceil(inputs.length / columns);
  const listFile = path.join(outDir, 'frames.txt');
  fs.writeFileSync(listFile, inputs.map((file) => `file '${path.resolve(root, file).replace(/'/g, "'\\''")}'`).join('\n'));
  try {
    runFfmpeg(['-hide_banner', '-loglevel', 'error', '-y', '-f', 'concat', '-safe', '0', '-i', listFile,
      '-vf', `scale=480:-2,tile=${columns}x${rows}:padding=6:color=0x202020`, '-frames:v', '1', sheet], root);
  } catch (_) { /* contact sheet is a convenience */ }
  let cover = null;
  if (!brief.loop) {
    const still = capture.stills.find((item) => item.time === 0);
    const frame0 = still ? lumaStats(path.resolve(root, still.file)) : null;
    cover = {
      frame0,
      notBlack: Boolean(frame0 && frame0.mean >= COVER_LIMITS.blackMean),
      contrastOk: Boolean(frame0 && frame0.std >= COVER_LIMITS.flatStd),
      rule: `frame 0 is the cover: mean luma ≥ ${COVER_LIMITS.blackMean}, std ≥ ${COVER_LIMITS.flatStd} (warning)`
    };
  }
  const report = {
    ok: Boolean(capture.determinism ? capture.determinism.deterministic : true) && (!loop || loop.seamless) && (!cover || cover.notBlack),
    probedAt: new Date().toISOString(),
    sceneSha256: sha256File(scene),
    briefSha256: sha256File(path.join(root, 'motion-brief.json')),
    frames: capture.stills.length,
    stills: capture.stills.map((item) => ({ time: item.time, file: item.file })),
    determinism: capture.determinism,
    loop,
    cover,
    contactSheet: fs.existsSync(sheet) ? path.relative(root, sheet) : null,
    review: 'Open the contact sheet and every cut frame. Fix anything cluttered, overlapping, off-grid or hard to read before rendering.'
  };
  writeJson(path.join(root, 'reports', 'motion-probe.json'), report);
  return report;
}

function mixAudio(root, brief, videoFile, output, profile) {
  const audio = brief.audio || {};
  const duration = Number(brief.canvas.duration);
  const args = ['-hide_banner', '-loglevel', 'error', '-y', '-i', videoFile];
  const graph = [];
  const labels = [];
  const cues = [];
  let input = 1;
  if (audio.music && audio.music.path) {
    const music = projectPath(root, audio.music.path, 'audio.music.path', true);
    const inPoint = Number(audio.music.inPoint || 0);
    args.push('-i', music);
    const fadeOut = brief.loop ? 0 : Math.min(1.2, duration / 4);
    graph.push(`[${input}:a]atrim=start=${inPoint}:duration=${duration},asetpts=PTS-STARTPTS,aresample=48000,aformat=channel_layouts=stereo,volume=${Number(audio.music.gain || 1)}${fadeOut ? `,afade=t=out:st=${duration - fadeOut}:d=${fadeOut}` : ''}[m]`);
    labels.push('[m]');
    input += 1;
  }
  for (const [index, cue] of (audio.sfx || []).entries()) {
    const file = projectPath(root, cue.path, `audio.sfx[${index}].path`, true);
    const trim = Number(cue.trim || 0);
    const align = cue.alignPeak !== false;
    const peak = align ? peakOffset(file, { trim }) : { peakMs: 0 };
    let start = Number(cue.at) - peak.peakMs / 1000;
    let extraTrim = 0;
    if (start < 0) { extraTrim = -start; start = 0; }
    args.push('-i', file);
    const gain = cue.gain == null ? 0.5 : Number(cue.gain);
    graph.push(`[${input}:a]atrim=start=${trim + extraTrim},asetpts=PTS-STARTPTS,aresample=48000,aformat=channel_layouts=stereo,volume=${gain},adelay=${Math.round(start * 1000)}:all=1[s${index}]`);
    labels.push(`[s${index}]`);
    cues.push({ id: cue.id || `sfx${index + 1}`, path: cue.path, eventAt: Number(cue.at), peakMs: peak.peakMs, placedAt: round(start), gain });
    input += 1;
  }
  if (!labels.length) {
    fs.copyFileSync(videoFile, output);
    return { audio: false, cues };
  }
  const lufs = Number(audio.loudnessLUFS || -14);
  // Master in two passes: mix → measure integrated loudness → gain to target →
  // true-peak-safe limiter. Single-pass loudnorm undershoots on peaky material.
  const premix = output.replace(/\.mp4$/, '.premix.wav');
  graph.push(`${labels.join('')}amix=inputs=${labels.length}:duration=longest:normalize=0,apad,atrim=0:${duration}[a]`);
  runFfmpeg([...args, '-filter_complex', graph.join(';'), '-map', '[a]', '-c:a', 'pcm_s24le', '-ar', '48000', premix], root);
  const measured = measureLoudness(root, premix);
  let gainDb = measured.integratedLUFS == null || !Number.isFinite(measured.integratedLUFS) ? 0 : lufs - measured.integratedLUFS;
  const mastered = output.replace(/\.mp4$/, '.master.wav');
  let achieved = null;
  for (let pass = 0; pass < 5; pass += 1) {
    gainDb = Math.max(-30, Math.min(30, gainDb));
    runFfmpeg(['-hide_banner', '-loglevel', 'error', '-y', '-i', premix,
      '-af', `volume=${gainDb.toFixed(2)}dB,alimiter=limit=0.8:attack=3:release=60:level=false`,
      '-c:a', 'pcm_s24le', '-ar', '48000', mastered], root);
    achieved = measureLoudness(root, mastered).integratedLUFS;
    if (achieved == null || Math.abs(achieved - lufs) <= 0.7) break;
    gainDb += lufs - achieved;
  }
  runFfmpeg(['-hide_banner', '-loglevel', 'error', '-y', '-i', videoFile, '-i', mastered,
    '-map', '0:v:0', '-map', '1:a:0', '-c:v', 'copy', '-c:a', 'aac', '-b:a', profile === 'final' ? '256k' : '160k',
    '-t', String(duration), '-movflags', '+faststart', output], root);
  fs.rmSync(mastered, { force: true });
  fs.rmSync(premix, { force: true });
  return { audio: true, loudnessTargetLUFS: lufs, premixLUFS: measured.integratedLUFS, gainDb: round(gainDb, 2), cues };
}

function measureLoudness(root, file) {
  const result = spawnSync(ffmpegPath(), ['-hide_banner', '-nostats', '-i', file, '-af', 'ebur128=peak=true', '-f', 'null', '-'], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
  const text = String(result.stderr || '');
  const summary = text.slice(text.lastIndexOf('Summary:'));
  const integrated = /I:\s+(-?[\d.]+) LUFS/.exec(summary);
  const peak = /Peak:\s+(-?[\d.]+|-inf) dBFS/.exec(summary);
  return { integratedLUFS: integrated ? Number(integrated[1]) : null, truePeakDbfs: peak ? Number(peak[1]) : null };
}

function verifyMotion(root, output, brief, mix, profile) {
  const base = verifyVideo(output);
  const errors = [...(base.errors || [])];
  const warnings = [...(base.warnings || [])]
    .filter((item) => !(mix.audio === false && /No audio stream/.test(item)))
    .filter((item) => !(profile === 'draft' && /width is low/.test(item)));
  const duration = base.format && base.format.duration;
  const frame = 1 / brief.canvas.fps;
  if (duration != null && Math.abs(duration - brief.canvas.duration) > frame * 2 + 0.05) errors.push(`Duration ${duration}s differs from canvas.duration ${brief.canvas.duration}s.`);
  let loudness = null;
  if (mix.audio) {
    loudness = measureLoudness(root, output);
    const target = Number((brief.audio && brief.audio.loudnessLUFS) || -14);
    if (loudness.integratedLUFS != null && Math.abs(loudness.integratedLUFS - target) > 1.5) warnings.push(`Integrated loudness ${loudness.integratedLUFS} LUFS is off target ${target} LUFS.`);
    if (loudness.truePeakDbfs != null && loudness.truePeakDbfs > -1) warnings.push(`Peak ${loudness.truePeakDbfs} dBFS is above -1 dBFS.`);
  }
  return { ...base, ok: errors.length === 0, errors, warnings, loudness };
}

async function commandRender(root, flags) {
  const brief = readBrief(root);
  const profile = String(flags.profile || 'draft');
  if (!['draft', 'final'].includes(profile)) throw new UsageError('--profile must be draft or final.');
  const check = checkBrief(root, brief);
  if (!check.ok) return { ok: false, stage: 'check', errors: check.errors };
  const scene = projectPath(root, brief.build.scene, 'build.scene', true);
  if (profile === 'final') {
    const probeFile = path.join(root, 'reports', 'motion-probe.json');
    const probe = fs.existsSync(probeFile) ? JSON.parse(fs.readFileSync(probeFile, 'utf8')) : null;
    const blockers = [];
    if (!probe) blockers.push('Run qcut motion probe before the final render.');
    else {
      if (probe.cover && !probe.cover.notBlack) blockers.push('Frame 0 is black/blank. Make storyboard[0] the cover (references/cover-thumbnail-method.md), then re-probe.');
      else if (!probe.ok) blockers.push('The last probe failed (non-deterministic frames or loop seam). Fix and re-probe.');
      if (probe.sceneSha256 !== sha256File(scene)) blockers.push('Scene changed since the last probe. Re-run qcut motion probe.');
    }
    if (check.status === 'awaiting-storyboard-approval') blockers.push('approval.mode is ask and the storyboard is not approved. Show the storyboard on the beat grid, then set approval.storyboardApproved=true.');
    if (blockers.length) return { ok: false, stage: 'final-gate', errors: blockers };
  }
  const { width, height, fps, duration } = brief.canvas;
  const build = brief.build || {};
  const videoOnly = projectPath(root, `renders/motion.${profile}.video.mp4`, 'render output');
  const output = projectPath(root, `renders/motion.${profile}.mp4`, 'render output');
  for (const file of [videoOnly, output]) {
    if (fs.existsSync(file)) {
      if (!flags.force) throw new Error(`${path.relative(root, file)} exists. Re-run with --force to replace it.`);
      fs.unlinkSync(file);
    }
  }
  const started = Date.now();
  const capture = await captureBrowserScene({
    projectRoot: root,
    source: scene,
    output: videoOnly,
    width, height, fps, duration,
    transparent: false,
    allowLarge: true,
    motionBlur: profile === 'final' ? Number(build.motionBlurSubframes || 3) : 1,
    shutter: build.shutter,
    scale: profile === 'final' ? 1 : Number(flags.scale || 0.5)
  });
  const captureSeconds = (Date.now() - started) / 1000;
  const mix = mixAudio(root, brief, videoOnly, output, profile);
  const verification = verifyMotion(root, output, brief, mix, profile);
  const report = {
    ok: Boolean(verification && verification.ok !== false),
    profile,
    output: path.relative(root, output),
    videoOnly: path.relative(root, videoOnly),
    canvas: brief.canvas,
    capture: { frames: capture.frames, motionBlur: capture.motionBlur, scale: capture.scale, seconds: round(captureSeconds, 1) },
    audio: mix,
    verification,
    releaseReady: profile === 'final' && Boolean(verification && verification.ok !== false)
  };
  writeJson(path.join(root, 'reports', `motion-render-${profile}.json`), report);
  return report;
}

// ---- batch diversity: films made together must be different films ---------------------------------
function hexToRgb(hex) {
  const m = /^#?([0-9a-f]{6})$/i.exec(String(hex || '').trim());
  if (!m) return null;
  const n = parseInt(m[1], 16);
  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
}
function chroma([r, g, b]) { return Math.max(r, g, b) - Math.min(r, g, b); }
function paletteOverlap(a, b) {
  const pa = (a || []).map(hexToRgb).filter((c) => c && chroma(c) > 40);
  const pb = (b || []).map(hexToRgb).filter((c) => c && chroma(c) > 40);
  if (!pa.length || !pb.length) return 0;
  const near = (x, y) => Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2]) < 60;
  const hits = pa.filter((x) => pb.some((y) => near(x, y))).length;
  return hits / Math.min(pa.length, pb.length);
}
const norm = (v) => String(v || '').trim().toLowerCase().replace(/\s+/g, ' ');

function diversityReport(entries) {
  const errors = [];
  const warnings = [];
  const add = (list, code, message, extra = {}) => list.push({ code, message, ...extra });
  entries.forEach((e) => {
    const c = e.concept;
    if (!c) add(errors, 'concept-missing', `${e.name}: no brief.concept.`);
    else if (!norm(c.reference) || /^todo/.test(norm(c.reference))) add(errors, 'reference-missing', `${e.name}: concept.reference must name a real ad or film.`);
  });
  for (let i = 0; i < entries.length; i += 1) {
    for (let j = i + 1; j < entries.length; j += 1) {
      const a = entries[i], b = entries[j];
      if (!a.concept || !b.concept) continue;
      const pair = `${a.name} × ${b.name}`;
      if (norm(a.concept.archetype) === norm(b.concept.archetype)) add(errors, 'same-archetype', `${pair}: both use archetype "${a.concept.archetype}".`);
      if (norm(a.concept.musicStyle) === norm(b.concept.musicStyle)) add(errors, 'same-music', `${pair}: both use music style "${a.concept.musicStyle}".`);
      if (norm(a.concept.structure) === norm(b.concept.structure)) add(errors, 'same-structure', `${pair}: identical structure.`);
      if (norm(a.concept.reference) === norm(b.concept.reference)) add(errors, 'same-reference', `${pair}: both cite "${a.concept.reference}".`);
      if (norm(a.concept.typeStyle) === norm(b.concept.typeStyle)) add(warnings, 'same-type', `${pair}: same type style "${a.concept.typeStyle}".`);
      if (norm(a.concept.camera) && norm(a.concept.camera) === norm(b.concept.camera)) add(warnings, 'same-camera', `${pair}: identical camera language.`);
      const ta = Number(a.concept.tempo), tb = Number(b.concept.tempo);
      if (ta > 0 && tb > 0 && Math.abs(ta - tb) <= 8) add(warnings, 'close-tempo', `${pair}: tempos ${ta} and ${tb} BPM are within 8.`);
      const ov = paletteOverlap(a.concept.palette, b.concept.palette);
      if (ov >= 0.5) add(warnings, 'similar-palette', `${pair}: ${Math.round(ov * 100)}% of the saturated colours overlap.`);
      const da = Number(a.concept.duration), db = Number(b.concept.duration);
      if (da > 0 && db > 0 && Math.abs(da - db) < 1) add(warnings, 'same-duration', `${pair}: same duration (${da}s); vary the length.`);
    }
  }
  return { ok: errors.length === 0, films: entries.map((e) => ({ name: e.name, archetype: e.concept && e.concept.archetype, reference: e.concept && e.concept.reference, music: e.concept && e.concept.musicStyle, type: e.concept && e.concept.typeStyle, tempo: e.concept && e.concept.tempo, duration: e.concept && e.concept.duration })), errors, warnings };
}

function commandDiversity(roots, flags) {
  if (roots.length < 2) throw new UsageError('qcut motion diversity needs at least two project directories.');
  const entries = roots.map((root) => {
    const file = path.join(root, 'motion-brief.json');
    if (!fs.existsSync(file)) throw new Error(`motion-brief.json not found in ${root}`);
    const brief = JSON.parse(fs.readFileSync(file, 'utf8'));
    return { name: path.basename(root), concept: brief.concept };
  });
  const report = diversityReport(entries);
  if (flags.out) writeJson(path.resolve(String(flags.out)), { checkedAt: new Date().toISOString(), ...report });
  return report;
}

async function commandCover(root, flags) {
  const brief = readBrief(root);
  if (brief.loop) throw new UsageError('Loops have no cover shot; export a thumbnail with qcut cover export instead.');
  const scene = projectPath(root, brief.build.scene, 'build.scene', true);
  const configured = brief.cover && brief.cover.variants ? Object.keys(brief.cover.variants) : [];
  const variants = flags.variants ? String(flags.variants).split(',').map((v) => v.trim()).filter(Boolean) : (configured.length ? configured : ['a']);
  const scale = Number(flags.scale || 2);
  const { width, height } = brief.canvas;
  const outDir = projectPath(root, 'renders/cover', 'cover output');
  fs.mkdirSync(outDir, { recursive: true });
  const results = [];
  for (const variant of variants) {
    if (!/^[\w-]{1,24}$/.test(variant)) throw new UsageError(`Invalid variant id: ${variant}`);
    const stillDir = path.join(root, 'reports', 'motion-cover', variant);
    fs.rmSync(stillDir, { recursive: true, force: true });
    const capture = await captureStills({ projectRoot: root, source: scene, width, height, times: [0], outDir: stillDir, scale, determinism: false, query: `cover=${encodeURIComponent(variant)}` });
    const master = path.join(outDir, `cover-${variant}@${scale}x.png`);
    fs.copyFileSync(path.resolve(root, capture.stills[0].file), master);
    const thumbs = exportThumbnails(master, outDir, `cover-${variant}`);
    const check = checkCover(thumbs.jpg);
    results.push({
      variant,
      concept: brief.cover && brief.cover.variants ? brief.cover.variants[variant] || null : null,
      master: path.relative(root, master),
      jpg: path.relative(root, thumbs.jpg),
      previews: thumbs.previews.map((file) => path.relative(root, file)),
      frame0: check.frame0,
      bytes: fs.statSync(thumbs.jpg).size,
      errors: check.errors,
      warnings: check.warnings
    });
  }
  const report = {
    ok: results.every((item) => item.errors.length === 0),
    renderedAt: new Date().toISOString(),
    sceneSha256: sha256File(scene),
    frameZeroVariant: variants[0],
    variants: results,
    review: 'Compare the 168/360 previews side by side; the main variant is frame 0 of the film. Upload 2–3 variants to YouTube Test & Compare (judged on watch-time share).'
  };
  writeJson(path.join(root, 'reports', 'motion-cover.json'), report);
  return report;
}

function usage() {
  return `Usage:
  qcut motion styles [--json]
  qcut motion init <project> [--style ${Object.keys(STYLES).join('|')}] [--title T]
                   [--audio assets/song.mp3] [--bpm 120] [--width W --height H --fps F --duration S]
                   [--loop] [--mode ask|autopilot] [--force] [--json]
  qcut motion scene  <project> [--force]      regenerate the starter scene from the storyboard
  qcut motion check  <project> [--json]
  qcut motion probe  <project> [--times 0,1.5,3] [--max 32] [--json]
  qcut motion diversity <project> <project> [...] [--out report.json] [--json]   films made together must be different concepts
  qcut motion cover  <project> [--variants a,b,c] [--scale 2] [--json]   frame-0 cover → thumbnails
  qcut motion render <project> [--profile draft|final] [--force] [--json]
`;
}

async function cli(argv = process.argv.slice(2)) {
  const { positional, flags } = parseArgs(argv);
  const [command, project] = positional;
  if (command === 'styles') {
    const list = Object.entries(STYLES).map(([id, style]) => ({ id, title: style.title, canvas: style.canvas, bpm: style.bpm, loop: Boolean(style.loop) }));
    process.stdout.write(flags.json ? `${JSON.stringify(list, null, 2)}\n` : `${list.map((item) => `${item.id}\t${item.title}`).join('\n')}\n`);
    return 0;
  }
  if (command === 'diversity') {
    const report = commandDiversity(positional.slice(1).map((p) => path.resolve(p)), flags);
    process.stdout.write(flags.json ? `${JSON.stringify(report, null, 2)}\n` : `diversity: ${report.ok ? 'ok' : 'blocked'}\n${report.errors.map((e) => `  ✗ ${e.message}`).join('\n')}${report.warnings.length ? '\n' + report.warnings.map((e) => `  ! ${e.message}`).join('\n') : ''}\n`);
    return report.ok ? 0 : 1;
  }
  if (!['init', 'scene', 'check', 'probe', 'cover', 'render'].includes(command) || !project) throw new UsageError(usage());
  const root = path.resolve(project);
  if (command !== 'init' && !fs.existsSync(root)) throw new Error('Project directory not found.');
  let result;
  if (command === 'init') result = commandInit(root, flags);
  else if (command === 'scene') result = commandScene(root, flags);
  else if (command === 'check') result = commandCheck(root);
  else if (command === 'probe') result = await commandProbe(root, flags);
  else if (command === 'cover') result = await commandCover(root, flags);
  else result = await commandRender(root, flags);
  if (flags.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
  else process.stdout.write(`${command}: ${result.ok ? 'ok' : 'blocked'}${result.status ? ` (${result.status})` : ''}\n${(result.errors || []).map((item) => `  ✗ ${item.message || item}`).join('\n')}\n`);
  return result.ok ? 0 : 1;
}

module.exports = { STYLES, checkBrief, lintScene, storyboardSkeleton, coverSeconds, diversityReport };

if (require.main === module) {
  cli().then((code) => { process.exitCode = code; }).catch((error) => {
    process.stderr.write(`${error.message}\n`);
    process.exitCode = error instanceof UsageError ? 2 : 1;
  });
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall