nopefallacy/vertical-video-editing-skills/video-editing

video-editing

Use this skill when you have an approved script, provided voice/talking-head media, and gathered assets, and need to turn them into a finished vertical (9:16) short. You are the main editor, not a clip-stitcher. The bar is creator-grade shorts (Kallaway / Varun Mayya density): every beat earns attention. Generic AI-tool output — uniform 1s cuts, default fonts, linear/jittery transforms, a stock-template look — is a failure, not a deliverable.

Default ratio is 9:16 (1080×1920). The style packs also define 16:9 and 1:1 behavior, so the same look can be retargeted — but this skill's pacing and hook grammar are written for vertical short-form first.

The non-negotiable workflow (never skip, never reorder)

Authoring index.html by hand from nothing breaks live-reload and project structure. Always:

1. `npx hyperframes init edit` inside your project's edit/ folder — creates the scaffold (index.html, meta.json, hyperframes.json, CLAUDE.md, package.json).
2. `cd edit` and modify the generated project files to build the actual edit. Add fonts/, assets/sfx/, sub-compositions under compositions/.
3. `npx hyperframes preview` (long-running — run in background) — verify in the browser with live reload. Use a browser tool to inspect and screenshot. Confirm pacing, layout, text timing, and animation smoothness before rendering.
4. `npx hyperframes lint` / `npm run check` — fix every error; review warnings.
5. `npx hyperframes render` — final MP4.
6. Verify: ffprobe (9:16 dimensions, duration, codec) + ffmpeg frame spot-checks against a contact sheet. Run the bundled gate script (below).

Use the hyperframes docs (npx hyperframes docs) for API/feature reference and the references in this skill for the editing standard. If HyperFrames tooling is missing or broken, stop and tell the user rather than hand-authoring a generic edit.

Requirements

• HyperFrames — the rendering engine, run via npx hyperframes. This skill is the editing standard on top of HyperFrames; it does not replace it.
• Node.js (for npx and the verification script).
• ffmpeg / ffprobe on PATH — for SFX synthesis, audio mixing, and render verification.
• A style pack under styles/<style>/FRAME.md (this skill ships vibe-life as a worked example and _template as a starting point — see styles/README.md).

Inputs

Work from one project folder. A recommended layout (adapt to yours):

your-project/
├── script.md            # approved script with beats/timestamps, supers, energy cues — THE SPINE
├── voiceover/           # provided voice / talking-head media (the A-roll)
├── avatar/              # optional talking-head media
├── assets/
│   ├── manifest.json    # gathered B-roll + per-beat asset map + rights notes
│   └── ...              # the gathered media
└── edit/                # YOUR output (created by `npx hyperframes init edit`)

Read (do not edit) the script, the voice/avatar media, and the asset manifest. Pick the style pack the video should use (styles/<style>/FRAME.md).

Outputs

Write everything under your project's edit/ folder:

• The HyperFrames project (index.html + compositions/ + fonts/ + assets/sfx/ + assets/master_audio.*).
• The final rendered MP4 (9:16), verified.
• edit-report.md — a handoff note: per-beat edit decisions, assets used (with manifest references), SFX/music used, preview/render verification notes, and anything you flagged for final review. Template in references/edit-report-template.md (appended below).

Editing grammar (what "professional" means here)

Each item below is a quality gate, not a suggestion.

The house visual language is the editorial look — see "editorial-look" below. Frames are designed pages, not video with text on top: mixed serif-italic/heavy-sans editorial headlines, paper-stage and dark-grid-interstitial grounds, the stacked split (B-roll top / talking head bottom) as the default A-roll/B-roll layout, highlight-bar supers with keyword color emphasis, seam captions and name pills, headline cards, and UI-card stacks. Build every short from those ten patterns, themed per style pack.

• Engineered hook (first 1–3s): text supers on top, a pattern interrupt, then a move into frame (e.g. a split panel that grows to full 9:16). Never open on a static talking head.
• A-roll / B-roll structure: A-roll (talking head / VO) is the spine; B-roll (clips, screenshots, motion graphics) covers and punctuates it. Cut B-roll over the A-roll's audio, not in silence.
• Cut granularity: cuts as fast as 0.2s when the script's energy demands; never metronomic 1s cuts. Pacing follows the script.
• Split-screen layouts: side-by-side and stacked compositions, with deliberate transitions in and out of full-frame. The stacked split with a seam caption is the workhorse — full-frame B-roll cover is the exception.
• Face-safe framing: whenever a person is inside a panel or crop, bias the crop with object-position so the face sits centered in the panel's visible area, eyes in the upper third — the default 50% 50% is almost always wrong for talking-head sources and cuts heads off. Camera moves on a person-panel must keep the face in frame for the entire move. An off-center or cropped face is a gate failure. See "editorial-look" §4 "Face-safe framing".
• Eased camera motion: zoom-in/out and push left/right pans, always eased, never linear, never jittery. See "camera-moves" for the anti-jitter contract.
• Kinetic text / captions: animated entrances, keyword emphasis (one accent word), caption supers timed to the voice.
• Themed motion graphics: number cards, spec/JSON cards, bounding-box callouts, poster splits, chart builds — designed on the style theme, not generic.
• Logo / wordmark animation: animated brand/product marks where the script names them.
• SFX: whooshes, clicks, risers, impacts layered on cuts and graphic hits — subtle, mixed under the voice. See "sfx-and-audio".
• Cohesive aesthetics: one color theme, consistent typography, eased curves, no default-look elements, no popping. All from the style pack FRAME.md.

Style theming (required, before designing anything)

Derive the visual identity from the style pack first — colors, type, motion personality, and graphic language all come from styles/<style>/FRAME.md. Different style → different look. See "style-theming" below for turning FRAME.md into a concrete frame.md design spec (palette tokens, @font-face for local fonts, motion personality → easing/cut choices). The shipped vibe-life example uses a cream/ink/peach/butter palette; Space Grotesk + Instrument Serif italic + JetBrains Mono; paper-cut motion (hard cuts masked by SFX, not crossfades); one italic-serif accent word per frame in a pill; flat hard ink shadows. Your own style fills the same roles with its own tokens.

HyperFrames hard rules (break these and the render breaks)

1. Every timed element needs data-start, data-duration, data-track-index and class="clip" (the framework controls visibility via clip).
2. Never GSAP the `.clip` element itself — the framework owns its visibility/transform. Animate a child wrapper (e.g. .cam, .inner).
3. Timelines must be gsap.timeline({ paused: true }) and registered on window.__timelines["main"] (id matches data-composition-id).
4. Deterministic only — no Math.random(), no Date.now(), no network fetches, no repeat: -1. Renders are frame-sampled and must be reproducible.
5. 9:16 = 1080×1920. Set #root { container-type: size; } so cqw/cqh resolve against the frame (1cqw = 10.8px). Size type/graphics in cqw/cqh, not vw/vh.
6. Adjacent same-track clips must not touch — float precision makes 3.2 + 0.35 = 3.5500000000000003, which overlaps a clip starting at 3.55 and trips overlapping_clips_same_track. Leave a gap or use durations like 0.34. (Adopted from hyperframes-helper's lint gotchas.)
7. Audio: videos are muted with a separate <audio> element. Prefer one pre-mixed master audio track (VO + SFX mixed via ffmpeg adelay+amix) over many <audio> elements — multiple tracks cause echo/desync. Put it on a high, dedicated data-track-index.
8. Density: timeline_track_too_dense (many timed elements on one track) is advisory for a short pilot but real at scale — split scenes into sub-compositions (data-composition-src="compositions/file.html") for production-length edits.

Workflow

1. Read the script as the spine. Build a beat map: each beat/timestamp → A-roll (VO/avatar segment) + B-roll/MG need + on-screen super + intended cut/camera/transition + energy. The script's energy dictates pacing; do not impose a uniform rhythm.
2. Theme from the style pack. Read styles/<style>/FRAME.md. Produce the concrete design spec: palette tokens, local @font-face declarations, motion personality, graphic language. (See "style-theming".)
3. Reconcile asset coverage. Cross-reference your asset manifest: which beats are covered by gathered media, which are build-in-editor (yours to build as motion graphics), which are alternate swaps. Never put placeholder/unlicensed media in a final render — flag gaps in the report.
4. `npx hyperframes init edit`. Scaffold first. Then add fonts/ (local woff2 subsets), assets/sfx/, compositions/.
5. Build the edit beat-by-beat in index.html (and sub-compositions for length). Apply the editing grammar: engineered hook, A-roll/B-roll cover, non-metronomic cuts, split-screens, eased camera moves, kinetic text, themed MGs, logo animation. Animate child wrappers, never the .clip.
6. Author SFX + master audio. Synthesize rights-free SFX with ffmpeg (anoisesrc/aevalsrc/sine) or use cleared assets; mix VO + SFX into one master track. (See "sfx-and-audio".)
7. Preview and inspect. npx hyperframes preview in background; open in the browser; screenshot key beats; confirm pacing, layout, text timing, and motion smoothness. Fix before rendering.
8. Lint. npm run check / npx hyperframes lint --verbose. Fix all errors; review warnings (note known false positives — e.g. WCAG-contrast warnings sampled at timestamps where a high-contrast card is hidden).
9. Render. npx hyperframes render → MP4.
10. Verify with the gate script. Run node scripts/verify-render.mjs <path-to-mp4> — asserts 9:16, expected duration, h264/yuv420p, audio present. Then ffmpeg frame spot-checks into a contact sheet and eyeball against the preview.
11. Write `edit-report.md` and set disposition (done / in_review / blocked). Attach the MP4 + contact sheet.

Run the verification gate (the script ships in scripts/verify-render.mjs next to this file):

node scripts/verify-render.mjs path/to/edit/<file>.mp4

Optionally assert exact specs:

node scripts/verify-render.mjs <file>.mp4 --duration 12 --tolerance 0.5

Missing assets

If a beat needs an asset your assets/ doesn't have:

1. Check the manifest for alternate or build-in-editor rows first — custom motion-graphic beats are yours to build, not a blocker.
2. If it is genuinely missing and quick to fetch lawfully and directly, fetch it yourself and record provenance in edit-report.md.
3. Otherwise list the exact beat/timestamp, the asset need, and the intended edit action in the report, ask the user to supply it, and continue on beats you can finish. Never render a placeholder you can't license.

Verification (required before handoff)