i-hate-editing
Drop in raw talking-head takes, get back a finished, publishable video. Every rule in this repo was paid for by a rejected render.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ranahaani--i-hate-editing)HTML
<a href="/listings/ranahaani--i-hate-editing"><img src="/api/listings/ranahaani--i-hate-editing/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Option A — skills.sh
npx skills add ranahaani/i-hate-editing
That registers the skill with your agent. You still need the local tools (`ffmpeg`, `whisper-cpp`, Playwright Chromium). Details in [`install.md`](./install.md).
Option B — paste this into your agent
Works in Claude Code, Cursor, Codex, and anything else with a shell:
Set up https://github.com/ranahaani/i-hate-editing for me. Read install.md first: clone the repo to a stable path, symlink it into this agent's skills directory, install ffmpeg + whisper.cpp, create the Python venv with playwright + pillow, and optionally run scripts/sfx_library.py install. Then read SKILL.md for daily usage. After install, don't start editing — tell me it's ready and wait for me to drop footage into a folder.
Option C — by hand
git clone https://github.com/ranahaani/i-hate-editing ~/Developer/i-hate-editing ln -sfn ~/Developer/i-hate-editing ~/.claude/skills/i-hate-editing # Claude Code ln -sfn ~/Developer/i-hate-editing ~/.cursor/skills/i-hate-editing # Cursor # ln -sfn ~/Developer/i-hate-editing ~/.codex/skills/i-hate-editing # Codex cd ~/Developer/i-hate-editing uv venv .venv && uv pip install --python .venv playwright pillow .venv/bin/playwright install chromium brew install ffmpeg whisper-cpp # macOS; use your package manager on Linux
First edit
cd /path/to/your/footage claude # or your agent of choice
> edit these into a reel
It scans the machine, asks five questions, picks a Whisper model for your language and hardware, and starts. More in [`install.md`](./install.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 437 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: i-hate-editing
- description: Turn raw talking-head takes into a finished, publishable video package — cut, captioned, scored, graded, with platform variants, post caption and thumbnail. For short-form vertical and YouTube talking-head footage. Opinionated by design; the studio makes the craft decisions and takes plain-language direction. Use when someone drops recorded footage in a folder and wants it edited.
- ---
- # I Hate Editing
- A studio, not a tool. Someone hands you raw takes; you hand back something they
- can publish without touching an editor.
- **The bar:** if a professional editor returned this, would the client accept it?
- That question decides every call you make. "The pipeline ran" is not done.
- ## Principles
- 1. **Judgement is the product; configuration is a failure state.** Never ask
- which font, which transition, which decibel level. Decide, show the result,
- and take plain direction — *punchier*, *slower*, *less music*. The user
- describes the feeling; you own the numbers.
- 2. **The rules are not suggestions.** `rules/` holds craft decisions that were
- each paid for by a rejected render, and `HARD-RULES.md` holds things that
- fail silently if you deviate. Read both before editing. Artistic freedom
- without taste memory produces the median boring cut every time — that is
- the failure this skill exists to prevent.
- 3. **Audio is the authority on time.** Cut boundaries come from silence
- detection and word onsets, never from eyeballing video.
- 4. **Verify before you present.** If you did not look at the frame or measure
- the level, it is not done. See "Verify" below — it is a gate, not a habit.
- 5. **Deliver a package.** A cut file is not the deliverable. See "Output".
- 6. **Learn from every correction.** Feedback becomes a durable rule in
- `taste.md`, read before every future edit. The studio should be better on
- the tenth video than the first.
- 7. **Never fabricate proof.** When footage references a real repo, page, tweet
- or product, capture the real thing. Never mock up something that implies a
- screenshot of reality.
- ## Setup
- First run performs a capability scan and asks what the user is making, then
- installs only what is missing:
- ```bash
- python3 scripts/scan.py
- ```
- It writes `profile.yml` (brand, language, pacing, caption style, aspect
- targets) and scaffolds the project. Everything downstream reads that file —
- there are no hardcoded brand values anywhere in this skill.
- Requirements, all free:
- | Job | Tool | Notes |
- |---|---|---|
- | Transcription | `whisper.cpp` | Local. Model chosen by language + hardware. |
- | Media processing | `ffmpeg` / `ffprobe` | |
- | Captions, cards, compositing | HyperFrames | Renders HTML/CSS/GSAP compositions. |
- | Designed scenes | Remotion | React motion graphics, one composition per scene. Installed per project by `scenes.py init`. |
- | Composition runtime | `node` 22+ | Already required by Claude Code. |
- | B-roll download | `yt-dlp` | Optional. |
- Nothing requires an API key and nothing leaves the machine.
- ## Project layout
- Footage lives wherever the user put it. All output goes in `<footage>/studio/`.
- ```
- <footage>/
- ├── <source takes, untouched>
- └── studio/
- ├── profile.yml brand, language, pacing — the only config
- ├── taste.md durable feedback; read before every edit
- ├── transcripts/ cached per source, never re-transcribed
- ├── takes.md packed phrase-level transcript (reading view)
- ├── edl.json cut decisions
- ├── composition/ HyperFrames project
- ├── scenes.json designed scenes: which beat, what moves
- ├── scenes/ Remotion project for those scenes
- ├── assets/ fetched SFX, logos, screenshots
- ├── verify/ frames and measurements from the verify pass
- └── out/ the delivered package
- ```
- ## The process
- Run in order. Two stop gates; do not run past them.
- **1 — Read state.** Load the taste memory and profile before anything else:
- ```bash
- python3 scripts/taste.py --studio <footage>/studio brief
- ```
- Those instructions override the defaults in `rules/` — they are what this
- particular person has already corrected you on. Never regenerate an artifact
- that is already on disk.
- **2 — Inventory.** `ffprobe` every source. Note resolution, fps, duration,
- audio channels. Flag anything that will bite later (variable frame rate,
- mismatched fps between takes, silent audio track).
- **3 — Transcribe.** `scripts/transcribe.py <sources>` — word-level, cached,
- language pinned from `profile.yml`. Never auto-detect: auto-detect silently
- *translates* some languages, which corrupts every downstream timestamp.
- **4 — Pack.** `scripts/pack.py` produces `takes.md`, the phrase-level reading
- view. This is what you actually read to make cut decisions — not raw JSON,
- and not the video.
- **5 — Plan the cut.** Identify beats, pick the best take of each, and place
- boundaries. This is judgement work; `rules/cutting.md` has the craft.
- Retakes cluster at file boundaries — expect one wherever a source ends.
- **6 — Assemble.** Write `edl.json`, then `scripts/render.py` for a draft.
- **7 — Verify the cut.** *Gate.* See below. Fix and re-verify before showing
- anything.
- **8 — Present the cut.**
- ```bash
- python3 scripts/review.py --studio <footage>/studio
- # phone preview on a trusted network only:
- # python3 scripts/review.py --studio <footage>/studio --lan
- ```
- Opens it in a browser with frame-stepping on **localhost**. Pass `--lan` only
- on a trusted network if you need a phone URL — that mode has no auth, and a
- machine's IP changes with the network anyway. **STOP.** Do not build captions,
- motion or sound on an unapproved cut — every downstream timestamp depends on
- it, and a base-cut change invalidates all of them.
- **9 — Enhance the voice.** Every reel, right after the cut is approved and
- before any sound effect is placed:
- ```bash
- python3 scripts/enhance.py <studio>/cut.wav -o <studio>/voice_enhanced.wav
- ```
- It runs Adobe Podcast Enhance Speech v2 through the signed-in ego-browser
- session (upload, poll, download the stems) and mixes the website's default
- "Speech 50%, Background 10%, Music 10%" locally. About 30s for a short reel.
- Then:
- 1. Level it: `acompressor=threshold=0.045:ratio=3.2:attack=6:release=110:makeup=1`,
- then gain and `alimiter=limit=0.7` to land near -18.4 LUFS. Boosting it plain
- to -15 LUFS pushes speech into the limiter and every sting collapses.
- 2. Remux it as the cut's audio (`-c:v copy`), so no video re-render is needed and
- every timestamp holds. The script fails if the duration drifts over 50 ms.
- 3. Place stings and mix against this enhanced voice, not the raw take.
- If it prints `NOT_SIGNED_IN`, ask the user to sign in to podcast.adobe.com in
- ego-browser. Never type credentials. Use `--mix full` only when asked; 100%
- enhanced speech sounds processed.
- **10 — Enrich.** In order:
- ```bash
- python3 scripts/grade.py cut.mp4 --strength normal # look at the comparison
- python3 scripts/captions.py --studio <studio>
- python3 scripts/proofread.py fix --studio <studio> --name "Claude" --name "<tool>"
- python3 scripts/capture.py <url> --studio <studio> --find "<the phrase>"
- python3 scripts/icons.py fetch claude github --studio <studio>
- # Generated stills for beats with nothing real to show — see "Generated stills".
- python3 scripts/gen_image.py "<full prompt>" --studio <studio> --name payoff --animate 3
- # Optional: 2–3 AI B-roll clips (3s each) — writes studio/broll.json + assets/broll/
- # Author studio/slots.json from takes.md beats first; see broll-gen skill.
- ~/.claude/skills/broll-gen/scripts/broll-gen generate --studio <studio> --slots <studio>/slots.json --duration 3
- python3 scripts/sfx.py plan --studio <studio> --library <sfx>
- # Designed scenes for beats with structure — see "Designed scenes".
- python3 scripts/scenes.py init --studio <studio>
- python3 scripts/scenes.py check --studio <studio>
- python3 scripts/scenes.py render --studio <studio>
- python3 scripts/compose.py --studio <studio> --render
- ```
- ### Generated stills
- `scripts/gen_image.py` talks to a local Gemini proxy
- (`http://127.0.0.1:8081/v1`, key `sk-gemini`) — no account, no cost, no
- watermark. Image generation there is a **route, not a model**: nothing in
- `/v1/models` makes images, `n` must be 1, and `size`/`quality`/`style` are
- rejected, so the aspect goes in the prompt text. The script injects the
- vertical-9:16 clause for you and warns if what comes back is landscape. It
- injects nothing else — when a beat needs text, logos, screens or UI kept out,
- put that ban at the end of that beat's own prompt.
- **Reach for it only after checking there is nothing real to show.** A repo, a
- page, a dashboard always beats a generated still — see `rules/proof.md`. And a
- generated image must never imply a screenshot of something real.
- **Write the whole prompt.** A short prompt returns a stock-photo cliché. Every
- prompt states, in this order: the subject, the setting, the camera (lens,
- aperture, height), the lighting with its direction and colour temperature, the
- composition including which parts of the frame stay empty, the mood, and the
- ban list. `--animate N` renders a push-in clip from the still, because a
- generated still that sits motionless is a dead frame; add the clip to
- `broll.json` as an overlay.
- Worked prompt, for the "gold mine" payoff beat of a reel about saving money:
- > A deep underground cavern of glowing golden light, with streams of tiny
- > luminous golden particles rising out of the darkness like sparks. Rich black
- > background, warm gold highlights, high contrast, dramatic rim lighting,
- > shot on a 35mm lens at f2, abstract and atmospheric, the lower third almost
- > pure black so captions stay readable. Cinematic, fine film grain.
- Full prompt library and failure log: `~/ai-me/reels/docs/agent-suggestions.md`
- and `~/.claude/skills/virtual-bg/references/plate-prompts.md`.
- **Do not generate a virtual background.** Reels ship with the real room — see
- `taste.md` under framing, and the STOP notice in the `virtual-bg` skill.
- You author four files by hand, the same way you author the EDL. They are the
- edit; the scripts only render them.
- **`cards.json`** — the motion vocabulary. Without it the piece is a face with
- captions, and `beats.py` will fail step 11.
- ```json
- {"cards": [
- {"start": 0.35, "duration": 5.1, "style": "band", "big": "SIX WORDS OR FEWER"},
- {"start": 13.1, "duration": 4.2, "kicker": "small label above",
- "big": "HEADLINE WITH *ACCENT* WORD", "sub": "one supporting line",
- "items": [{"title": "row one", "note": "right-aligned"},
- {"title": "row two", "note": "staggered in"}]},
- {"start": 21.6, "duration": 1.9, "full": true, "big": "OWNS THE *FRAME*"}
- ]}
- ```
- Add `"icon": "claude.svg"` to put a brand mark on a card, and
- `"brand_colour": "#D97757"` to theme the whole card in that brand's colour —
- `icons.py` reports the official hex when it fetches. A named tool with its own
- mark on its own colour reads as designed; the same dark card every time reads
- as a template.
- `style: "band"` is the hook headline over a full frame. Default is a
- half-screen split: card on top, face below. `full: true` takes the whole frame
- and hides the face — captions are suppressed under it. `*asterisks*` mark the
- accent word. `items` makes it a numbered list. Choose the form from what the
- sentence is doing, and the arrival is chosen for you — see `rules/motion.md`.
- Captions come out of `captions.py` as a raw pass and are marked
- `proofread: false`. `proofread.py` restores product names and strips
- punctuation artefacts, but it cannot fix meaning — so it only marks them
- proofread when a model pass ran (`--llm "<any command>"`) or when you rewrote
- the copy yourself and passed `--accept`. Verification fails while the flag is
- false, because captions are the most-read thing on screen.
- **`proof.json`** — real pages: which capture, which target, which move.
- ```json
- {"beats": [
- {"asset": "repo", "start": 6.9, "duration": 3.1,
- "action": "scroll", "from_y": 60, "to_y": 560},
- {"asset": "repo", "start": 10.1, "duration": 2.9, "action": "zoom",
- "target": "the exact text", "highlight": true, "highlight_at": 0.75}
- ]}
- ```
- `asset` is the `--name` you gave `capture.py`. `target` must be text that
- capture found. `rules/proof.md` has the craft.
- **`scenes.json`** — designed scenes, built in Remotion. A card is text on a
- ground; a scene is a built visual with structure — a counter running, a
- comparison assembling, a stylised UI typing. Beats with structure go here
- rather than into a headline and a sub-line.
- ```json
- {"scenes": [
- {"id": "token-waste", "start": 12.4, "duration": 3.2, "full": true,
- "line": "every retry re-sends the whole conversation",
- "visual": "context bar fills, three retry chips stack on it, bar turns red on the third",
- "assets": ["claude.svg"]}
- ]}
- ```
- `scenes.py sync` writes the Remotion project's `Root.tsx` and
- `src/data/scene-spec.json` from this file and the cut — one composition per
- scene, at the cut's own size and frame rate. You write only the components, in
- `<studio>/scenes/src/scenes/<Component>.tsx`. `scenes.py studio` opens Remotion
- Studio to preview them, `render` writes one MP4 per scene and registers them as
- overlays so `compose.py` composites them under the captions.
- Show `scenes.json` before writing any component — a component written against
- an unapproved beat is the expensive artefact to throw away. Craft and the
- self-review checklist: `rules/scenes.md`. Scene stings go in `sfx.json`, never
- inside the component: overlays composite muted (`HARD-RULES.md`).
- **`profile.yml`** — written by `scan.py`, or by hand when it cannot run
- interactively:
- ```yaml
- language: ur
- translate_captions: true
- aspects: ["9:16"]
- pacing: punchy # punchy | balanced | restrained
- brand: {accent: "#76B900", font: "Archivo Black"}
- transcription: {model: large-v3-turbo}
- face_half_y: 30 # vertical crop of the face in a split
- ```
- This is where a trimmed recording becomes an edited video.
- **11 — Verify the render.** *Gate.* Frames and levels, again, plus the beat
- map:
- ```bash
- python3 scripts/beats.py --studio <studio> # stretches with nothing new
- python3 scripts/sound.py check out/master.mp4 # stings audible, not just present
- ```
- A shot that sits still is the most-reported defect in short-form and the
- easiest to miss, because nothing errors when a face holds for ten seconds.
- **12 — Deliver the package.**
- ```bash
- python3 scripts/music.py out/master.mp4 <bed>.mp3 -o out/final.mp4
- python3 scripts/deliver.py --studio <studio>
- python3 scripts/review.py --studio <studio>
- ```
- Then write `out/post.md` yourself from the spoken lines it surfaces, and look
- at the thumbnail candidates and pick one. Neither is generated: a generated
- title reads like a generated title, and "face clear, eyes open" is not a
- metric.
- **13 — Learn.** Record every correction the user made, phrased as an
- instruction for next time and filed under the area it affects:
- ```bash
- python3 scripts/taste.py --studio <footage>/studio add captions \
- "Start each caption 0.08s after the word is spoken, never before" \
- --said "we show early for a sec then I start speaking"
- ```
- Always pass `--said` with their actual words. The instruction is your reading
- of the feedback and can be wrong; keeping the original means a bad reading can
- be corrected later instead of quietly hardening into a rule.
- When a rule stops applying, retire it rather than deleting it —
- `taste.py retire <area> <n>` — so the reversal stays visible.
- ## Verify
- Two failures survive every automated check and both get flagged by users, so
- hunt them explicitly.
- **Repeated phrases at seams.** A join can leave a word said twice. Transcribe
- the rendered cut in short windows aligned to each seam — never one whole-file
- pass, which condenses and hides the defect.
- **Clipped clauses.** Every kept block must start and end on a complete
- thought. A cut that lops a negation inverts the meaning of the sentence. If
- the clause only completes in a later take, stitch the two rather than shipping
- the fragment.
- Then: `ffprobe` the duration against what the EDL predicts, extract frames at
- every boundary and look at them, and measure audio levels at each sound effect
- against a voice-only baseline. "Not clipping" is not the same as "audible" —
- see `rules/sound.md`.
- ## Output
- Every finished run delivers a package, because that is what an editor hands
- back:
- - **Master** — graded, mixed, captioned
- - **Platform variants** — vertical, square, landscape as `profile.yml` requests
- - **Post caption** — hook line, substance, hashtags
- - **Thumbnail frame** — pulled from the cut, face visible, no mid-blink
- - **Title options** — a small set to choose from
- ## House style
- Locked on the NVIDIA and Promptive reels (2026-10-02). Apply it by default; the
- details and the reasons are in the rules files named.
- - **Hook, 0 to about 3.4s** (`rules/hooks.md`, "The split-proof hook"):
- - Split from frame 0, with an HD visual on top and the face below.
- - Text: 2-3 familiar words plus one emoji ("CLAUDE / LIMIT ISSUE 😕").
- - The top panel changes once at 1.0-1.3s.
- - Named tools' marks pop in on their spoken names.
- - A loss word turns the whole frame red for about 0.5s.
- - Plan it with `hook_plan.py --proof <capture>`.
- - **Everything HD:**
- - The hook's top panel is a motion graphic built at frame resolution, never
- an upscaled screenshot.
- - Rebuild product screenshots as native Flick/Remotion scenes at 1080x960,
- using the real UI's text (`rules/proof.md`).
- - **Palette:** green `#76B900` for emphasis words in captions, accents, chips
- and borders. The ground is near-black green with a slow-drifting grid. It is
- the profile default; a brand colour in `profile.yml` still wins.
- - **Sound:**
- - Pop sting: `assets/sfx/pop_dragon.mp3` (peak 0.197s; start = hit - 0.197).
- - Impact on frame 1, swoosh on a panel swap, click on a highlight.
- - Every sting +2 to +4 dB above the enhanced voice (centre +3.1). Master at
- -15 LUFS.
- - **Voice:** Adobe Enhance (step 9) on every reel.
- - **Cut:** transcribe the first 0.3s of every block on its own. A clipped false
- start ("com" before "link chahiye") hides at block heads.
- ## Craft rules
- Read the relevant file before touching that part of the edit. Each rule states
- the failure it prevents.
- | File | Covers |
- |---|---|
- | `HARD-RULES.md` | Correctness. Silent failures. Non-negotiable. |
- | `rules/cutting.md` | Take selection, boundaries, silence, pacing |
- | `rules/hooks.md` | Openings, headline, retention |
- | `rules/captions.md` | Timing, chunking, style |
- | `rules/sound.md` | Sound effect placement, levels, music |
- | `rules/proof.md` | Screenshots, B-roll, zoom and highlight |
- | `rules/motion.md` | Zooms, transitions, cards, layout |
- | `rules/scenes.md` | Designed Remotion scenes: when, how, what to check |
- | `rules/framing.md` | Crops, splits, composition |
- | `rules/assets.md` | Where pictures come from: proof, reference clips, flick, generated stills, Flow |
- ## Anti-patterns
- - Asking the user to configure something you should have decided.
- - Building captions or motion before the cut is approved.
- - Trusting a whole-file transcript to verify a cut.
- - Concluding a sound effect works because it did not clip.
- - Re-transcribing a source that has not changed.
- - Auto-detecting the spoken language.
- - Presenting output you did not look at.
- - Rendering a sentence with structure as a headline and a sub-line.
- - Writing a scene component before `scenes.json` was agreed.
- - Baking a sound effect into a scene, where the mix never hears it.
- - Adding a feature nobody asked for.
- - Finishing an edit without recording what the user corrected.
README.md · README · 329 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # I Hate Editing
- [](https://github.com/ranahaani/i-hate-editing#option-a--skillssh)
- [](./LICENSE)
- [](./install.md)
- [](./SECURITY.md)
- Drop in raw talking-head takes. Get back something you can publish.
- I named it after a note to myself: never hand back work that still needs fixing
- by hand.
- <p align="center">
- <img src="docs/demo.gif" alt="The same reel twice: the plain face-only cut on the left, the finished reel with proof cards, captions and sound on the right, pipeline log in a terminal below." width="820">
- </p>
- <p align="center">
- <em>Same reel on both phones, frame for frame. Left is the cut with nothing
- added; right is what shipped.
- <a href="https://www.instagram.com/ranahaani.me/reels/">More reels on Instagram</a>.</em>
- </p>
- The skill picks the take, decides the repo and the docs page were worth
- capturing, where to zoom, which line gets the highlighter, what goes on each
- card, and where every sound lands. You say "punchier." It owns the numbers.
- ## Reels made with it
- <p align="center">
- <a href="docs/reels/strix.mp4"><img src="docs/reels/strix.jpg" alt="Strix reel" width="220"></a>
- </p>
- <p align="center">
- <em>Strix, straight out of <code>studio/out</code>. Click to play.
- More on <a href="https://www.instagram.com/ranahaani.me/reels/">Instagram</a>.</em>
- </p>
- ## What it does
- - Cuts from silence and word onsets, not from scrubbing the timeline
- - Re-transcribes a short window around every seam so repeated words and
- mid-clause cuts get caught before you see a preview
- - Writes captions that still read on a phone, with a proofread gate before
- they ship
- - Captures real pages as tall stills, then scrolls, zooms, and highlights the
- line you said (no mocked screenshots)
- - Places free-licensed SFX by intent and aligns peaks so a short window is
- actually audible
- - Builds beats with structure as real motion graphics — Remotion components,
- previewed in Studio, composited under the captions
- - Hands back a package: master, platform crops, ranked thumbnails, post lines
- - Remembers corrections in `taste.md` so the tenth video is better than the first
- - Runs transcription on your machine with `whisper.cpp`. No cloud STT key.
- Built for talking-head reels and YouTube explainers.
- ## Quick start
- ### Option A — skills.sh
- ```bash
- npx skills add ranahaani/i-hate-editing
- ```
- That registers the skill with your agent. You still need the local tools
- (`ffmpeg`, `whisper-cpp`, Playwright Chromium). Details in
- [`install.md`](./install.md).
- ### Option B — paste this into your agent
- Works in Claude Code, Cursor, Codex, and anything else with a shell:
- ```text
- Set up https://github.com/ranahaani/i-hate-editing for me.
- Read install.md first: clone the repo to a stable path, symlink it into this
- agent's skills directory, install ffmpeg + whisper.cpp, create the Python venv
- with playwright + pillow, and optionally run scripts/sfx_library.py install.
- Then read SKILL.md for daily usage. After install, don't start editing —
- tell me it's ready and wait for me to drop footage into a folder.
- ```
- ### Option C — by hand
- ```bash
- git clone https://github.com/ranahaani/i-hate-editing ~/Developer/i-hate-editing
- ln -sfn ~/Developer/i-hate-editing ~/.claude/skills/i-hate-editing # Claude Code
- ln -sfn ~/Developer/i-hate-editing ~/.cursor/skills/i-hate-editing # Cursor
- # ln -sfn ~/Developer/i-hate-editing ~/.codex/skills/i-hate-editing # Codex
- cd ~/Developer/i-hate-editing
- uv venv .venv && uv pip install --python .venv playwright pillow
- .venv/bin/playwright install chromium
- brew install ffmpeg whisper-cpp # macOS; use your package manager on Linux
- ```
- ### First edit
- ```bash
- cd /path/to/your/footage
- claude # or your agent of choice
- ```
- > edit these into a reel
- It scans the machine, asks five questions, picks a Whisper model for your
- language and hardware, and starts. More in [`install.md`](./install.md).
- ## How it works
- The model does not watch the video. Audio is the clock. Scripts do the
- mechanical work; the agent only makes taste calls.
- ```mermaid
- %%{init: {
- "theme": "base",
- "themeVariables": {
- "fontFamily": "ui-sans-serif, system-ui, sans-serif",
- "fontSize": "14px",
- "primaryTextColor": "#0f172a",
- "lineColor": "#94a3b8",
- "clusterBkg": "#ffffff00",
- "clusterBorder": "#e2e8f0",
- "edgeLabelBackground": "#ffffff",
- "tertiaryColor": "#f8fafc"
- },
- "flowchart": {
- "curve": "basis",
- "padding": 16,
- "nodeSpacing": 32,
- "rankSpacing": 40,
- "htmlLabels": true
- }
- }}%%
- flowchart TB
- RAW(["🎬 raw takes"]):::src
- PROF(["🎛️ profile.yml"]):::cfg
- subgraph A["🎧 1 · LISTEN"]
- direction LR
- SCAN(["🔍 scan"]):::listen
- ASR(["🗣️ whisper.cpp"]):::listen
- PACK(["📄 pack"]):::listen
- SIL(["🔇 silences"]):::listen
- TAKES[("takes.md")]:::artBlue
- GAPS[("gaps.json")]:::artBlue
- SCAN --> ASR --> PACK --> TAKES
- SCAN --> SIL --> GAPS
- end
- subgraph B["✂️ 2 · CUT · HARD GATE"]
- direction LR
- EDL[("edl.json")]:::artAmber
- RND(["🎞️ render"]):::cut
- VER{"🛡️ verify<br/>seam re-ASR"}:::gate
- GRD(["🎨 grade"]):::cut
- CUTV[("cut.mp4")]:::artAmber
- EDL --> RND --> CUTV --> VER
- VER -- "❌ fail" --> EDL
- VER -- "✅ pass" --> GRD
- end
- subgraph C["✨ 3 · ENRICH"]
- direction LR
- CAP(["💬 captions"]):::enrich
- PRF(["🌐 proof"]):::enrich
- SFX(["🔊 sfx + music"]):::enrich
- CMP(["🧩 compose"]):::enrich
- MASTER[("master.mp4")]:::artPink
- CAP --> CMP
- PRF --> CMP
- SFX --> CMP
- CMP --> MASTER
- end
- subgraph D["🚀 4 · SHIP"]
- direction LR
- DEL(["📦 deliver"]):::ship
- PKG[("studio/out")]:::artGreen
- REV(["👀 review"]):::ship
- DEL --> PKG --> REV
- end
- RAW --> SCAN
- PROF -.-> SCAN
- PROF -.-> CAP
- TAKES --> EDL
- GAPS --> EDL
- GRD --> CAP
- GRD --> PRF
- GRD --> SFX
- MASTER --> DEL
- classDef src fill:#0f172a,stroke:#facc15,stroke-width:3px,color:#fef08a
- classDef cfg fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
- classDef listen fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a8a
- classDef cut fill:#ffedd5,stroke:#ea580c,stroke-width:2px,color:#9a3412
- classDef enrich fill:#f3e8ff,stroke:#9333ea,stroke-width:2px,color:#581c87
- classDef ship fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
- classDef gate fill:#fee2e2,stroke:#dc2626,stroke-width:3px,color:#7f1d1d
- classDef artBlue fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1d4ed8
- classDef artAmber fill:#fffbeb,stroke:#d97706,stroke-width:2px,color:#b45309
- classDef artPink fill:#fdf4ff,stroke:#c026d3,stroke-width:2px,color:#86198f
- classDef artGreen fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#15803d
- style A fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af
- style B fill:#fff7ed,stroke:#f97316,stroke-width:2px,color:#c2410c
- style C fill:#faf5ff,stroke:#a855f7,stroke-width:2px,color:#7e22ce
- style D fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#15803d
- linkStyle 8 stroke:#dc2626,stroke-width:2.5px
- linkStyle 9 stroke:#16a34a,stroke-width:2.5px
- ```
- `verify` blocks the cut. `review` is when you look at the package. If you change
- the cut after captions and sound are built, those timestamps are wrong. Start
- that layer over.
- ```
- footage/
- ├── take-01.mp4 your sources stay put
- └── studio/ everything the skill writes
- ├── profile.yml
- ├── taste.md
- ├── transcripts/
- ├── edl.json
- ├── composition/
- └── out/ what you publish from
- ```
- ## Why this exists
- Two things matter. The rest is plumbing.
- Joins love to leave a word sitting there twice. Cuts land mid-clause and flip
- what you meant. A whole-file transcript papers over both. So after the cut
- renders, verify re-transcribes short windows on each seam. Repeats are
- mechanical. Broken clauses get flagged for a human call.
- And when you correct something, it sticks. "Captions feel early" goes into
- `taste.md` and shows up on the next job. You should not have to teach the same
- lesson twice.
- You also should not be asked which font, which transition, or what decibel
- level. Say *punchier*, *slower*, *less music*. The studio owns the numbers.
- ## Proof B-roll
- Name a repo, an article, a number. The skill opens the real page in a vertical
- viewport, grabs one tall still, then scrolls, zooms, and draws a highlighter
- across the line you said.
- A screen recording locks scroll speed forever. A still plus motion in the
- composition can re-time with the cut and sit on the same timeline as your face,
- captions, and sound.
- Targets are text, not CSS selectors. If the line is not on the page, it says so
- instead of grabbing something nearby.
- ## The rules
- Each rule exists because a render failed once and we paid for it.
- | File | Covers |
- |---|---|
- | [`HARD-RULES.md`](./HARD-RULES.md) | Silent failures. Non-negotiable. |
- | [`rules/cutting.md`](./rules/cutting.md) | Take selection, seams, what to remove |
- | [`rules/hooks.md`](./rules/hooks.md) | Openings, headline, retention |
- | [`rules/captions.md`](./rules/captions.md) | Timing, chunking, style |
- | [`rules/sound.md`](./rules/sound.md) | Placement, levels, audibility |
- | [`rules/motion.md`](./rules/motion.md) | Zooms, pacing, easing |
- | [`rules/framing.md`](./rules/framing.md) | Crops, splits, composition |
- | [`rules/proof.md`](./rules/proof.md) | Screenshots, B-roll, zoom, highlight |
- Agent instructions: [`SKILL.md`](./SKILL.md). Threat model: [`SECURITY.md`](./SECURITY.md).
- ## Requirements
- | Tool | Why | Required |
- |---|---|---|
- | `ffmpeg` / `ffprobe` | Media | Yes |
- | `whisper.cpp` | Local transcription | Yes |
- | `node` 22+ | HyperFrames | Yes |
- | `playwright` + `pillow` | Proof capture, thumbnails | For proof / deliver |
- | `yt-dlp` | Reference footage | Optional |
- ## Limitations
- - Talking-head short-form and explainers. Not travel montages or multi-cam.
- - You bring the music bed. The skill ducks it; it does not license tracks.
- - Proof capture needs Chromium. Skip it if face + captions is enough.
- - First Whisper download is roughly 0.5–3 GB, depending on language and hardware.
- ## Contributing
- Best PR is a rule: what failed, what it cost, what you will never do again. Add
- it under [`rules/`](./rules/) or in [`HARD-RULES.md`](./HARD-RULES.md).
- ```bash
- uv venv .venv && uv pip install --python .venv pytest
- .venv/bin/pytest -q
- ```
- ## Disclaimers
- Footage stays on your machine. Scripts can still hit the network for proof
- pages, Mixkit SFX, a pinned HyperFrames package, and Remotion when a project
- uses designed scenes. See
- [`SECURITY.md`](./SECURITY.md).
- Copyright on `yt-dlp` downloads and music beds is on you. Brand marks from
- Simple Icons / Lucide are for editorial use; check trademark rules before ads.
- `review.py` binds localhost by default. Only pass `--lan` on a network you
- trust. No auth on that server.
- ## Credit
- Composition and rendering by
- [HyperFrames](https://github.com/heygen-com/hyperframes) (version pinned in
- `scripts/compose.py`).
- Designed scenes are [Remotion](https://www.remotion.dev) compositions. That
- layer's shape — a spec approved before anything is built, one composition per
- scene, frame-driven motion, no background music — is adapted from
- [Creatorberry's flick](https://github.com/Creatorberry/flick) (MIT), which does
- the same job standalone and is worth using directly if a script is all you have.
- MIT. Vulnerabilities: [`SECURITY.md`](./SECURITY.md).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.