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//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//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//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 ` element. Prefer **one pre-mixed master audio track** (VO + SFX mixed via ffmpeg adelay+amix) over many 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//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 — 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/.mp4

Optionally assert exact specs:

node scripts/verify-render.mjs .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)

• Preview screenshots: representative frames captured from the live preview, confirming layout/timing/motion.
• ffprobe: dimensions exactly 9:16 (1080×1920), expected duration (±tolerance), h264 / yuv420p, audio stream present. The gate script enforces this.
• Frame spot-checks: ffmpeg extract frames across the timeline into a contact sheet; confirm each required technique renders on-style and matches the preview.
• Face check: on every preview screenshot and contact-sheet frame containing a person, the whole face is visible and centered in its panel (not cropped by a seam, caption, edge, or camera move). Fail the gate and re-frame if not.
• Rights: no unlicensed/placeholder media in the render; anything that needs a final license check called out in the report.
• Design-change log: any deviation from the style spec or the editorial-look patterns (new layout, changed colors/type, modified motion) must be recorded in edit-report.md under "Design decisions", with the reason. Visual changes are fine; silent visual changes are not.

Credits & provenance

This skill researched the hyperframes docs, github.com/robonuggets/hyperframes-helper, and reference frames from creator-grade shorts, then went beyond them. See "standard-provenance" below for the breakdown. Summary:

• Adopted from hyperframes-helper / HyperFrames: HTML-source-of-truth model; data-* timing attributes + class="clip"; paused timelines on window.__timelines; GSAP power2/power3.out eases; white-glow caption styling; SVG underline emphasis; the lint gotcha list (overlap float-precision, deterministic-only, muted-video-plus-audio, etc.).
• Added here: a full eased camera-motion system with an explicit anti-jitter contract; 9:16 short-form grammar (engineered hooks, sub-0.2s non-metronomic cutting, split→full-frame transitions); a style-theming pipeline from FRAME.md → concrete design spec; rights-free SFX synthesis + single pre-mixed master-track discipline; and a render verification gate (ffprobe assertions + contact-sheet spot-checks).

---

Appendix — Reference Library (inlined)

The authoring source keeps these as separate files under references/; they are inlined here so the skill is a single self-contained SKILL.md.

Appendix: editorial-look

The editorial look — reference visual grammar

Distilled from stills of creator-grade shorts (Kallaway / Varun Mayya class) into ten named patterns. These are the house layouts: build every short from them, themed with your style pack's tokens (styles//FRAME.md). The recipes below show a mapping for the shipped vibe-life example; substitute your own tokens.

The unifying idea: frames are designed pages, not video with text on top. Type is editorial (a heavy grotesque playing against an italic serif), media sits in cards or panels on a textured ground, and supers are typeset objects (bars, pills, underlines) — never bare drop-shadowed text.

---

1. Editorial headline (mixed serif/sans)

One headline, two voices: heavy sans for the statement, italic serif for the twist word(s), plus a hand-drawn underline or highlight on the payoff.

Claude Just *Changed*        ← serif italic on the verb
SOCIAL MEDIA FOREVER         ← heavy grotesque, tight leading
━━━━━━━━━━━━                 ← accent underline (brand accent)

.headline { text-align: center; line-height: 0.95; color: var(--fg); }
.headline .sans  { font: 500 9cqw/0.96 "Space Grotesk"; letter-spacing: -0.32cqw; }
.headline .serif { font: italic 400 9cqw/0.96 "Instrument Serif"; }
.headline .underline {
  display: block; width: 46cqw; height: 0.9cqw; margin: 1.6cqw auto 0;
  background: var(--accent-strong); border-radius: 999px;
  transform-origin: left center;          /* animate scaleX 0→1, power3.out */
}

Rules: serif italic on one or two words max (the verb or the twist), never the whole line. Underline draws in with scaleX after the words land. Mixed-case serif against caps/title-case sans is the signature.

2. Paper stage (light textured ground)

Full-frame off-white "paper" with a faint grid — media and graphics sit on it as cards. Used for hooks, logo beats, UI-stack beats.

.paper {
  background:
    linear-gradient(var(--line-faint) 1px, transparent 1px),
    linear-gradient(90deg, var(--line-faint) 1px, trans

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nopefallacy](https://github.com/nopefallacy)
- **Source:** [nopefallacy/vertical-video-editing-skills](https://github.com/nopefallacy/vertical-video-editing-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.