effectcraft-editor

effectcraft-editor

An agent skill that makes motion-design edits in EffectCraft — and checks them with numbers, not vibes.

Cut real footage, recreate a reel shot for shot, edit to the beat, drop in titles and lower thirds, composite characters into photos, render photoreal 3D sets, and deliver in any format.

Quickstart · What it does · How it works · Toolbox · Compare · Docs

Six templates rendered headless by the test suite. The second panel is the lower third exported as an .ectemplate and re-rendered with new text — no script.

💬 Try saying

"Recreate this reel in EffectCraft, down to the camera moves."

"Cut these 12 clips into a 30-second montage on the beat, match their colours, and make a vertical version."

"Make a 15-second vertical edit in the style of this video, cut to this song."

"Add a lower third for each speaker and export ProRes with alpha for my editor."

"This shot looks like a PNG pasted on a photo — fix the compositing."

The skill tells your agent how to plan the edit, which EffectCraft quirks to avoid, which tool measures what, and when to stop tuning and rebuild a shot instead.

⚡ Quickstart

# 1. get the skill (Claude Code loads skills from ~/.claude/skills)
git clone https://github.com/hamgarian/effectcraft-editor ~/.claude/skills/effectcraft-editor
cd ~/.claude/skills/effectcraft-editor

# 2. Python tools
pip install opencv-python numpy pillow pytest certifi

# 3. find EffectCraft (or save its path once: python scripts/ec_cli.py --set /path/to/effectcraft-cli)
python scripts/ec_cli.py

# 4. check the machine (ffmpeg, Blender, voices) — prints the fix for anything missing
python scripts/doctor.py

# 5. prove it works here
python -m pytest tests -q

You need Python 3.10+, ffmpeg/ffprobe on PATH and EffectCraft (found automatically in the usual folders; your agent asks you for the path if not). Blender is optional (photoreal sets). Per-OS steps and MCP setup: references/setup.md.

✨ What it does

✂️ Edit real footage Probe and conform clips (variable frame rate and black-rendering codecs flagged), find shots, cut the pauses out of a talking head, build beat-synced montages, then assemble with trims, slips, speed ramps, freezes, reverses, J/L cuts, punch-ins, picture-in-picture and split screens. Colour-match clips to each other, reframe for vertical by following the subject, duck the music under speech. Every time helper is checked frame-accurately against rendered pixels.

🎯 Match a reference Study it frame by frame, then measure your render against it: cut timing, camera zoom/roll/pan per shot, brightness, beats, exposed edges, one-frame glitches, per-frame MAE/SSIM, frames that lead or lag. Claims are capped by fidelity levels — no "pixel perfect" without proof.

🎬 Direct an original edit One moving idea, a beat table where every beat changes state, a slideshow check. Like a video's style? stylemap.py turns it into a shot-by-shot plan — rhythm, camera, palette — for new content.

🎵 Cut to the music Tempo, beats and hits from any track; original sound effects (whoosh, impact, riser, click…); mix, mux, and a check that cuts land on beats and the audio is in sync.

🧩 Templates with controls Lower third, title card, logo reveal, kinetic type, 3D text orbit, social reframe — each exportable as an .ectemplate that renders new text from a JSON file.

🧪 Compositing that holds up Cut-outs graded into the plate with light wrap, backlit shading and real shadows; motion tracking, masks and expressions as one-line helpers.

🧊 Photoreal 3D sets Headless Blender (Cycles, HDRI, sun, off-screen shadow casters, smudged glass, screens that take shadow), rendered and placed back in the edit — for when "make it a real 3D scene" is the note.

📦 Deliver anywhere MP4, ProRes 4444 + alpha, WebM + alpha, GIF, RGBA PNG, Lottie, and editable timelines for Premiere, Resolve and Final Cut — each file verified after export. Vertical/square formats with safe areas.

🗣️ Captions & narration Timed captions (SRT, VTT, burned-in) from a script, the beat, or Whisper; offline narration with built-in voices; stock stills/video from Wikimedia Commons with licences attached.

🔁 How it works

flowchart LR
    A[Reference or brief] --> B[Study<br/>frame by frame, beats]
    B --> C[Plan<br/>shots, assets, audio, format]
    C --> D[Build<br/>one JSX script]
    D --> E[Render<br/>headless, resumable]
    E --> F[Measure<br/>cuts, camera, beats, frames]
    F -->|numbers off| G[Fix the earliest<br/>failing frame]
    G --> D
    F -->|gates green| H[Deliver<br/>verified exports]

Every edit is a script you can rerun, so a fix is a code change, not a pile of manual tweaks. When tuning stops moving the numbers for two rounds, the skill says to rebuild the shot's structure instead.

📊 Proof

From a real reel recreation (logs from the project, not rerun for this repo):

On a second reel, framemetrics.py picked out the weakest stretch on its own (f174–179, a macro push that stops short) — the same shot a separate AI review flagged — and audio.py read the music at 139.7 BPM with 26 of 47 cuts on a beat. Test runs: tests/RESULTS.md (62 passing on EffectCraft 0.16.0; 0.14.0 and 0.16.0 render bit-identical).

🧰 Toolbox

🆚 How it compares

Ideas from these projects were rewritten, not copied — see CHANGELOG.md. full-aigc's set also has a skill named effectcraft-editor; install one of them under another folder name.

📚 Docs

⚠️ Limits

• Tested on Windows x64 (EffectCraft 0.16.0 and 0.14.0, Blender 5.0). macOS/Linux steps follow EffectCraft's docs but weren't run.
• EffectCraft can't load After Effects plug-ins (.aex); AE .jsx scripts mostly run.
• With original art, MAE/SSIM aren't pass marks — use them for cuts, lead/lag and worst frames.
• Beat detection is a classic spectral-flux tracker: great for pop/electronic, weaker on rubato or ambient music.
• Safe areas are common margins, not platform specs. No CapCut draft export (use FCP XML / OTIO).
• footage.py reframe uses OpenCV's face detector when the installed build has it, else it follows motion.

📄 License

MIT. Originated in a series of reel recreations with original art; no third-party characters, logos, lyrics or music are included.