Heditor

heditor — creative video editing (Reels and long form)

heditor turns a recording of someone speaking into a short vertical video that holds attention second by second: a strong opening, a visual world built for what is being said, captions synced word by word, sound effects tied to every action, music with an emotional arc and a call to action. Compositions are HTML + GSAP rendered to MP4 by HyperFrames. Everything runs locally.

The standard is high: every video gets an edit designed for it. A style is a proven visual language, never a template to stamp. If two videos in the same batch look like the same mould, the work is not done.

0. Setup (once per machine)

bashCopy code
bash <skill_dir>/scripts/setup.sh          # installs ffmpeg/node/python deps if missing, venv, Chrome, fonts, music, SFX, models
. ~/.heditor/env.sh && heditor doctor       # must end with "heditor is ready."

• Re-running setup is safe. --no-audio skips the Mixkit library; --whisper small,medium pre-downloads ASR models.
• Edit ~/.heditor/brand.json (name, @handle, colours, logo path, Follow/Following words, language). Ask the user for these the first time; never invent a handle.
• If a tool cannot be installed automatically (no sudo/package manager), tell the user the exact command to run and stop.
• All commands below assume . ~/.heditor/env.sh was sourced. The CLI is heditor (also at <skill_dir>/scripts/heditor).

1. Choose the mode

Named styles (heditor styles): see references/styles/INDEX.md for when each fits.

Long-form mode (classes, lives, YouTube; any format)

For minutes to hours of video in 16:9 (also 16:9 4K, 1:1, 4:5, 9:16), follow references/long-form.md: heditor new --long <work> <video> --format 16:9 --style <slug|creative> --kind aula|live|youtube → heditor long transcribe (chunked, resumable ASR) → long edl (proposed cuts of dead pauses, false starts, repetitions and fillers, reviewed before applying) → long apply → long chapters → long layouts (screen + camera layouts: pip, screen with zoom, speaker, side) → long produce (style pack, set pieces, captions, lower thirds, intro/CTA, mix) → long preview → heditor test → long render (segmented, resumable) → long finalize (one continuous master audio, SRT/VTT, YouTube chapters, QA report). Every named style is available as a style pack (heditor long styles); creative mode lives in set pieces at key moments. Format profiles: heditor formats.

Layered effects (any mode)

Text and objects behind the speaker, captions painted on a wall, 3D objects passing between the speaker and the room, depth fog, contour scans, point clouds and objects that follow the hands come from depthkit: heditor matte|depth|look|hands|plane <work> (models download on first use). Read references/depth-and-3d.md before using them in any style or in creative mode; layouts, illustrations, hooks and CTAs borrowed from creator Reels are in references/technique-catalogue.md.

Motion tools (any mode)

• GSAP plugins offline: SplitText, DrawSVG, MorphSVG, MotionPath, CustomEase/Bounce/Wiggle, Text, Physics2D/Props and EasePack ship with setup; load them with rk.page(..., plugins=("SplitText", "DrawSVG")). Read references/gsap-craft.md first: some GSAP features call Math.random (ScrambleText, stagger from: "random", gsap.utils.random) and break the render; the kit has seeded replacements (rnd(), scramble()).
• SVG preparation: heditor svg <in.svg> [out.svg] [static|draw|morph] cleans exported SVGs with SVGO for the animation they will get and proves, pixel by pixel in the render Chrome, that they still look the same.
• Real physics: heditor physics / physkit bakes a Rapier rigid-body simulation (falling piles, impacts, blasts) into per-frame transforms that a three.js layer with bloom and depth of field reads at any time. Recipe, framing and look values in references/physics-3d.md; working pilot in templates/physics/pilot_build.py.
• Styles built on these tools: gravidade (physics: blocks land on their words, physkit.land_on) and circuito (DrawSVG, MorphSVG, MotionPath, SplitText on a circuit board). Both ship a reference build: heditor new <work> <video> --style gravidade|circuito, write <work>/beats.json from the speech (format in the style file and at the top of the build), then heditor produce. In creative mode, borrow their engines (board(), physics()) for a single set piece.

Stock video / B-roll (any mode)

heditor stock search "<english words>" [--orientation portrait] lists free Mixkit clips (no account, no API key) and heditor stock get <work> '#N' downloads one into <work>/composition/assets/stock/, after confirming the Mixkit Stock Video Free License on the clip page, and records its provenance in <work>/stock.json (paste the printed line into DESIGN.md). Use B-roll only where it illustrates a word of the speech, muted, 1.5–3 s per idea, without recognisable faces next to claims in ads, logos or brands; one clip per get, never bulk downloads (Mixkit's terms forbid scraping the library). Read references/stock-media.md.

AI avatar source (optional, HeyGen)

When there is no recording, only a script, the source can be the user's own HeyGen digital twin. Read references/heygen-avatar.md first. In short:

• heditor heygen status (exit 0 connected, 3 not connected). Not connected: the user runs heditor heygen connect in their own terminal (HeyGen account by OAuth with subscription credits, or API key with the API wallet; on servers the assistant prints a link and asks for the return address). Never run it for them and never ask for a key in chat.
• heditor heygen avatars|voices → heditor avatar <work> --look ID --script roteiro.txt --dry-run shows the cost estimate (credits or USD). Show it to the user; only after approval run it again with --yes. The file lands in <work>/source/ with provenance in <work>/avatar.json (synthetic: true), then the normal workflow from heditor new <work> <file>.
• The person's own cloned voice, always: set it once in ~/.heditor/brand.json ("heygen": {"voice_id": "..."}); heditor avatar refuses a look default that is not one of the account's cloned voices (HeyGen can return a stock voice for photo looks). Generate with script + that voice_id (the engine saved on the voice), never with uploaded audio synthesized elsewhere; per-sentence gestures: § One motion prompt per sentence in the reference.
• Prepare the speech before spending: the approved roteiro.txt (caption spelling) and a spoken roteiro-fala.txt with numbers as said, abbreviations expanded, a few <break time="0.4s"/> pauses and connected sentences; recurring foreign terms, acronyms and names go into a HeyGen pronunciation glossary (heditor heygen glossaries, --glossary ID), respelled the way the person really says them. After generating, compare the transcript with the approved script word by word and regenerate any mispronounced line (references/heygen-avatar.md § Writing the script for the voice).
• Editing a studio avatar video (one scene per sentence): pass the scene seams to the prepare (prepare_cut(..., seams=[...])) so every pause cut lands on a pose reset instead of a few frames from it, check each splice of joined renders for clicks and each scene start for a head dip, and never blank the speaker to hide a jump (references/heygen-avatar.md § Editing an avatar video).
• The user approves every script; no claims, numbers or promises they did not approve; disclose AI use where a platform or law requires it.

2. Workflow (all modes)

Follow references/workflow.md step by step. Summary:

1. Probe the source. heditor probe <video> 5 60 300 and look at the frames: where is the speaker (full frame, webcam tile in a meeting, screen share)? Note resolution, the speaker crop, what else is on screen.
2. Transcribe and choose the cut. heditor transcribe <video> 0 <duration> qa/asr-full.json (or a window). Pick a self-contained argument of 30–70 s: hook → thesis → explanation → conclusion. Long-form stories (e.g. a narrated documentary of ~90 s, style documentario-narrado) are allowed when requested: declare max_duration in the plan (≤ 180 s) so heditor test accepts them, and keep a retention device every few seconds. The hook must exist in the speech. Never invent, reorder words inside a sentence, speed up or splice half-sentences into a new claim. Remove repetitions, false starts and tangents only at clean word boundaries. Scripted or teleprompter takes go through heditor triage <video...> first: chunks between silences transcribed alone and labelled keep / retake / false_start / editor / noise, so reading pauses, repeated sentences and asides to the editor never reach the cut. An aside is a note from the speaker to you (cut, redo, marker, note): follow it and report what you did (references/raw-takes.md).
3. Scaffold and prepare. heditor new <work> <video>, fill BLOCKS/CROP in <work>/prepare.py, heditor prepare <work>, heditor gaps <work> (no pause > 0.45 s), then heditor words <work> and fix spelling/brand names in words-reviewed.json (timings untouched; profanity can be masked on screen only).
4. Design first. Fill <work>/DESIGN.md: video analysis, mode/style, frame map, palette, captions, beat sheet with timestamps, music, CTA, risks. In creative mode, research before designing.
5. Build. Rewrite <work>/build.py (the template is only a runnable baseline) to implement DESIGN.md. Use the kit (references/kit-api.md) or write your own HTML when the format needs it.
6. Produce. Pick the mix profile (voice or presence), profile the track with heditor music <music:ID|file> and place its turns on the speech turns; heditor produce <work> music:<id> <drop_s> → composition + mix; read the balance it prints (targets, music_gaps).
7. QA before render. heditor lint <work> (0 errors) → heditor preview <work> <18–24 times> → inspect the contact sheet with vision and fix every defect → heditor test <work>. Gates in references/quality-gates.md.
8. Render and finalize. heditor render <work> → heditor finalize <work> <name>.mp4 → review qa/final-contact-sheet.jpg and qa/final-verification.json → heditor asr-check <work>.
9. Deliver the MP4 path with a short summary (format, music, what was verified, what nobody has checked: nobody has listened to it — say so). Never publish to social networks unless the user explicitly asks.
10. Learn. If you created a new style that the user liked, add it as a named style (references/adding-styles.md).

3. Non-negotiables

• No dead air. Inspect pauses inside blocks and across every junction, using the assembled clean voice, not the music mix. Run heditor gaps after prepare and check the surrounding words. The default 0.45 s threshold flags candidates for revision; it does not authorize clipping consonants, removing every breath or flattening deliberate rhetorical pauses. Preserve speech at 1× and shorten unwanted dead air with small safety margins. Document any intentional longer pause and verify the exception explicitly before rendering. For a pause-only revision of an approved edit, preserve its visual language and previous version, remap captions, media and SFX to the new timeline, then verify the exported MP4.
• Voice first, music present. Mix profile by delivery (plan["mix"]): voice (default; organic Reels, class excerpts) music ≈ 21.5 dB under the voice (median), background ≥ 12 dB under at p95; presence (paid ads, creative mode, trailer) music ≈ 15 dB under, background p95 ≥ 7 dB under, filtered sections with make-up gain and heditor asr-check required. In both the bed may not vanish inside the speech (test_music_presence). Impacts in the gaps, ducking held across the whole phrase. -14 LUFS, true peak ≤ -1.5 dBTP after AAC.
• Readable captions. Every spoken word, synced; active word with high contrast (black on light yellow, white on saturated dark — never dark-on-mid or dark outline on dark text). Check enlarged crops.
• Safe zones. (9:16; every format profile has its own safe area, see long-form.md.) Nothing important above y = 270 (top 14%; titles with accents start ≥ 300), keep the bottom ~350 px and the right edge (~120 px, y 1000–1700) free of critical info, never cover the face.
• Truth. Numbers, names and claims exactly as spoken; no invented stats, testimonials, promises or private data; no third-party logos or copyrighted assets (homage through type, colour, motion, sound).
• Licences. Fonts OFL (google/fonts), icons Lucide, music/SFX from the catalog (Mixkit Free License), stock video through heditor stock (Mixkit Stock Video Free License, stock.json) or user-provided licensed files. Record provenance in DESIGN.md.
• Different every time. In a batch, give each video its own format (layout, camera treatment, captions, palette, transitions, music, CTA). Ask vision to compare contact sheets: "do these look like the same template?" If yes, change more.
• Verify before claiming. A video is done only after lint, previews, tests, render, finalize gates and contact-sheet review pass. Report what failed honestly.
• The fourth wall stays closed. Nothing the speaker says to the editor or the crew ("cut that", "again", "corta aí, editor", "vamos editar essa parte") appears in the cut, in picture, sound or captions. Each aside is a note to you: follow it (discard, use the retake, apply the edit) and report what you did; run heditor triage on raw scripted takes before choosing anything.
• Paid-ad hooks. Frame 0 shows something concrete and readable plus a title of up to 6 words; the first spoken word is the object, the pain or the question; keep voice ≥ 90 % and ≥ 38 words in the first 15 s (first_15s in qa/final-verification.json) and put dramatic pauses, blacks and slow cards after that. A hook test changes only the opening: the body keeps the frames and audio of the running version (encoded once more, never re-edited) (references/hook-variants.md).

4. References

• references/workflow.md — the full procedure with commands, cut selection and EDL rules.
• references/raw-takes.md — raw takes: asides to the editor (the fourth wall) and their intents, choosing takes, stutters and self-corrections, recording failures (clipping, knocks, duplicated frames, the set moving, mirrored or HDR sources) and what goes in the delivery.
• references/hook-variants.md — new openings for a video that already performs: body identical, routes A (splice onto the delivered file with heditor splice), B (project copy) and C (rebuild and reproduce), continuous music, loudness and seal at the splice, what to report.
• references/pre-production.md — before recording: measure the scripts, inventory the set, reuse existing screen recordings, fact-check cited studies, recording plan (setups, gestures on words, screens, inserts), teleprompter generated from the source and a per-video style map for a batch.
• references/long-form.md — long-form mode: format profiles, layouts, EDL proposal, chapters, style packs for all styles, creative set pieces and cadence, segmented render, QA.
• references/creative-mode.md — creative mode, reference-directed creative mode, research method, idea bank.
• references/kit-api.md — reelkit functions, page skeleton, GSAP helpers, plan/sound/music formats.
• references/depth-and-3d.md — depthkit: speaker matte, depth map, scans, planes, tracking, three.js, layered recipes and QA.
• references/gsap-craft.md — GSAP plugins available offline, seek-safety rules (determinism hazards inside GSAP), SplitText/DrawSVG/MorphSVG in a render, SVG preparation with heditor svg.
• references/physics-3d.md — physkit: baked Rapier physics, scene format, three.js page with bloom/depth of field, look values and framing that passed QA.
• references/technique-catalogue.md — creator layouts (A/B page, morphs, insets, bands), illustrations, camera moves, caption systems, hooks and CTAs.
• references/heygen-avatar.md — optional AI avatar source from the user's HeyGen account: heditor heygen connect (OAuth with subscription credits, --remote for servers, or API key), status, looks and voices, heditor avatar (estimate, approval, idempotent request, download, avatar.json), writing the script for the voice (pronunciation glossary, spoken script, pauses, natural flow, word-by-word check), editing synthetic footage, consent and disclosure.
• references/stock-media.md — free Mixkit B-roll: search in English, orientation, quality, licence check, stock.json provenance, using clips in the page, what to avoid, Mixkit terms (no mass download) and why Pexels/Pixabay/Unsplash/Adobe Stock/Videezy are not built in.
• references/sound-design.md — voice chain, mix targets, SFX vocabulary, music catalog and section design.
• references/captions-and-layout.md — caption systems, contrast rules, safe zones, camera treatments.
• references/quality-gates.md — every gate, how to read false positives, final checklist.
• references/adding-styles.md — how to turn a successful edit into a new named style.
• references/troubleshooting.md — known failures and fixes.
• references/licenses.md — third-party components and asset licences.
• references/styles/ — one file per named style.

5. Changing heditor itself

Every change pushed to main ships as a version, never as a loose commit:

1. Bump metadata.version in this file (semver: patch for fixes and docs, minor for styles, commands and features, major for breaking changes).
2. Add a ## X.Y.Z — YYYY-MM-DD section at the top of CHANGELOG.md.
3. Commit as heditor X.Y.Z: <summary>, push to main and wait for CI to pass on that commit.
4. Create the annotated tag and the GitHub release with that CHANGELOG section as notes: git tag -a vX.Y.Z -m "heditor X.Y.Z: <summary>" && git push origin vX.Y.Z gh release create vX.Y.Z --verify-tag --title "heditor X.Y.Z: <summary>" --notes-file <notes.md> --latest
5. Read it back: gh release view vX.Y.Z shows the release as Latest and git ls-remote --tags origin lists the tag.

Full procedure in the repository's CONTRIBUTING.md.