Skip to content
Back to search

cut-video

SkillWorks with Claude CodeGitHub

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".

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/louisedesadeleer--cut-video/badge.svg)](/listings/louisedesadeleer--cut-video)

HTML

<a href="/listings/louisedesadeleer--cut-video"><img src="/api/listings/louisedesadeleer--cut-video/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/louisedesadeleer/cut-video.git ~/.claude/skills/cut-video

Restart Claude Code and `/cut-video` is available as a slash command.

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 · 354 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: cut-video
  3. 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".
  4. ---
  5. # Cut Video
  6. 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.
  7. > **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.
  8. > **⚠️ 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.
  9. **Style target** (calibrated from `AI mogging my dad.mp4`):
  10. - ~1 cut every 1.3–1.5 seconds (median cut duration ~1.1s)
  11. - ~40–60% total runtime reduction from raw
  12. - Cuts happen mid-sentence, not just between sentences
  13. - Word-by-word tightening — fillers, hedges, and weak openers get sliced
  14. ## Inputs
  15. - Video file path (the user will provide; otherwise ask)
  16. - Optional: tone preference (`aggressive` / `balanced` / `sentimental` / `documentary`) — default: `aggressive`
  17. ## Working directory
  18. `/tmp/cut-video/<basename>/` — mkdir at start, leave artifacts for debugging.
  19. ---
  20. ## Step 0 — Make a proxy (the single biggest speed move)
  21. 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.
  22. **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`).
  23. ```bash
  24. ffmpeg -y -hwaccel videotoolbox -i "$SRC" \
  25. -vf scale=1920:1080 \ # portrait sources: scale=1080:1920
  26. -c:v libx264 -preset fast -crf 20 -pix_fmt yuv420p \
  27. -c:a aac -b:a 192k \
  28. /tmp/cut-video/$NAME/proxy.mp4
  29. ```
  30. **Critical flags:**
  31. - `-hwaccel videotoolbox` on the INPUT — hardware-decodes HEVC, ~5–10× faster on Apple Silicon. Skip this and you'll wait minutes instead of seconds.
  32. - `-preset fast` — the libx264 default is `medium`, which is ~3× slower for no useful quality gain on a working copy.
  33. Hardware encode alternative (even faster on M-series, slightly larger file):
  34. ```bash
  35. -c:v h264_videotoolbox -b:v 8M
  36. ```
  37. ## Step 1 — Get the transcript TEXT (whisper, as input for MFA)
  38. 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.
  39. ```bash
  40. ffmpeg -y -hwaccel videotoolbox -i /tmp/cut-video/$NAME/proxy.mp4 \
  41. -vn -ac 1 -ar 16000 /tmp/cut-video/$NAME/audio.wav
  42. whisper /tmp/cut-video/$NAME/audio.wav \
  43. --model tiny.en --word_timestamps True --output_format json \
  44. --output_dir /tmp/cut-video/$NAME --language en
  45. ```
  46. **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.
  47. ## Step 1.5 — Align the transcript to the audio with MFA (Montreal Forced Aligner) — the timing engine
  48. 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.**
  49. **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.
  50. ```bash
  51. # 1. Ensure conda exists (MFA's only supported install path). Install miniforge via brew if missing.
  52. if ! command -v conda >/dev/null 2>&1; then
  53. echo "conda not found — installing miniforge (one-time)…"
  54. brew install --cask miniforge || brew install miniforge
  55. # make conda available in this shell
  56. eval "$("$(brew --prefix)/bin/conda" shell.bash hook 2>/dev/null || conda shell.bash hook)"
  57. fi
  58. source "$(conda info --base)/etc/profile.d/conda.sh"
  59. # 2. Ensure the mfa env exists with MFA installed
  60. if ! conda env list | grep -q '^mfa\b'; then
  61. echo "creating mfa conda env (one-time)…"
  62. conda create -n mfa -c conda-forge montreal-forced-aligner -y
  63. fi
  64. # 3. Ensure the English acoustic model + dictionary are downloaded (idempotent; skips if present)
  65. conda run -n mfa mfa model download acoustic english_mfa 2>/dev/null || true
  66. conda run -n mfa mfa model download dictionary english_mfa 2>/dev/null || true
  67. ```
  68. 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.
  69. **Per run:**
  70. ```bash
  71. # corpus = a dir with audio.wav + audio.txt (the whisper transcript as PLAIN TEXT, no timestamps)
  72. mkdir -p /tmp/cut-video/$NAME/corpus
  73. cp /tmp/cut-video/$NAME/audio.wav /tmp/cut-video/$NAME/corpus/
  74. 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'])"
  75. conda run -n mfa mfa align --clean /tmp/cut-video/$NAME/corpus english_mfa english_mfa /tmp/cut-video/$NAME/aligned
  76. # → aligned/audio.TextGrid — "words" tier: (start, end, word); EMPTY-label intervals = true silences
  77. ```
  78. Parse the TextGrid `words` tier (pip `praatio`, or a 20-line parser — interval tiers are plain text). What MFA buys:
  79. - **True word boundaries** → cut pads shrink to ~0.02s, no clipped word onsets/tails.
  80. - **True silences are explicit empty intervals** → the 2a gap table works directly off the TextGrid; the whisper embedded-pause problem disappears.
  81. - **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.
  82. - **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.
  83. - **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.
  84. ## Step 2 — Build the cut list (AGGRESSIVE by default)
  85. 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:
  86. ### 2a. Silence gaps — MFA empty intervals first, audio silencedetect as cross-check (updated 2026-06-10)
  87. 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):
  88. ```bash
  89. # 1. Measure the noise floor F and speech level S from per-0.5s-window RMS
  90. # (slice the wav into 0.5s windows, run volumedetect on each, collect mean_volume;
  91. # F ≈ 10th-percentile window RMS (room tone), S ≈ 90th-percentile (speech))
  92. # 2. Set the silence threshold RELATIVE to the floor, not absolute:
  93. THRESH=$(python3 -c "print(f'{F + 6:.0f}')") # 6 dB above the measured floor
  94. ffmpeg -i proxy.mp4 -af silencedetect=noise=${THRESH}dB:d=0.14 -f null - 2>&1 | grep silence_
  95. ```
  96. **⚠️ 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.
  97. 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.
  98. - **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.
  99. ### 2a-legacy. Silence gaps between words (TIGHT thresholds)
  100. | Gap | `aggressive` (default) | `balanced` | `sentimental` | `documentary` |
  101. |---|---|---|---|---|
  102. | `< 0.25s` | keep | keep | keep | keep |
  103. | `0.25–1s` | trim to **0.1s** | trim to 0.3s | trim to 0.5s | keep |
  104. | `1–3s` | trim to **0.2s** | trim to 0.8s | trim to 1.5s | trim to 2s |
  105. | `> 3s` | trim to **0.2s** | trim to 0.5s | trim to 1s | trim to 3s |
  106. The aggressive thresholds match the reference video's pacing (median cut 1.13s).
  107. ### 2b. Filler words — cut with 50ms padding
  108. Always cut: `um`, `uh`, `umm`, `uhh`, `er`, `erm`, `ah`, `mhm`, `hmm` (standalone)
  109. ### 2c. Hedges & weak transitions — cut aggressively in default mode
  110. Cut these when they're delivered as filler (not as substantive content). Mark for cut, then verify against context in the review step:
  111. - **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)
  112. - **Weak transitions:** `so` (sentence-opener), `and so`, `and then`, `but um`, `but uh`, `okay so`, `right so`, `well`
  113. - **Redundant qualifiers:** `kind of like`, `sort of like`, `or whatever`, `or something`
  114. - **Re-orientation phrases:** `anyway`, `so anyway`, `the thing is`, `what I'm saying is`, `to be honest`, `honestly`
  115. In `balanced` / `sentimental` / `documentary` modes, only cut hedges that precede a re-statement (false start, see 2d). Keep them in conversational moments.
  116. ### 2d. False starts and repetitions — cut aggressively
  117. Detect by scanning for:
  118. - **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.
  119. - **Restart preambles:** `"so basically what I'm saying is..."`, `"the point is..."`, `"let me start over..."`. Drop the preamble, keep the actual point.
  120. - **Verbatim repetitions:** speaker says same 3+ words twice in a row. Keep the cleaner take.
  121. 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.
  122. ### 2d-bis. FULL-LINE RETAKES (self-shot to-camera recordings, added 2026-06-10)
  123. 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:
  124. - **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.
  125. - **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.
  126. - **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.
  127. - **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.
  128. ### 2e. NEVER cut these — protect explicitly
  129. - **Laughs.** Whisper transcribes laughter as silence. Before applying ANY silence cut, check audio amplitude:
  130. ```bash
  131. ffmpeg -i audio.wav -af "volumedetect" -f null - 2>&1 | grep mean_volume
  132. ```
  133. 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.)
  134. - **Comedic beats.** A deliberate pause after a punchline. In `aggressive` mode, still trim to 0.4–0.6s (don't kill it, just tighten).
  135. - **Reaction sounds.** Sighs, "ooh", "wow", gasps — all content.
  136. - **Single-word punchlines.** If a sentence ends with a one-word zinger after a beat, keep the beat.
  137. ### 2f. STRICTNESS PASS — zero tolerance for repetitions (Louise, 2026-06-10: "get rid of ANY repetitions")
  138. After building the keep list, run a machine scan — do NOT trust your eyes on the transcript:
  139. 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).
  140. 2. **Cut hedge flubs** even mid-stat: "I believe", opener "Like", "I guess". Keep rhetorical repetition (parallel structure) — that's intentional.
  141. 3. **When excising a word, cut to the FULL MFA word end (+0.01s)** — a 15ms vowel residue still reads as the word.
  142. 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.
  143. 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.
  144. 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.
  145. ## Step 2.5 — GROUND-TRUTH every keep boundary with isolated windows (added 2026-07-02 — this step saved the whole run)
  146. 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…").
  147. ```bash
  148. # windows: name:start:duration — start ≥0.5s BEFORE the expected onset
  149. for n in "r1:5.5:8.4" "r2:17.0:6.0" "r3:30.5:6.0"; do
  150. f=${n%%:*}; rest=${n#*:}; o=${rest%%:*}; t=${rest##*:}
  151. ffmpeg -y -hide_banner -loglevel error -ss $o -t $t -i audio.wav gt/$f.wav
  152. whisper gt/$f.wav --model small.en --word_timestamps True --output_format json --output_dir gt --language en >/dev/null 2>&1
  153. python3 -c "
  154. import json
  155. d=json.load(open('gt/$f.json'))
  156. print('=== $f (+$o) ===')
  157. for s in d['segments']:
  158. for w in s.get('words',[]):
  159. print(f\"{$o+w['start']:7.2f}-{$o+w['end']:7.2f} {w['word']}\")"
  160. done
  161. ```
  162. (That loop is zsh-safe — don't use `set -- $var`, zsh doesn't word-split unquoted variables.)
  163. Rules for reading the windows:
  164. - **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.
  165. - **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.
  166. - **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.
  167. - Final keep times: pad onset −0.03s, offset +0.04–0.08s (tight — stacked +0.10 pads across 20 keeps add 2s of mush).
  168. - **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.
  169. - **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.
  170. 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.
  171. ## Step 3 — Show the plan, render immediately
  172. **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:
  173. ```
  174. Original duration: 7m 25s
  175. Cleaned duration: 3m 58s
  176. Cut: 3m 27s (47%)
  177. Total keep intervals: 312
  178. Median cut duration: 1.2s (target: 1.1–1.5s)
  179. Hard cuts (dead air > 3s removed): 23
  180. Filler hits: 47
  181. Hedge/transition cuts: 89
  182. False-start drops: 12
  183. Notable preserved long pauses: list timestamps + context (laughs, punchlines)
  184. ```
  185. **Self-check vs benchmark:**
  186. - If median cut > 2s → not aggressive enough. Tighten gap thresholds or expand hedge list, retry.
  187. - If median cut < 0.7s → over-cut. Likely killing breath/cadence. Loosen 0.25–1s threshold to 0.3s.
  188. - Target compression: 40–60% in aggressive mode.
  189. - **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).
  190. 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).
  191. ## Step 3.5 — Manual timeline editor (OPTIONAL — only when Louise asks for it)
  192. (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.)
  193. A timeline editor so she can trim silences and drop anything she doesn't want, before (or after) the render:
  194. ```bash
  195. # keeps.json must be [start, end, "transcript text"] triplets in the working dir;
  196. # needs proxy.mp4 (and ideally audio.wav) in the same dir. Generates wave.png once.
  197. python3 ~/.claude/skills/cut-video/make_review.py /tmp/cut-video/$NAME
  198. open /tmp/cut-video/$NAME/review.html
  199. ```
  200. 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://`):
  201. - **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.
  202. - **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).
  203. - **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.
  204. - **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).
  205. - **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).
  206. - 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.
  207. - **"Copy decisions for Claude"** copies `{"keeps": [[a,b], ...]}` — the full edited keep list in source-proxy seconds.
  208. 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.
  209. 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).
  210. ## Step 4 — Render with `trim` + `concat`, NOT `select`
  211. **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.
  212. Build a filtergraph with one trim+atrim pair per keep interval, then concat them:
  213. ```
  214. [0:v]trim=A1:B1,setpts=PTS-STARTPTS[v0];
  215. [0:a]atrim=A1:B1,asetpts=PTS-STARTPTS[a0];
  216. [0:v]trim=A2:B2,setpts=PTS-STARTPTS[v1];
  217. [0:a]atrim=A2:B2,asetpts=PTS-STARTPTS[a1];
  218. ...
  219. [v0][a0][v1][a1]...concat=n=N:v=1:a=1[outv][outa]
  220. ```
  221. 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:
  222. ```bash
  223. ffmpeg -y -hwaccel videotoolbox -i /tmp/cut-video/$NAME/proxy.mp4 \
  224. -filter_complex_script /tmp/cut-video/$NAME/filter.txt \
  225. -map "[outv]" -map "[outa]" \
  226. -c:v libx264 -preset fast -crf 20 -pix_fmt yuv420p \
  227. -c:a aac -b:a 192k \
  228. /tmp/cut-video/$NAME/cleaned.mp4
  229. ```
  230. **Faster alternative for many cuts:** if filtergraph exceeds ~500 trims, switch to per-segment extract + lossless concat:
  231. 1. Extract each keep interval as a separate stream-copied chunk
  232. 2. Build a concat demuxer file
  233. 3. `ffmpeg -f concat -safe 0 -i concat.txt -c copy cleaned.mp4`
  234. This avoids re-encoding entirely on the trim pass.
  235. ## Step 5 — Deliver
  236. - Save final to `<source_dir>/cut_out/<source_name>_cut.mp4` (mkdir if missing)
  237. - Print one line: original duration → cleaned duration, percent cut, median cut, output path
  238. - `open` the file so the user can review immediately
  239. - 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.)
  240. - Offer to iterate: re-tune gap thresholds, switch tone preset, mark specific moments to preserve/cut
  241. ---
  242. ## Pitfalls — don't repeat these (learned from prior runs)
  243. - **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.
  244. - **Don't use the `select` filter for cuts.** It misaligns audio. Use trim+concat.
  245. - **Don't use `-preset medium` (the libx264 default).** It's ~3× slower than `-preset fast` for no quality gain on a working copy.
  246. - **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.
  247. - **Don't trim a long "silence" without checking amplitude** — that's usually laughter, a thinking pause, or a setup-payoff beat.
  248. - **Don't `whisper` the entire raw source if a proxy exists.** Run whisper against `audio.wav` extracted from the proxy.
  249. - **Don't re-encode audio twice.** If you only changed video, use `-c:a copy` to skip an unnecessary AAC pass.
  250. - **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.
  251. - **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.
  252. - **Don't scale a portrait source to 1920:1080.** Probe orientation first; DJI/phone footage is usually 9:16.
  253. - **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.
  254. - **`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.
  255. ## Benchmark reference
  256. `AI mogging my dad.mp4` (2026-05-03, CapCut project `0501`):
  257. - 335 cuts in 460s = 1 cut / 1.37s
  258. - Median 1.13s, mean 1.37s
  259. - 41% of cuts < 1s, 12% < 0.5s
  260. - Only 3 cuts > 5s
  261. - Raw source compressed ~60%
  262. Use this as ground-truth for "aggressive" mode tuning.
  263. ## What this skill explicitly does NOT do
  264. - Add zooms, layouts, or motion graphics (separate concern — handled in CapCut or via [[tella-edit]])
  265. - Add memes or b-roll (user-curated, see [[clipify]] for short-form cuts)
  266. - Burn captions (separate pass after cleanup)
  267. - Upload anywhere
  268. Keep this skill focused on one thing: produce a tighter MP4 from a long-form recording, fast and aggressive.
README.md · README · 78 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Cut Video
  2. A [Claude Code](https://claude.com/claude-code) skill that tightens long-form recordings — removes silences, ums, fillers, and dead air **while preserving laughs and comedic pauses**.
  3. **More accurate than cutting from Whisper alone.** Cuts are driven by [Montreal Forced Aligner](https://montreal-forced-aligner.readthedocs.io/) (MFA) word boundaries (~10–20ms precision, with true inter-word silences as explicit intervals) rather than Whisper timestamps (±100–300ms, with pauses embedded inside word durations). Whisper is used only to produce the transcript *text*; MFA aligns it to the audio. The result: tighter cuts, no clipped word onsets/tails, and reliable silence detection.
  4. Point it at any video file and it will:
  5. 1. **Make a proxy** — transcodes HEVC/4K → 1080p H.264 with hardware decode so every subsequent step runs in seconds, not minutes (portrait 9:16 sources handled too).
  6. 2. **Transcribe with [Whisper](https://github.com/openai/whisper)** — `tiny.en`, for the transcript text only.
  7. 3. **Force-align with [MFA](https://montreal-forced-aligner.readthedocs.io/)** — snaps the transcript to the audio at ~10–20ms precision; this drafts the take structure and the cut list.
  8. 4. **Plan the cuts** — applies a tone-aware silence heuristic (aggressive / balanced / sentimental / documentary), strips fillers, drops false starts and retakes. Shows you the plan before touching the video.
  9. 5. **Ground-truth every keep boundary** — re-transcribes each kept region in an isolated window before rendering. On retake-heavy footage Whisper collapses repeated lines and MFA's global alignment drifts by *seconds*; isolated windows catch that, plus dropped words and flubs hiding inside stretched words. Pauses >0.2s *inside* kept takes get trimmed to ~0.1s here too.
  10. 6. **Render & verify** — ffmpeg `trim+concat` (not `select`, which misaligns audio), then re-transcribes the output and scans for surviving stutters or clipped words before shipping.
  11. There's also an optional **browser timeline editor** (`make_review.py`) — a self-contained HTML page with a canvas waveform, pinch-to-zoom, drag-across-to-delete, auto-suggested silence bands, per-segment transcript cards, and a live "preview final cut" mode. It exports an edited keep list you paste back into the chat for a seconds-fast re-render.
  12. Runs entirely on your machine. No cloud APIs. Built for Apple Silicon — fast.
  13. ## Why this exists
  14. Most silence-cutters (auto-editor, opus, etc.) are either too aggressive (they cut your laughs) or too slow (the wrong ffmpeg flags). This skill was tuned against a 7-minute 4K HEVC interview that took 5+ minutes to even decode in other tools. With the right flags (`-hwaccel videotoolbox`, `-preset fast`, hardware-friendly trim/concat) the same source cuts in ~30 seconds.
  15. Specifically, this skill is opinionated about four things most tools get wrong:
  16. - **Laughs aren't silences.** Before any silence cut, it checks audio amplitude. If a "silent" window has audible content, it stays.
  17. - **Comedic pauses are content.** A 4-second pause after a punchline isn't dead air — it's the joke. The skill compresses dead air aggressively but preserves comedic timing.
  18. - **Audio sync matters.** Most `ffmpeg -vf select` cut tutorials produce videos with drifting audio. This skill uses `trim+concat`, which keeps everything in sync.
  19. - **ASR timestamps lie on real footage.** Whisper collapses retakes, drops words ("bland", "slop"), and hides pauses inside stretched word durations — and a forced aligner fed that transcript drifts by seconds. The skill treats all global timestamps as drafts and ground-truths every cut boundary with isolated-window re-transcription, then verifies the rendered output.
  20. ## Requirements
  21. - macOS (uses VideoToolbox for hardware-accelerated decode — works on Linux/Windows if you remove `-hwaccel videotoolbox` flags)
  22. - [Claude Code](https://claude.com/claude-code)
  23. - `ffmpeg` with `libx264` (`brew install ffmpeg`)
  24. - [`whisper`](https://github.com/openai/whisper) (`pip install openai-whisper`) — for the transcript text
  25. - [Montreal Forced Aligner](https://montreal-forced-aligner.readthedocs.io/) — the alignment / timing engine. **The skill installs this for you** on first run (creates a `mfa` conda env and downloads the English model; installs [miniforge](https://github.com/conda-forge/miniforge) via Homebrew if conda is missing). No manual setup needed. If Homebrew isn't available, the skill falls back to Whisper word timestamps + ffmpeg `silencedetect` (and says so in the plan).
  26. ## Install
  27. ```bash
  28. git clone https://github.com/louisedesadeleer/cut-video.git ~/.claude/skills/cut-video
  29. ```
  30. Restart Claude Code and `/cut-video` is available as a slash command.
  31. ## Usage
  32. In Claude Code:
  33. ```
  34. /cut-video
  35. ```
  36. Then paste a video file path when asked. The skill will:
  37. 1. Make a 1080p H.264 proxy (skip if source is already small/H.264)
  38. 2. Transcribe the audio with Whisper (transcript text only)
  39. 3. Force-align the transcript to the audio with MFA — the draft timing for every cut
  40. 4. Print a proposed cut list — timestamps, what gets cut, what stays, total compression
  41. 5. Ground-truth the keep boundaries with isolated-window re-transcription
  42. 6. Wait for your "go" (ask for the timeline editor here if you want to adjust by hand)
  43. 7. Render the cleaned version, verify its transcript is clean, and open it for review
  44. ## Tone presets
  45. When asked, pick one:
  46. - **`aggressive`** *(default)* — tightest pacing; ~40–60% runtime reduction, mid-sentence cuts, fillers and hedges sliced
  47. - **`balanced`** — aggressive on dead air, preserves comedic beats
  48. - **`sentimental`** — gentler everywhere; longer pauses preserved for emotional moments
  49. - **`documentary`** — only cuts genuine dead air; keeps thinking pauses intact
  50. ## What this skill doesn't do
  51. - It doesn't add zooms, layouts, b-roll, memes, captions, or motion graphics. Pair it with [clipify](https://github.com/louisedesadeleer/clipify) for short-form output, or your editor of choice for the rest.
  52. Built by [@louisedesadeleer](https://github.com/louisedesadeleer). PRs welcome.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.