footage-cutlist

footage-cutlist

Picking which moment of a customer's footage plays under which line is a judgement, not a formula. A position map ("beat 3 is 40% through the reel, so take the footage 40% through") was measured up to 5.7s off a person's picks on a reference build. So this capability does the free, mechanical parts and leaves the decision to the agent and the user:

All free. ffmpeg + Pillow + numpy only.

Run

python survey.py --video footage.mp4 --out work/survey            # whole clip, ~1 frame/s
python survey.py --video footage.mp4 --out work/s-12 --from 12 --to 18 --every 0.25 --frames
python preview.py --cutlist work/cutlist.json --out work/review.png
python cut.py --cutlist work/cutlist.json --out work/layer.mp4 [--draft]

survey.json lists cuts (scene changes), motion (change per second) and still (runs of 1.5s+ with nothing moving: a dead screen reads as a frozen video). Read the sheets; open a single frame-*.png (from --frames) when you need to read small UI text.

The cut list

{
  "size": [1080, 1920], "fps": 30, "seam": 768, "creator_side": "bottom", "bg": "auto",
  "sources": {"demo": "footage/demo.mp4"},
  "beats": [
    {"id": "b1", "start": 0.0, "end": 3.1, "state": "creator", "vo": "..."},
    {"id": "b2", "start": 3.1, "end": 7.4, "state": "split", "vo": "...",
     "source": "demo", "in": 12.0, "out": 16.3, "fit": "width", "why": "the brand kit fills in at 13.4s"}
  ]
}

• state: creator (creator full frame), split (footage in the product zone, creator in the other), product (footage full frame).
• in is where the window starts in the source; out defaults to in + slot (1.0x). A window may play between 0.5x and 2x; it is never looped or frozen to fill a slot.
• fit: width (whole frame, letterboxed; the default), cover (fill + crop around focus), crop (a source box [x0,y0,x1,y1] in fractions, then fit by width).
• bg: auto samples the footage's own corner colour so the letterbox and the footage read as one surface; blur; or #rrggbb.
• look: "screen": frame the footage as a screen filmed at close range (thin bezel, dark room, faint moire, grain, slow handheld drift). crop picks the source region, screen: {rot, keystone, fill, fit, drift} the geometry, mask boxes are blurred in the source (an email, a customer name). Inserts over a creator: keystone ~0.007, rot within ±1°. Walkthroughs: keystone ~0.024, rot -1.5..0, fill ~0.80. Never bigger angles and never alternate them between beats (read as a wonky camera).
• transition: {"dissolve_frames": 7} (top level): cross-dissolve every beat into the next. A hard cut between two screens reads as an edit; 6-7 frames reads as the camera moving.
• A source can be a still image (png/jpg/webp): it holds for its slot. Give it look: "screen" so the drift keeps it alive.
• why: one line on what the window shows. It is printed on the review sheet so the user can see the reasoning, and it makes the agent say what it saw.