@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/cut-video/SKILL.md

@@ -1,387 +0,0 @@
----
-name: cut-video
-description: "Tighten a long recording aggressively — remove silences, fillers, hedges, false starts, and repetitions while preserving laughs and comedic pauses. Cuts are driven by Montreal Forced Aligner (MFA) word boundaries (auto-installs on first run), not raw Whisper timestamps. Use when the user pastes a video and says \"cut this\", \"tighten this video\", \"remove silences\", \"strip ums\", \"clean this up\", or any variant of \"make this video shorter without losing the good parts\". Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "louisedesadeleer/cut-video"
----
-
-# Cut Video
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-Tighten a long-form recording **aggressively**: remove silences, fillers, hedges, weak transitions, false starts, and repetitions. Preserves laughs and comedic pauses. Outputs a cleaned MP4 ready to drop into CapCut for layouts/zooms/memes.
-
-> **This skill is more accurate than cutting from Whisper alone.** Cuts are driven by **Montreal Forced Aligner (MFA)** word boundaries (~10–20ms precision, with true inter-word silences as explicit intervals), not Whisper timestamps (±100–300ms, with pauses embedded inside word durations). Whisper is used only to produce the transcript *text* that MFA aligns to the audio. The result: tighter cuts, no clipped word onsets/tails, and reliable silence detection.
-
-> **⚠️ But MFA times are a DRAFT, not ground truth (burned 2026-07-02, `AI is bad at jokes` DJI run).** MFA can only align the transcript whisper gave it. On retake-heavy footage whisper COLLAPSES repeated lines, so MFA smears one transcribed instance across several spoken takes — measured drift on that run was **1–6 seconds** in the back half ("the average of all working code": MFA said 217.2s, real onset 225.4s; the final "what this means" take: MFA said 114.7s, real 130.4s). Every keep boundary must be **ground-truthed with isolated-window re-transcription (Step 2.5)** before rendering. Skipping that step on that video would have produced garbage cuts for the entire second half.
-
-**Style target** (calibrated from `AI mogging my dad.mp4`):
-- ~1 cut every 1.3–1.5 seconds (median cut duration ~1.1s)
-- ~40–60% total runtime reduction from raw
-- Cuts happen mid-sentence, not just between sentences
-- Word-by-word tightening — fillers, hedges, and weak openers get sliced
-
-## Inputs
-
-- Video file path (the user will provide; otherwise ask)
-- Optional: tone preference (`aggressive` / `balanced` / `sentimental` / `documentary`) — default: `aggressive`
-
-## Working directory
-
-`/tmp/cut-video/<basename>/` — mkdir at start, leave artifacts for debugging.
-
----
-
-## Step 0 — Make a proxy (the single biggest speed move)
-
-If the source is HEVC, >500MB, or 4K+, transcode to a 1080p H.264 working copy FIRST. Every subsequent step runs against the proxy, not the source.
-
-**Check orientation first** (`ffprobe … width,height`) — DJI/phone footage is often vertical 9:16, and a hard-coded `scale=1920:1080` would squash it. Use `scale=1920:1080` only for landscape; use `scale=1080:1920` for portrait (or the orientation-proof `scale=-2:1080` / `scale=1080:-2`).
-
-```bash
--vf scale=1920:1080 \        # portrait sources: scale=1080:1920
-  -c:v libx264 -preset fast -crf 20 -pix_fmt yuv420p \
-  -c:a aac -b:a 192k \
-  /tmp/cut-video/$NAME/proxy.mp4
-```
-```
-**Critical flags:**
-- `-hwaccel videotoolbox` on the INPUT — hardware-decodes HEVC, ~5–10× faster on Apple Silicon. Skip this and you'll wait minutes instead of seconds.
-- `-preset fast` — the libx264 default is `medium`, which is ~3× slower for no useful quality gain on a working copy.
-
-Hardware encode alternative (even faster on M-series, slightly larger file):
-```
-```bash
--c:v h264_videotoolbox -b:v 8M
-```
-
-## Step 1 — Get the transcript TEXT (whisper, as input for MFA)
-
-MFA is a **forced aligner, not a transcriber** — it needs a transcript to align. Whisper's only job here is to produce that text; **whisper word timestamps are NOT used for cutting** (they're ±100–300ms off and turbo embeds pauses inside word durations). MFA (Step 1.5) supplies all timing.
-
-```bash
--vn -ac 1 -ar 16000 /tmp/cut-video/$NAME/audio.wav
-whisper /tmp/cut-video/$NAME/audio.wav \
-  --model tiny.en --word_timestamps True --output_format json \
-  --output_dir /tmp/cut-video/$NAME --language en
-```
-```
-**Model choice (revised 2026-07-02 — "we only need the words" was WRONG):** the transcript text IS the alignment input, so transcript errors become timing errors. On the `AI is bad at jokes` run, `tiny.en` dropped exactly the words the old warning predicted ("bland", "slop"), misheard "Compare this to" as "comparative is", and collapsed full-line retakes — and MFA, aligning that wrong text, drifted 1–6s across the back half. Use **`tiny.en` only for a first fast pass to see the take structure**; if the transcript shows retakes/repetitions, or the footage is noisy/outdoor, the per-region ground-truth pass (Step 2.5) with `small.en` supplies the real cut times anyway. (A full-pass `small.en` transcript is a reasonable upgrade for the MFA input too — ~1–2 min on a 5-min video — but it ALSO collapses retakes, so it does not remove the need for Step 2.5.) For non-English use `--model base` and drop `--language`. We keep `--word_timestamps True` only so whisper times survive as a cross-check/fallback (Step 1.5 caveats, 2a-legacy) — never as the primary cut source.
-```
-
-## Step 1.5 — Align the transcript to the audio with MFA (Montreal Forced Aligner) — the timing engine
-
-This is the spine of the skill. **MFA forced-aligns the whisper transcript text to the audio** and returns word boundaries at ~10–20ms precision, with true inter-word silences as explicit empty intervals. **All cut decisions (gaps, fillers, false starts, retakes) use MFA word times.**
-
-**Auto-install MFA (the skill does this itself — don't make the user do it).** Run this idempotent bootstrap at the start of every run; it's a no-op once everything's present (a few seconds), and a one-time ~2–3 min install on a fresh machine. Tell the user "installing MFA (one-time)…" only when it actually installs something.
-
-# 2. Ensure the mfa env exists with MFA installed
-if ! conda env list | grep -q '^mfa\b'; then
-  echo "creating mfa conda env (one-time)…"
-  conda create -n mfa -c conda-forge montreal-forced-aligner -y
-fi
-
-# 3. Ensure the English acoustic model + dictionary are downloaded (idempotent; skips if present)
-conda run -n mfa mfa model download acoustic english_mfa  2>/dev/null || true
-conda run -n mfa mfa model download dictionary english_mfa 2>/dev/null || true
-```
-If `brew` itself is missing, MFA can't be auto-installed — fall back to the whisper+silencedetect path (see the fallback bullet below) and tell the user, with the one-line `brew install miniforge` they'd need to unlock MFA precision.
-
-**Per run:**
-```
-
-# corpus = a dir with audio.wav + audio.txt (the whisper transcript as PLAIN TEXT, no timestamps)
-mkdir -p /tmp/cut-video/$NAME/corpus
-cp /tmp/cut-video/$NAME/audio.wav /tmp/cut-video/$NAME/corpus/
-python3 -c "import json;d=json.load(open('/tmp/cut-video/$NAME/audio.json'));open('/tmp/cut-video/$NAME/corpus/audio.txt','w').write(d['text'])"
-conda run -n mfa mfa align --clean /tmp/cut-video/$NAME/corpus english_mfa english_mfa /tmp/cut-video/$NAME/aligned
-
-# → aligned/audio.TextGrid — "words" tier: (start, end, word); EMPTY-label intervals = true silences
-```
-Parse the TextGrid `words` tier (pip `praatio`, or a 20-line parser — interval tiers are plain text). What MFA buys:
-- **True word boundaries** → cut pads shrink to ~0.02s, no clipped word onsets/tails.
-- **True silences are explicit empty intervals** → the 2a gap table works directly off the TextGrid; the whisper embedded-pause problem disappears.
-- **Caveat:** MFA aligns the transcript it's GIVEN. If whisper collapsed a spoken stutter ("growth… growth marketer" → "growth marketer"), alignment drifts locally around it — keep the `silencedetect` pass (2a) as a CROSS-CHECK, and treat disagreements > 0.3s as suspect regions to re-inspect. **On retake-heavy self-shot footage the drift is not local — it's cumulative and can reach seconds** (see the warning at the top and Step 2.5). And when the noise floor kills silencedetect too (low-dynamic-range guard), you have NO automatic cross-check — Step 2.5 is then mandatory, not optional.
-- **Drift smoke alarm — stretched words:** any short word whose MFA or whisper duration is ≳1s ("like" 1.16s, "there's" 1.5s, "of" 2.4s, "the" 4.9s on the 2026-07-02 run) is hiding a pause, a flub, or an ENTIRE collapsed retake inside it. Collect every stretched word up front; each one marks a region whose true content is unknown until re-windowed (Step 2.5). One stretched "the" turned out to contain a complete clean take of the whole sentence — the take that got kept.
-- **Fallback:** if MFA/conda is unavailable and the user doesn't want the install, fall back to whisper words + audio silencedetect (2a) — and say so in the plan summary. This is the ONLY path where whisper timestamps drive cuts.
-```
-
-## Step 2 — Build the cut list (AGGRESSIVE by default)
-
-Compute a list of (start, end) intervals to KEEP from the **MFA word intervals** (whisper JSON only as fallback). Aggressive cutting removes content in four categories:
-
-### 2a. Silence gaps — MFA empty intervals first, audio silencedetect as cross-check (updated 2026-06-10)
-With MFA (Step 1.5), true silences are the TextGrid's empty-label intervals — apply the gap table below to those directly. Cross-check with audio silence detection — **but CALIBRATE the threshold to the recording's own noise floor; never hard-code `-30dB`** (added 2026-06-16, burned on a DJI-mic to-camera take whose floor sat at ~-24dB: a fixed `-30dB` saw the ENTIRE take as non-silent, so every "silent" gap measured "above threshold = content, keep" and ~8s dead-air pauses survived the cut):
-
-# 1. Measure the noise floor F and speech level S from per-0.5s-window RMS
-
-#    (slice the wav into 0.5s windows, run volumedetect on each, collect mean_volume;
-
-#     F ≈ 10th-percentile window RMS  (room tone),  S ≈ 90th-percentile  (speech))
-
-# 2. Set the silence threshold RELATIVE to the floor, not absolute:
-THRESH=$(python3 -c "print(f'{F + 6:.0f}')")        # 6 dB above the measured floor
-ffmpeg -i proxy.mp4 -af silencedetect=noise=${THRESH}dB:d=0.14 -f null - 2>&1 | grep silence_
-```
-**⚠️ Low-dynamic-range guard (the real lesson, 2026-06-16):** if `S − F < ~8dB` (noisy mic — outdoor/DJI/lav with AC hum, where the per-second RMS reads the SAME during speech and silence), NO energy threshold can separate speech from silence. Do **not** trust silencedetect/volumedetect at all in that case — drive every cut from MFA word boundaries, or in the no-MFA fallback from **`small.en` word ONSETS + stretched-word pause detection** (a whisper word whose duration ≫ a normal word IS a hidden pause: keep ~`0.10 + 0.105·len(word)`s of onset, then cut to the next word's start). Say which path you used in the plan summary.
-
-Without MFA, the silencedetect pass is the trustworthy gap source ONLY when the dynamic-range guard passes: **`mlx_whisper`/whisper-turbo (and `tiny.en`) EMBED pauses inside word durations** — a 3s "word" is really "word [long pause]", inter-word *gaps* read ~0.00, and gap-based trimming does NOTHING. **Use `small.en` (not `tiny.en`) for the fallback path** — tiny stretches words across silence even worse and silently drops words ("bland", "slop") and whole retakes. Parse `silence_start`/`silence_end`, remove those intervals (keep ~0.04s pad; MFA-precision boundaries allow ~0.02s). For "almost no pauses" → `d=0.12`, pad 0.03. Combine with the dedup (2c/2d) by removing `silences ∪ dropped-word-ranges`. This is how you hit median ~1.1–1.3s.
-- **Stutters whisper hides:** turbo collapses spoken repetitions ("growth… growth marketer" → "growth marketer") and varies run-to-run (drops/re-adds words). These are invisible to transcript-based cutting — MFA alignment drift + silencedetect disagreement marks the region; re-inspect it, or ask the user for the timecode and cut a precise window.
-```
-
-### 2a-legacy. Silence gaps between words (TIGHT thresholds)
-
-| Gap | `aggressive` (default) | `balanced` | `sentimental` | `documentary` |
-|---|---|---|---|---|
-| `< 0.25s` | keep | keep | keep | keep |
-| `0.25–1s` | trim to **0.1s** | trim to 0.3s | trim to 0.5s | keep |
-| `1–3s` | trim to **0.2s** | trim to 0.8s | trim to 1.5s | trim to 2s |
-| `> 3s` | trim to **0.2s** | trim to 0.5s | trim to 1s | trim to 3s |
-
-The aggressive thresholds match the reference video's pacing (median cut 1.13s).
-
-### 2b. Filler words — cut with 50ms padding
-
-Always cut: `um`, `uh`, `umm`, `uhh`, `er`, `erm`, `ah`, `mhm`, `hmm` (standalone)
-
-### 2c. Hedges & weak transitions — cut aggressively in default mode
-
-Cut these when they're delivered as filler (not as substantive content). Mark for cut, then verify against context in the review step:
-
-- **Hedges:** `like` (as filler, not as comparison), `you know`, `I mean`, `I guess`, `I think` (when hedging, not asserting), `kind of`, `sort of`, `basically`, `literally`, `actually` (as filler)
-- **Weak transitions:** `so` (sentence-opener), `and so`, `and then`, `but um`, `but uh`, `okay so`, `right so`, `well`
-- **Redundant qualifiers:** `kind of like`, `sort of like`, `or whatever`, `or something`
-- **Re-orientation phrases:** `anyway`, `so anyway`, `the thing is`, `what I'm saying is`, `to be honest`, `honestly`
-
-In `balanced` / `sentimental` / `documentary` modes, only cut hedges that precede a re-statement (false start, see 2d). Keep them in conversational moments.
-
-### 2d. False starts and repetitions — cut aggressively
-
-Detect by scanning for:
-- **Self-corrections:** speaker re-states the same opening within ~3 seconds. Pattern: `"I want — I wanted to..."`, `"It's a — it's an interesting..."`. Drop the earlier attempt + the gap.
-- **Restart preambles:** `"so basically what I'm saying is..."`, `"the point is..."`, `"let me start over..."`. Drop the preamble, keep the actual point.
-- **Verbatim repetitions:** speaker says same 3+ words twice in a row. Keep the cleaner take.
-
-Implementation hint: build a sliding-window fuzzy-match on consecutive word n-grams. When 3-gram similarity > 0.8 within a 3-second window, flag the earlier instance for removal.
-
-### 2d-bis. FULL-LINE RETAKES (self-shot to-camera recordings, added 2026-06-10)
-Self-shot intros/promos contain **whole-sentence retakes** separated by 5–60s ("The next person is Carmen who works. … The next person, the next guest I invited is Carmen who's social and content lead at Slate") — far outside 2d's 3-second window. Detect and resolve them:
-- **Detection:** fuzzy n-gram match (4-grams, similarity > 0.7) across a **60-second window**; also match sentence OPENERS (first 3–5 words) since retakes usually restart the line.
-- **Keep the LAST take by default** — speakers re-record until satisfied. Exception: if the last take is incomplete/flubbed and an earlier one is clean, keep the clean one and note the override in the plan summary.
-- **A retake boundary is usually preceded by a long pause, a breath, a click, or a slate-phrase** ("okay", "again", "take two") — the pause+opener-match combo is the strongest signal.
-- **Surface every retake group in the Step 3 plan** (`line → takes at [t1, t2, t3] → keeping t3`) so the user can override which take survives.
-
-### 2e. NEVER cut these — protect explicitly
-
-- **Laughs.** Whisper transcribes laughter as silence. Before applying ANY silence cut, check audio amplitude:
-  ```
-Compare the window's RMS to the **measured noise floor F** (2a), NOT to a fixed dB: if window RMS > `F + ~10dB` it contains audible content (laugh, breath, reaction) — keep it. A hard-coded `-30dB`/`-25dB` cutoff fails on noisy mics whose floor already sits above it — it then "protects" pure room tone as if it were a laugh, which is exactly how dead air survives. Use `ffmpeg -i audio.wav -af "astats=metadata=1:reset=1,ametadata=print:key=lavfi.astats.Overall.RMS_level"` for per-window RMS. (And remember the low-dynamic-range guard in 2a: when `S − F < ~8dB`, RMS can't tell a laugh from room tone either — fall back to MFA/word-onset timing and surface anything ambiguous in the plan for the user to judge.)
-- **Comedic beats.** A deliberate pause after a punchline. In `aggressive` mode, still trim to 0.4–0.6s (don't kill it, just tighten).
-- **Reaction sounds.** Sighs, "ooh", "wow", gasps — all content.
-- **Single-word punchlines.** If a sentence ends with a one-word zinger after a beat, keep the beat.
-```
-
-### 2f. STRICTNESS PASS — zero tolerance for repetitions (Louise, 2026-06-10: "get rid of ANY repetitions")
-After building the keep list, run a machine scan — do NOT trust your eyes on the transcript:
-1. **Scan the MFA words that fall INSIDE kept ranges** for (a) consecutive duplicate words, (b) duplicate bigrams ACROSS segment boundaries (a flubbed restart can straddle a cut — "…meet her. And we're [flub] / And we're going to…" survived a snap once), (c) duplicate sentence-openers in adjacent sentences ("So… So…" → cut the second).
-2. **Cut hedge flubs** even mid-stat: "I believe", opener "Like", "I guess". Keep rhetorical repetition (parallel structure) — that's intentional.
-3. **When excising a word, cut to the FULL MFA word end (+0.01s)** — a 15ms vowel residue still reads as the word.
-4. **MFA OOV trap (burned 2026-06-10): acronyms/names missing from MFA's dictionary ("AI", brand names) silently VANISH from the alignment** — the word gets absorbed into its neighbor, and snapping a keep-end to "the last MFA word" then CLIPS the real spoken word. Guard: if whisper's chunk end exceeds the last MFA word end by >0.2s, trust the LATER of (whisper end, next silencedetect onset) for that boundary — and verify that junction with an isolated-segment transcription.
-5. **Verification trap: whisper-of-the-output LIES twice.** It (a) COLLAPSES surviving stutters (a real "and we're… and we're" transcribes once — looks clean, isn't), and (b) HALLUCINATES context words at cut junctions (a "girls"+"Enjoy" junction transcribes as "So enjoy" — looks dirty, isn't). So verify with BOTH: the kept-range MFA dup-scan (catches real stutters), and per-segment isolated transcription of any suspect junction (clears hallucinations). Only ship when the dup-scan returns NONE.
-6. **⭐ CROSS-ASR VERIFICATION — the strongest stutter detector (discovered 2026-06-10).** The MFA dup-scan only sees the words WHISPER transcribed — if whisper collapsed a phrase retake ("with the most recent video… with the most recent video" → once), MFA never knows it exists and the scan passes a dirty cut. The fix: **run the cut through a SECOND, independent ASR and diff.** Tella's transcript after upload is perfect for this (different model → different blind spots): it caught 5 repetitions in one pass that the whisper+MFA pipeline certified clean (a doubled phrase, a surviving "or, or", two mid-word fragments "pers-"/"per-", a doubled "into"). Workflow: upload the cut to Tella (or any second ASR) → scan ITS transcript for dup words/bigrams/phrases and mid-word fragments ("xyz-") → map hits back to source times → cut → re-verify. Disagreement between the two ASRs marks exactly the regions to fix or flag to the user.
-
-## Step 2.5 — GROUND-TRUTH every keep boundary with isolated windows (added 2026-07-02 — this step saved the whole run)
-
-MFA gives you the take STRUCTURE (what was said, roughly where). It does not reliably give you cut times on retake-heavy or noisy footage. Before rendering, re-transcribe **every region you plan to keep** in an isolated ±few-second window with `small.en` — within a short window whisper's word times are accurate, and it hears words the full pass dropped ("bland", "slop") and retakes the full pass collapsed ("It turns out— it turns out…").
-
-# windows: name:start:duration — start ≥0.5s BEFORE the expected onset
-for n in "r1:5.5:8.4" "r2:17.0:6.0" "r3:30.5:6.0"; do
-  f=${n%%:*}; rest=${n#*:}; o=${rest%%:*}; t=${rest##*:}
-  ffmpeg -y -hide_banner -loglevel error -ss $o -t $t -i audio.wav gt/$f.wav
-  whisper gt/$f.wav --model small.en --word_timestamps True --output_format json --output_dir gt --language en >/dev/null 2>&1
-  python3 -c "
-import json
-d=json.load(open('gt/$f.json'))
-print('=== $f (+$o) ===')
-for s in d['segments']:
-    for w in s.get('words',[]):
-        print(f\"{$o+w['start']:7.2f}-{$o+w['end']:7.2f} {w['word']}\")"
-done
-```
-(That loop is zsh-safe — don't use `set -- $var`, zsh doesn't word-split unquoted variables.)
-
-Rules for reading the windows:
-- **Window-edge words are stretched and untrustworthy.** A first word spanning from exactly the window start, or a last word ending at the window end, was clipped — its true onset/offset is outside the window. Re-window with the boundary moved ~1s outward before using that time.
-- **Stretched words INSIDE a window hide audio too** — `small.en` collapses within-window repeats just like the full pass ("to" spanning 93.1–97.9 contained an entire abandoned take). Re-window tighter around any word ≳1s. Sometimes what's inside is a **complete clean take** that neither full-pass ASR surfaced — check before assembling a splice from fragments.
-- **Two windows can disagree about the same words** (one caught a flub the other clipped). Resolve with a third window positioned so the disputed moment sits mid-window, away from both edges.
-- Final keep times: pad onset −0.03s, offset +0.04–0.08s (tight — stacked +0.10 pads across 20 keeps add 2s of mush).
-- **Trim pauses INSIDE kept takes too (added 2026-07-02 — "even less silences").** Removing retakes and inter-take gaps is not enough: fluent takes still carry mid-sentence beats ("…for a living, [0.3s] I want to know…") and they add up. Scan the ground-truth words within each keep for inter-word gaps > 0.2s and trim each to ~0.1s (cut `[gap_start+0.05, gap_end−0.05]`). Leave deliberate rhetorical beats ("median… or average") no shorter than ~0.15s.
-- **Stretched-word trap, keep-side (burned 2026-07-02):** a drawn-out spoken word looks identical to word+trailing-pause in the ASR ("slooop" transcribed as `slop 285.08–286.32`). Trimming what looks like the pause half CLIPS THE WORD mid-vowel. Before trimming into any stretched word at a keep boundary, re-window it tightly to find where the voice actually stops — and if the post-render verify transcript is missing a word that was there before, your trim ate it: push the boundary back out.
-
-Cost on a 5-min video: ~10–15 windows × a few seconds of `small.en` each ≈ 2 minutes. It is the difference between a clean cut and re-doing the whole back half.
-```
-
-## Step 3 — Show the plan, render immediately
-
-**Do NOT wait for approval — print the summary and start the render in the same turn** (changed 2026-07-09: the approval gate cost Louise a wasted wait when she didn't notice the question; the render is non-destructive and cheap to redo, so render-first is strictly better). Print this summary, then go straight to Step 4:
-
-```
-Original duration: 7m 25s
-Cleaned duration: 3m 58s
-Cut: 3m 27s (47%)
-Total keep intervals: 312
-Median cut duration: 1.2s (target: 1.1–1.5s)
-Hard cuts (dead air > 3s removed): 23
-Filler hits: 47
-Hedge/transition cuts: 89
-False-start drops: 12
-Notable preserved long pauses: list timestamps + context (laughs, punchlines)
-```
-```
-**Self-check vs benchmark:**
-- If median cut > 2s → not aggressive enough. Tighten gap thresholds or expand hedge list, retry.
-- If median cut < 0.7s → over-cut. Likely killing breath/cadence. Loosen 0.25–1s threshold to 0.3s.
-- Target compression: 40–60% in aggressive mode.
-- **Exception — retake-heavy footage (2026-07-02):** when most of the runtime is abandoned takes, the compression comes from dropping whole lines, not word-level slicing — median keep lands at 3–5s and compression at 65–75%, and that's CORRECT. Judge by compression % and final-script cleanliness instead; do NOT force extra mid-sentence cuts into fluent kept takes just to hit the 1.1–1.5s median (that target is for filler-dense monologue where nothing is re-recorded).
-
-Run the self-check yourself and fix violations before rendering — that's the quality gate now, not the user. Then render immediately. The user reviews the *result*; if a cut killed a laugh or an intentional pause, adjust the keep list and re-render (fast — trim/concat, not re-transcription).
-```
-
-## Step 3.5 — Manual timeline editor (OPTIONAL — only when Louise asks for it)
-
-(Demoted from always-on 2026-07-02: Louise found the editor fiddly in practice and prefers the pipeline to just cut tighter automatically — the intra-take pause trimming in Step 2.5 came out of that. Generate the editor only if she asks to review/adjust by hand.)
-
-A timeline editor so she can trim silences and drop anything she doesn't want, before (or after) the render:
-
-# keeps.json must be [start, end, "transcript text"] triplets in the working dir;
-
-# needs proxy.mp4 (and ideally audio.wav) in the same dir. Generates wave.png once.
-python3 ~/.claude/skills/cut-video/make_review.py /tmp/cut-video/$NAME
-open /tmp/cut-video/$NAME/review.html
-```
-What the page gives her (self-contained HTML next to `proxy.mp4`, no server needed — waveform peaks and silence suggestions are embedded in the file, so it works on `file://`):
-- **Canvas waveform timeline of the FULL source**, crisp at every zoom. **Pinch or ctrl/⌘+wheel zooms centered on the cursor** (continuous, fit → 400px/s); mouse wheel pans; +/−/Fit buttons too. Click to scrub; playhead synced to the video.
-- **Drag ACROSS the waveform to delete that range** — the primary silence-removal gesture: see a flat stretch, swipe it, gone. Works across block boundaries (trims/splits/removes whatever it covers).
-- **Amber hatched bands = auto-suggested silences inside keep blocks** (peak-based, adaptive threshold — computed by the generator and embedded). Click a band to cut it (leaves 0.1s of pause at each side), or **"✂ Cut all"** with a min-duration slider to sweep every suggestion at once. On noisy mics the suggestions degrade — they're visual candidates, she judges.
-- **Drag a block's edges** to trim; the video seeks live while dragging so she hears the cut point. Selected edge nudges ±0.05s (buttons or ←/→, shift = 0.25s).
-- **Split at playhead** (`S`), **drop/restore** a block (`D`/⌫ or click its card), **double-click a gap** to resurrect cut footage, **undo** (`Z`, 60 levels).
-- Card list below with per-segment ▶ and transcript text; **"Preview final cut"** plays kept blocks back-to-back, skipping cuts — the render, live, without rendering.
-- **"Copy decisions for Claude"** copies `{"keeps": [[a,b], ...]}` — the full edited keep list in source-proxy seconds.
-
-Applying her decisions: the pasted `keeps` array REPLACES the old keep list — carry transcript text over by time-overlap with the previous `keeps.json` (blocks she created from gaps have no text; label them "(restored)"), rebuild `filter.txt`, re-render. The proxy is already there, so a revision costs seconds.
-
-Boundary hygiene: her hand-dragged edges are intentional — do NOT re-snap them to MFA/ASR word boundaries. Only warn if an edge lands mid-word per the ground-truth words (say which word and offer the nearest clean boundary).
-```
-
-## Step 4 — Render with `trim` + `concat`, NOT `select`
-
-**Critical:** Use the trim+concat filtergraph pattern, NOT `select`/`aselect`. The select filter compresses video frames but does NOT properly compress audio PTS, leaving audio and video misaligned.
-
-Build a filtergraph with one trim+atrim pair per keep interval, then concat them:
-
-```
-[0:v]trim=A1:B1,setpts=PTS-STARTPTS[v0];
-[0:a]atrim=A1:B1,asetpts=PTS-STARTPTS[a0];
-[0:v]trim=A2:B2,setpts=PTS-STARTPTS[v1];
-[0:a]atrim=A2:B2,asetpts=PTS-STARTPTS[a1];
-...
-[v0][a0][v1][a1]...concat=n=N:v=1:a=1[outv][outa]
-```
-```
-Write the filtergraph to a file (it'll get long — aggressive cuts mean 200–400 intervals on a 7-min source) and use `-filter_complex_script`. Render call:
-```
-```bash
--filter_complex_script /tmp/cut-video/$NAME/filter.txt \
-  -map "[outv]" -map "[outa]" \
-  -c:v libx264 -preset fast -crf 20 -pix_fmt yuv420p \
-  -c:a aac -b:a 192k \
-  /tmp/cut-video/$NAME/cleaned.mp4
-```
-```
-**Faster alternative for many cuts:** if filtergraph exceeds ~500 trims, switch to per-segment extract + lossless concat:
-1. Extract each keep interval as a separate stream-copied chunk
-2. Build a concat demuxer file
-3. `ffmpeg -f concat -safe 0 -i concat.txt -c copy cleaned.mp4`
-
-This avoids re-encoding entirely on the trim pass.
-```
-
-## Step 5 — Deliver
-
-- Save final to `<source_dir>/cut_out/<source_name>_cut.mp4` (mkdir if missing)
-- Print one line: original duration → cleaned duration, percent cut, median cut, output path
-- `open` the file so the user can review immediately
-- Revisions are cheap: the proxy + ground-truthed times stay in the working dir, so "drop the second segment" / "tighten X" is a seconds-fast re-render. (If she asked for the Step 3.5 editor, remind her it's still live for pasting decisions back.)
-- Offer to iterate: re-tune gap thresholds, switch tone preset, mark specific moments to preserve/cut
-
----
-
-## Pitfalls — don't repeat these (learned from prior runs)
-
-- **Don't skip `-hwaccel videotoolbox`** on the proxy step. HEVC software decode on a 7-min 4K source can take 5+ minutes. With the flag, ~30s.
-- **Don't use the `select` filter for cuts.** It misaligns audio. Use trim+concat.
-- **Don't use `-preset medium` (the libx264 default).** It's ~3× slower than `-preset fast` for no quality gain on a working copy.
-- **Don't wait for approval before rendering** (changed 2026-07-09 — the gate wasted more time than it saved). Print the plan, render immediately. The old worry (a "silent" gap holding a laugh, a "filler" that's intentional emphasis) is handled by the amplitude check below + preserved-pauses list in the summary — and a bad cut just means a quick re-render.
-- **Don't trim a long "silence" without checking amplitude** — that's usually laughter, a thinking pause, or a setup-payoff beat.
-- **Don't `whisper` the entire raw source if a proxy exists.** Run whisper against `audio.wav` extracted from the proxy.
-- **Don't re-encode audio twice.** If you only changed video, use `-c:a copy` to skip an unnecessary AAC pass.
-- **Don't be timid.** Default to `aggressive`. The reference cut style is fast — if the output feels "safe", it's not matching Louise's CapCut pacing.
-- **Don't render from MFA times alone on retake-heavy or noisy footage.** Measured 1–6s drift on the 2026-07-02 DJI run. Ground-truth every keep boundary with isolated windows (Step 2.5) first.
-- **Don't scale a portrait source to 1920:1080.** Probe orientation first; DJI/phone footage is usually 9:16.
-- **Don't trust window-edge word times** from an isolated transcription — a word touching the window boundary is clipped/stretched; re-window before using it as a cut point.
-- **`h264_videotoolbox -b:v 8M` is fine for the final render too**, not just the proxy — the whole 4K-HEVC→proxy→18-segment render finished in ~1 min total on M-series.
-
-## Benchmark reference
-
-`AI mogging my dad.mp4` (2026-05-03, CapCut project `0501`):
-- 335 cuts in 460s = 1 cut / 1.37s
-- Median 1.13s, mean 1.37s
-- 41% of cuts < 1s, 12% < 0.5s
-- Only 3 cuts > 5s
-- Raw source compressed ~60%
-
-Use this as ground-truth for "aggressive" mode tuning.
-
-## What this skill explicitly does NOT do
-
-- Add zooms, layouts, or motion graphics (separate concern — handled in CapCut or via [[tella-edit]])
-- Add memes or b-roll (user-curated, see [[clipify]] for short-form cuts)
-- Burn captions (separate pass after cleanup)
-- Upload anywhere
-
-Keep this skill focused on one thing: produce a tighter MP4 from a long-form recording, fast and aggressive.
-
-## Source
-
-Rewritten for AICUT from [`louisedesadeleer/cut-video`](https://github.com/louisedesadeleer/cut-video)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/cyxj-hyperframes-overlay/SKILL.md

@@ -1,75 +0,0 @@
----
-name: cyxj-hyperframes-overlay
-description: "XCYJ AICUT 专属 overlay。用户用 AICUT、HF、HTML+GSAP、website-to-video、catalog block、npx hyperframes、XCYJ 教程视频时使用。必须叠加官方 AICUT skills，不替代官方 skill。 Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "chenyuxiaojin/cyxj-hyperframes"
----
-
-# cyxj-AICUT-overlay
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-这是 XCYJ 的 HyperFrames 私有规则层。先按官方 HyperFrames skill（入口 `hyperframes`，按路由到 core / animation / creative / cli / registry / media）做正确实现，再套 XCYJ 视觉和生产纪律。
-
-## 必读顺序
-
-1. 官方 HyperFrames skill（GitHub 直连，16 个，`npx skills` 管理）：入口 `hyperframes`（READ FIRST，会路由到具体 workflow）→ 按任务加载 `hyperframes-core`（HTML 结构契约）、`hyperframes-animation`（动画 / GSAP / 七适配器 / 镜头蓝图）、`hyperframes-creative`（设计 / 排版 / 节奏 / 旁白）、`hyperframes-cli`（dev loop）、`hyperframes-registry`（catalog 零件）、`hyperframes-media`（TTS / 转写 / 抠像）；成片配方按需用 `website-to-video` / `motion-graphics` / `embedded-captions` / `graphic-overlays` 等。
-2. `../../notes/MY_VISUAL_DNA.md`
-3. `../../notes/MY_MOTION_NOTES.md`
-4. `../../rules/hyperframes/hyperframes-rules.md`
-5. `../../rules/hyperframes/effects-catalog.md`
-
-## 资产和模板（路径从仓库根 `hyperframes/` 起）
-
-```text
-资源库/logos/                         # 33 个 AI 厂商 / 工具 SVG（产品引用用真 logo）
-组件库/COMPONENTS.json  # ⭐ 组件注册表（可复用零件单源 = Remotion 镜头库，写前必查）
-组件库/README.md        # 组件库人读索引 + 登记仪式
-参考/catalog.json                # 官方 HeyGen catalog 零件（另一套，勿混）
-
-# 当前无内置起步模板：起新片从空白起步（npx hyperframes init --example blank）
-```
-复用零件先查 `组件库/COMPONENTS.json`，写前按 [BLOCKING-REUSE] 4 处扫描（本工程 / 注册表 / 历史 `视频项目/已发布/` / 官方 catalog）。组件**单一真源在 `组件库/`**（`cyxj/templates/` 为待废弃镜像，勿在那边加）。使用模板后，把需要长期渲染的素材复制到具体工程自己的 `assets/`。
-```
-
-## 关键纪律
-
-- 不在顶层 `视频制作台/` 跑 CLI。
-- 不手改官方 skill。
-- 写 composition 前做复用扫描。
-- Remotion 代码不进入 HyperFrames 工程。
-
-## Source
-
-Rewritten for AICUT from [`chenyuxiaojin/cyxj-hyperframes`](https://github.com/chenyuxiaojin/cyxj-hyperframes)
-(MIT), 制作规范/skills/cyxj-hyperframes-overlay/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/cyxj-remotion-evolve/SKILL.md

@@ -1,123 +0,0 @@
----
-name: cyxj-remotion-evolve
-description: "AICUT 文档进化引擎。把一次制作 / 对话里学到的东西(纠正、新决策、新手法、被推翻的旧规则、过时描述)路由到正确的真源文件并回写,保持路由链单一真源、指针不断、不重复。用户说\"进化 / 更新文档 / 把这次学到的写进规则 / 回写规则 / 文档该改了\"时使用。这不是复盘 QA,是让规则越长越准、视频越做越好的活文档机制。 Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "chenyuxiaojin/cyxj-remotion-starter"
----
-
-# cyxj-remotion-evolve(文档进化引擎)
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-Remotion 工作台的"活文档"机制。目标:**规则文档每次都跟着进化,不靠人记得改。** 学到一条东西 → 路由到正确的真源文件 → 回写 → 保持整条路由链一致。
-
-> ⚠️ 这不是复盘 / QA(那是查"做对没做对")。这是**进化**:把"学到的"沉淀成"下次的起点",让视频越做越好。
-> ⚠️ 也不替代官方核查或硬规则——它只负责"把规则本身改对、改全、放对地方"。
-
-## 什么时候触发
-
-- **手动**:用户说"进化 / 更新文档 / 回写规则 / 把这次学到的写进规则"。
-- **自动**:收工"文档进化闸"hook(`.claude/hooks/evolve-on-stop.mjs`,Stop 时机;搭档 `record-evolve-touch.mjs` 记本轮改动)检测到本轮动过镜头/出片代码而规则文档未动 → 拦一次提醒跑本 skill,再次收工放行。
-- **主动**:对话里出现"纠正 / 新决策 / 新手法 / 旧规则被推翻"时,主动提议跑一次。
-
-## 铁律(先记住,再动手)
-
-1. **绝不静默改文档。** 一律先出 diff 提案、按文件分组、说清"为什么写这个文件"、**用户批准才写**。规则文档是你的宪法。
-2. **单一真源。** 每条事实只在一个真源里写全,别处只放指针。**禁止把同一条规则复制进多个文件**——发现重复要合并、留指针。
-3. **CLAUDE.md 是路由器,不是仓库。** 具体规则进对应真源文件,CLAUDE.md 只留一行指过去;不要把内容堆进 CLAUDE.md 正文。
-4. **改视觉值走单一真源。** 视觉【值】(色 / 字号 / 动效 token)改 `kit/theme.ts`(或你为它建的生成器),别在组件里到处内联硬编码色值。
-5. **移动规则要补指针。** 一条规则从 A 文件挪到 B 文件,必须同步改掉所有指向它的路由行,别留断链。
-
-## 执行分工(防上下文污染)
-
-**主对话只做两件事**:① 采集信号(从本会话对话/diff 里捞,压缩成一段简报——只有主对话知道这轮发生了什么);② 按铁律 1 向用户出提案、拿批准。
-**批准后派子代理执行**(general-purpose,把简报 + 下方路由表 + 目标文件路径喂给它):读真源 → 一致性查重(四步之3)→ 回写 → 记沿革 → 返回 diff 摘要,主对话转达即可。
-**为什么**:路由/查重要读大量真源文件,全在主对话做会吃掉主上下文;子代理烧自己的窗口,主对话只留结论。
-**边界**:批准环节不许下放——子代理不能与用户对话,「用户批准才写」必须发生在主对话;子代理只执行已批准的内容,超出提案范围的发现带回主对话再议。
-
-## 路由链地图(锚点 = 仓库根)
-
-```
-CLAUDE.md                根路由 + 三层真源索引
-kit/CLAUDE.md            共享层(kit)索引 + 组件晋升规则
-template/CLAUDE.md       出片层(各工程自己的禁区)
-docs/HARD_RULES.md       工程红线唯一真源(frame 驱动 / clamp / 确定性 / public…)
-```
-
-## 进化四步
-
-### 1. 采集(找进化信号)
-从本会话对话 + `git diff` / `git log`(动过的工程)里捞:
-- **纠正**:用户说过"不对 / 我没说过 / 应该是 X / 你理解错了"。
-- **新决策**:定了新做法 / 新默认 / 新边界。
-- **新手法 / 新能力**:造出了好用且会跨片重复的手法,或验证了某引擎用法(3D / anime / 原生武器…)。
-- **旧规则被推翻 / 过时描述**:文档说 X,现实或代码是 Y。
-- **创造 vs 复用事件**:这次是真创造,还是又反射式复用了?(给"创作姿态闸"攒账)
-
-### 2. 分类 + 路由(查路由表)
-每条信号落到唯一真源:
-
-| 学到什么 | 写进哪个真源(锚点 = 仓库根) | CLAUDE.md |
-|---|---|---|
-| 操作纪律 / 流程 | 对应层 `CLAUDE.md` 正文(根 / kit / 出片层) | 它本身就是 |
-| 踩坑 / 框架红线 / 战疤 | `docs/HARD_RULES.md` | 留指针 |
-| 视觉【值】(色 / 字号 / 动效 token) | `kit/theme.ts`(或你建的生成器) | — |
-| 视觉意图 / 构图 / 色彩语义 | 你自己的设计说明书(本仓不含,建议自建) | 留指针 |
-| 动效手法 / 节奏 / spring 手感 | 你自己的动效笔记(本仓不含,建议自建) | 留指针 |
-| 引擎能力 / 用法(3D·anime·原生武器) | 你自己的引擎笔记(本仓不含,建议自建) | 留指针 |
-| **创作姿态(创造 vs 复用判断)** | `.claude/skills/cyxj-remotion-overlay/SKILL.md` | — |
-
-> 判不准放哪 → 问用户,别硬塞。一条信号可能要落两处(真源写全 + 上层留指针),但**内容只在真源那一份**。
->
-> 作者的完整真源体系还有设计说明书 / 动效笔记 / 引擎能力手册 / 字幕与后期 SOP / 沿革档案等多份文件(私有沉淀,**本仓不含**)。上表把它们标成"建议自建"——按同样的"单一真源 + 留指针"机制沉淀你自己的。
-
-### 3. 一致性检查(写之前必做)
-- 目标真源里**有没有已经写过的相近条目**?有 → 合并 / 改写,不新增重复。
-- 这条规则原来在别的文件吗?是 → 这是"移动":删旧处 + 改所有指向它的指针。
-- 写完后路由链**还连得上吗**?(CLAUDE.md 里的指针指向的文件 / 小节真实存在)
-
-### 4. 提案 → 批准 → 写
-- 按文件分组出 diff 提案,每组配一句"为什么是这个文件"。
-- 用户批准后才写入。
-
-## 跑完自检
-- [ ] 有没有把内容堆进了 CLAUDE.md 正文(本该进真源 + 留指针)?
-- [ ] 有没有制造重复(同一条话两个文件都写全)?
-- [ ] 有没有在组件里内联硬编码色值(本该改 `kit/theme.ts`)?
-
-## Source
-
-Rewritten for AICUT from [`chenyuxiaojin/cyxj-remotion-starter`](https://github.com/chenyuxiaojin/cyxj-remotion-starter)
-(MIT), .claude/skills/cyxj-remotion-evolve/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
-
-The repository holds 3 skills; this is the one its entry stands for.