Analyze a reference video (clean room)

analyze measures only a video's structure. It keeps no words, frames or audio from the reference, and neither do you. Never transcribe, quote, describe shot by shot or reuse a reference video's script, music, footage or visual identity. Use it only for pacing and layout.

1. Get the path of the video file. It must be a local file. For a link, ask the user to download a copy they are allowed to use.
2. Call analyze {path, project_dir}, where project_dir is the user's project folder (absolute path). This writes qa/analysis.json and qa/analysis.md there. Leave out project_dir for a quick look.
3. Report it in plain words:
   • duration and aspect ratio
   • shot count, average shot length, cuts per 10 s and pacing (fast < 2 s per shot, slow > 5 s)
   • length of the hook shot
   • speech share: voice-band sound, so music can inflate it
   • speech pacing (speech_pacing): pauses inside speech (voice-band silences of 100 ms or more, lead-in and tail excluded), their share of the speech span, and the median and p95 pause. For a video the user edited themselves, offer tighten pacing_from with this analysis so their footage is cut to the same pauses.
   • loudness in LUFS
   • caption band, as a percentage of the frame height, or "none found"
   • motion timing (motion_timing): how long elements take to settle after a change starts (median and p75 entrance, ms), the easing class (ease_out, ease_in_out, spring, linear, snap) and its share, the stagger between entrances in a burst, and the still holds
4. Turn it into guidance for the user's own video, for example:
   • Cut every ~N s to match the pacing: set scene duration_sec near avg_shot_sec.
   • Make the first scene about hook_shot_sec long.
   • Keep captions in a similar band, but let the platform lint decide the exact position (/video-studio:lint).
   • For fast pacing, use short phrases and more scenes.
   • To move like the reference, offer analyze {path, project_dir, write_style: "<id>"}: it writes <project>/styles/<id>.yaml, a style pack with the measured easing, entrance, exit and stagger times and a cut or crossfade transition (from the cut rate). Set the spec's style to that id. Project styles resolve before the bundled ones; editing the file re-renders. It refuses an existing file or a bundled style id (minimal, editorial, ...) unless the user agrees to overwrite: true. The pack has no palette or fonts: those stay the user's.
5. Offer the next step: the creative brief or plan, written from the user's own sources.

Limits:

• Scene detection misses soft cuts (fades and dissolves) and slow motion graphics, so a count of 1–2 shots on an animated reel is normal.
• The caption band is the densest text-like band in the lower two-thirds of the frame. It can be a headline instead of captions.
• Motion timing reads frame-to-frame difference energy of the whole frame. Crossfades read as linear changes and hard cuts as snap; camera moves and live footage over 2 s are left out (the notes say how many). Two elements moving at once count as one change. Entrance durations, easing and holds are null with fewer than 2 changes; stagger is null without two changes under 0.8 s apart. The slow ends of an ease-in-out read up to a frame short.