kurbaitaev/ghost-editor/ghost-editor

ghost-editor

One recording in, one reel out. The creative work is choosing takes and planning beats. The scripts do everything else the same way every time: cut math, zoom tweens, captions, SFX levels, asset copying, QA. Nothing on screen says anything the speaker did not say. A meme is a reaction, so it lands ON or just AFTER the punchline, never before it.

Skill dir: ~/.claude/skills/ghost-editor (below: $S). A reel project is any directory ($P); build.mjs copies what it needs into $P/assets so the project renders on its own.

Cost: one fresh helper per reel, the right model per step

Measured on a batch of 21 reels: looking at frames was ~5 % of the Claude usage. The cost is context re-read on every turn (one helper that built 3 reels in a row re-read 212 M cached tokens over 464 turns) and new generator code written per reel (two helpers per style each wrote their own lib). Numbers: docs/PLAYBOOK.md "Cost".

• One reel = one FRESH helper (Agent tool). Never one helper for several reels or a wave. The session that talks to

the user orchestrates: fill templates/briefs/build-one-reel.txt (build -> preview -> stop), send them the preview, and on their OK fill templates/briefs/finish-one-reel.txt for a new helper. Changes after their notes go to a fresh helper with the reel's reel.py and their words (the generator is the state, not the old transcript); SendMessage the old helper only for a one-line fix. Spawn helpers as reel-helper when the session lists it (templates/agents/reel-helper.md, copied to ~/.claude/agents/; shell and file tools only): a general-purpose helper starts at ~85 k tokens of tool and skill lists and re-reads them on every call. Long jobs run in one blocking call, never a background job polled per turn.

• Model per step: Opus (the default) plans and judges: takes, hook, beats, components, reel.py, snapshots, the

user's notes. Sonnet (Agent tool model: "sonnet") runs fixed recipes: preview / final renders, finals.py qa / deliver, components.py record, file moves and commits. It stops on a hard QA fail and reports; the fix goes back to Opus. Many frames are Gemini Flash's job (broll_vision / broll_qa), not Claude's.

• Little code per reel: a named style's reel is a short generator on its recipe's builder (clean-os/cleanos.py +

kit.py, result-podcast/faceresult.py, whiteboard/board.py, seoul-list/seoul.py); read <builder> --api, not old generators, and never write a per-batch lib. A part two reels needed goes into the builder's kit.

• Small context: grep / sed -n, not cat; one overview sheet per look (snap.py beats -> overview.jpg), not single

frames; never re-read what you just wrote. Measure a reel with scripts/reel_usage.py <helper transcripts>.

Pipeline

prep.sh        -> $P/assets/talk.mp4        1080x1920 30 fps, voice at -16 LUFS
transcribe.py  -> $P/build/words.whisper.json + take table (all takes)
face_track.py  -> $P/build/face.json          (captions and cards never cover the face)
choose takes   -> $P/reel.json takes        (references/take-selection.md)
  a scripted recording with many takes: rawcut_prep.sh -> vad_pauses.py -> islands_tx.py -> facescan.py --pts -> takes.py -> plan_cut.py -> subcheck.py
  -> assemble.py --plan -> voice_smooth.py --plan -> qa_cut.py: the clean raw cut every style builds on (take-selection.md)
plan beats     -> $P/reel.json beats/zoom   (references/reel-json.md; taste.py prompt first)
film_look.py / transitions.py reel           optional: graded plate, transition windows (after takes are final)
build.mjs      -> $P/index.html             + SFX table + rule and taste warnings
approval_sheet.py -> build/approval.html    lint, a frame at every cut and beat; WAIT for the user's yes
own_footage.py -> the user's own clips for the lines (face-checked: only them); `sheet` -> show the picked frames, WAIT for yes
broll_fetch.py -> $P/broll/: stock originals (Pexels by link, Mixkit search) + manifest.json; when to use which: references/broll.md 3
pictures: wikimedia_fetch.py (archival first) -> google_images.py; EN + RU, >= 1080 px, people-checked (references/broll.md 3)
brand_kit.py pull <tool URL> --dir $P/brand -> a reel about a named tool/app/company: its real logo (light + dark), icon, brand colour, nearest Cyrillic Google font, people-checked product shots; LOOK at brand/sheet.jpg
image_pick.py brief/pull/score/pick/sheet -> per line 6-10 candidates scored 0-5 (says the line at a glance >= 4 or FLAG); the scores sheet goes next to the preview
insert_prep.py -> every B-roll insert: people + line check, cut, SDR, fps conform, graded onto the speaker's plate as shot (never the reverse)
components.py plan/check -> new components per reel for a named style (catalog.json); record after the user's yes
broll_vision.py picks -> build/broll-picks.jpg: every B-roll shot + stock image, its line, the people check; WAIT for the user's yes
finals.py preview -> "<name> (preview).mp4": 720x1280 at ~4.5 Mbit/s for the user's phone (+ a frame-0 still); WAIT for their OK
finals.py render  -> "<name>.mp4": delivery master -> Instagram H.264 (refuses a reel with no current preview)
finals.py qa      -> render_report.py + broll_qa.py per reel, one summary line each; fix and re-render, at most 3 rounds
qa.py             -> SFX-vs-voice on a stem, A/V lengths, contact sheet
finals.py deliver -> optional: -14 LUFS into the user's library of finished videos (CONTENT): NOT POSTED, _moves.tsv,
                     TRACKER; taste.py log-reel; save_style.py if the user loved it

0. Check the toolchain once per session

bash $S/scripts/doctor.sh: tools, GEMINI_API_KEY and the media library, each with its fix. The Gemini key is needed for the B-roll checks (the free tier is enough), and doctor proves it with one test call: insert_prep.py, broll_vision.py and broll_qa.py's people / match checks ask Gemini, and with people rules set a shot nobody could check fails the QA. On a fresh machine run python3 $S/scripts/library_restore.py first (SFX, memes, music and the animated emoji aren't in git). Say what is missing; don't improvise around it. Lines marked opt are optional tools with their own scripts/setup_<x>.sh (BiRefNet matte, audio QA, film-look LUTs, caption metrics); the core works without them.

1. Prep and look

bash $S/scripts/prep.sh <IMG_xxxx.MOV> $P
ffmpeg -v error -i $P/assets/talk.mp4 -vf "fps=1/10,scale=216:384,tile=6x3" -frames:v 1 -update 1 $P/build/sheet.jpg

Look at the sheet. Check that it is the right person (show the frames and confirm with the user when there is any doubt). Note where the face sits (the zoom origin, default 50% 29%), where the chin is (the card band starts at y 990), and how bright the wall is.

2. Transcribe everything

python3 $S/scripts/transcribe.py $P/assets/talk.mp4 --out $P/build/words.whisper.json --lang en

The table is the take map in original seconds; * marks restart phrases ("okay, again"). Fix mangled names later in captions.fixes.

2b. Track the face

python3 $S/scripts/face_track.py $P/assets/talk.mp4 --out $P/build/face.json

Always. The build places captions, cards and reactions around the face, inside the platform's safe area.

2c. Noisy outdoor audio?

Crickets, hum, wind, traffic: bash $S/scripts/denoise.sh $P/assets/talk.mp4 $P/build/voice-clean.wav (DeepFilterNet3, capped at 20 dB; full strength makes the voice thin and watery). Use the clean track for the cut and the captions. Band-limited voice (Bluetooth mic, a call, a downloaded clip): voice_enhance.py IN OUT.wav --mode superres (ClearerVoice; does nothing on full-band phone audio). Speech islands on noisy raw audio: vad_pauses.py / autocut.py --vad (silero-vad). Both run in the audio QA venv (bash $S/scripts/setup_audioqa.sh prints its python).

3. Choose takes (references/take-selection.md)

Ask for the script if there is one. Pick the take of each sentence that is fluent and later, keep one-breath runs as one take, and cut on WORD times: a = first word - 0.10..0.15, b = last word + 0.20..0.30. When a meme will follow a line, end that take 0.6 to 1 s after the last word so the meme sound has air. Aim for 45 to 75 s.

A scripted recording with many takes: the raw-cut tools (take-selection.md, "The raw cut, step by step"): rawcut_prep.sh makes the voice files and a frame-exact proxy, islands_tx.py transcribes each speech island on its own, takes.py finds every attempt at every script sentence with its face flags, plan_cut.py turns your picks (cut.json) into frame-exact pieces with trimmed pauses, blink-safe edges and keep/cover labels, subcheck.py catches merged restarts, assemble.py --plan + voice_smooth.py --plan make the plates and the voice, qa_cut.py checks the result. On Apple silicon, transcribe with mlx-whisper (transcribe.py --backend mlx).

Audit the rough cut before building. Whisper merges restarts and false starts into one clean sentence and smears timestamps across them ("And even the… and even the thing that…"). Render the rough cut, re-transcribe THAT voice, and ask Gemini 2.5 Pro (analyze_video) for a verbatim audit: repeats, fillers, clipped words, breaths, look-aways. A long stretch of voice with few words in the transcript is a hidden retake. A throat-clear ("khm") shows up in a pitch scan as a short voiced hum with falling pitch; Gemini's sub-second timestamps are not reliable enough to cut on. Leave ~0.2 s of breath between sentences.

3b. A single clean take?

If the recording is already one good take, don't pick takes by hand: python3 $S/scripts/autocut.py $P/assets/talk.mp4 --noise -30 prints takes with the pauses removed.