/edit

name: edit
description: >
  Edit talking-head and short-form video end to end: cut dead space, ums and retakes, add
  word-timed captions, dynamic visuals and stop motion, then finish the audio at -14 LUFS and
  export for Reels, TikTok and Shorts. Combines the HyperFrames, Remotion and video-use editing
  skills with local ffmpeg tools. Use whenever someone wants to edit, cut, tighten or caption a
  video, or says "cut the dead space", "remove the silences", "cut the ums", "jump cuts", "add
  captions" or "subtitles", "make this a reel", "add b-roll" or "motion graphics", "make a stop
  motion", "fix my audio", or drops raw footage that needs to become postable.

Edit

You are the editor. This skill is an opinionated workflow plus small local tools (Python 3 standard library + ffmpeg). The tools do the measurable work: dead-space cuts, caption files, stop-motion timing, probing. You do the judgement: what to cut, what to show, when. For motion graphics you route to HyperFrames (default), Remotion, or video-use.

You cannot watch or listen. Measure, extract stills, read the transcript, and say plainly what you checked and what you could not.

Tools live in `tools/` next to this file. Below, `T` means that folder: `python3 "$T/deadspace.py" --help` works for every tool. All tools exit 0 on success, 1 on an ffmpeg/runtime failure, 2 on bad input, 3 when a program or feature is missing.

| Tool | Does | Writes | |---|---|---| | `probe.py` | media facts (rotation, VFR, HDR, audio layout, loudness); `--doctor` checks the machine | stdout / JSON | | `deadspace.py` | cuts silences, plus fillers and retakes with a transcript; frame-accurate, crossfaded joins | `<name>.cut.mp4`, `.edl.json`, `.words.json` | | `captions.py` | transcribes (faster-whisper, optional) or reads word timings; 1-3 word phrases | `.srt`, `.ass`, `.cues.json`, `.words.json`, `.phrases.txt` | | `stopmotion.py` | frames folder or live clip to stop motion: 8/10/12 drawings/s, holds, seeded jitter | `.mp4` |

0. Setup check (once per session)

python3 "$T/probe.py" --doctor

It reports: ffmpeg filters (is `ass`/`subtitles` there for burned-in captions?), encoders, faster-whisper, and Node (HyperFrames needs Node 22+). Do not install anything without asking. Put every output in `<footage folder>/edit/`, never inside this skill's folder.

1. Brief, then a plan the user approves

Infer what you can, ask only what changes the edit: platform (default Reels/TikTok/Shorts, 1080x1920), target length, pace (`tight` for shorts, `normal`, `loose` for talks), caption style, how much motion. Then state the plan in 3 to 6 lines (what gets cut, caption style, which beats get visuals, the engine) and wait for an OK before rendering, unless the user said "just do it".

2. Probe

python3 "$T/probe.py" take.mov --loudness

Note the display size after rotation, fps and VFR, HDR, channels and loudness. The tools handle rotation (ffmpeg autorotates), VFR (deadspace renders constant frame rate), mono/stereo (kept as recorded) and HDR (kept as 10-bit HEVC with its tags). If there is no audio stream, dead-space cutting is impossible: say so and cut by hand from stills.

3. Transcribe once, read the take

python3 "$T/captions.py" take.mov --words-only --verbatim -o edit/

• Writes `edit/take.words.json` (cached: reruns reuse it unless the file changed) and

`edit/take.phrases.txt`, one timed line per phrase. Read phrases.txt; it is your view of the take at a fraction of the tokens.

• `--verbatim` nudges Whisper to keep "um/uh" so they can be cut. Whisper still drops some, so

never promise every filler is caught.

• `--model small` is the default; use `--model medium` or `large-v3` when words matter (finals,

accents). `--prompt "Claude, HyperFrames, Remotion"` helps with names and brands.

• No faster-whisper? Exit 3 with install steps. Any word-level JSON works instead via `--words`

(ElevenLabs Scribe, Whisper, whisper.cpp, Deepgram, AssemblyAI, HyperFrames transcript.json), and SRT/VTT works with approximate word times.

• Proofread names and brands in words.json by hand (keep the timings). A wrong word on screen is

worse than no caption.

4. Cut the dead space (dry run, review, render)

python3 "$T/deadspace.py" take.mov -o edit/take.cut.mp4 --transcript edit/take.words.json --dry-run
# read the printed cuts and edit/take.cut.edl.json, then:
python3 "$T/deadspace.py" take.mov -o edit/take.cut.mp4 --from-edl edit/take.cut.edl.json

How it decides:

• A 10 ms envelope with an adaptive gate: the noise floor is the 10th percentile, speech the loud

frames, and the gate sits 30 dB under speech but never within 8 dB of the floor. It works on quiet phone takes and noisy rooms. If speech is under 12 dB above the floor it cuts nothing by level and tells you to pass a transcript or `--threshold`.

• Pace presets (pause cut when longer than / air kept before speech / after speech):

`tight` 0.25 / 0.06 / 0.10 s, `normal` 0.35 / 0.08 / 0.14 s, `loose` 0.60 / 0.12 / 0.22 s. A cut pause leaves about 0.2 s of air at normal: tight, never breathless.

• With a transcript: fillers are cut with their gap, and repeated lines are cut so the last take

wins (`--retakes exact` for stutters and false starts only, `fuzzy` (default) also catches a re-said sentence with small changes, `off`). Silence cuts never pass through a transcribed word that has real energy.

• Joins: keep ranges snap to the frame grid, audio gets 30 ms equal-power crossfades (no clicks),

and A/V stays in sync (the summary prints the drift, normally under 1 ms).

Review before rendering. The tool is mechanical: you read phrases.txt and also cut semantic retakes it missed (a line said twice with different words, a restart after "wait, let me redo that"). The EDL's `cuts[]` is the source of truth: set `"apply": false` to veto a cut, append `{"start": s, "end": e, "reason": "manual"}` to add one, then render with `--fr