Clean Cut

A clean cut keeps every spoken word and removes only the non-content between words: hesitation sounds, audio events, and dead air. The viewer should not notice an edit happened, only that the video is shorter and tighter.

This skill is a style layer on top of video-use (~/.agents/skills/video-use/SKILL.md, source: browser-use/video-use). Read its SKILL.md first: its Hard Rules apply here unchanged. video-use provides transcription and visual checks. This skill decides what to cut and ships its own cut builder and renderer.

Defaults

The user already stated this strategy by invoking the skill. Confirm only the unknowns: content type (screen recording or talking head) and language if unclear. Then execute without a separate strategy round.

Setup

• VU = the video-use repo root: $(dirname "$(readlink -f ~/.agents/skills/video-use/SKILL.md)"). H = $VU/helpers.
• PY = video-use's Python with its deps ($VU/.venv/bin/python after uv sync). This skill's own scripts are stdlib-only and run with any python3.
• CC = this skill's folder. E = <videos_dir>/edit. SRC = the source video.
• ElevenLabs key: ELEVENLABS_API_KEY in the environment or $VU/.env. The key needs the Speech to Text permission. A 401 with missing_permissions means the key exists but that toggle is off: the user enables it in ElevenLabs → Developers → API Keys.

Pipeline

1. Transcribe (word-level, with language code)

$PY $H/transcribe.py "$SRC" --language <iso> --edit-dir "$E"
$PY $H/pack_transcripts.py --edit-dir "$E"

Pass --language explicitly (en, ru, de, ...). Scribe keeps fillers verbatim (um, uh, э-э-э, м-м-м) and tags events ([clears throat], [laughs], [typing]). Those tokens are the whole editing signal, so a transcriber that normalizes fillers away (local Whisper) cannot do this job. A 17 min video transcribes in ~20s.

2. Proxy + static-screen detection in one decode pass

4K60 decode is the slowest step (~10 min per 17 min of source). Decode the source once, in the background, while step 1 runs:

ffmpeg -hide_banner -nostats -y -i "$SRC" -filter_complex \
 "[0:v]scale=1920:-2:flags=lanczos,fps=30,split[p][f];\
  [f]scale=640:-2,fps=10,freezedetect=n=-50dB:d=0.3,metadata=mode=print:file=$E/freeze.txt,nullsink" \
 -map "[p]" -map 0:a -c:v libx264 -preset veryfast -crf 14 -g 15 -pix_fmt yuv420p \
 -c:a pcm_s16le "$E/proxy_1080p30.mov"

• proxy_1080p30.mov has the same timeline as the source. Its short GOP (-g 15) makes each segment seek cheap.
• freeze.txt lists intervals where the screen is static. A silence not fully inside a freeze interval means something moves on screen: typing, output streaming, scrolling. Skip freeze.txt for talking-head footage.
• For a portrait source, use scale=-2:1920 in both places.

3. Build the cut list

python3 $CC/scripts/build_edl.py --edit-dir "$E" --transcript <name>.json \
  --source proxy_1080p30.mov --freeze freeze.txt --speed 1.1

Rules the script applies (tune with flags; the defaults are the approved style):

• Filler = any audio_event, a token matching the language's hesitation pattern (FILLERS dict: en, ru, de, es, fr), or any letter stretched with hyphens (a-a-a, э-э-э, a з-з-- stutter). English patterns always apply as a fallback. For a new language, add its hesitation sounds to FILLERS or pass --extra-fillers 'tok1,tok2'.
• Cut between two kept words when a filler sits between them, or when the silence is ≥ --min-gap (0.4s).
• Keep --pad-out 0.15s after the last word and --pad-in 0.12s before the next one. On an active screen, keep 0.45s and 0.35s.
• Filler guard: padding stops 20ms short of a removed filler, with a 30ms floor, so a sliver of "uh" never leaks back in.
• Cut windows under 0.12s are skipped: they are mid-phrase and not worth a seam.
• Head: 0.3s before the first word. Tail: 0.6s after the last word.

Read cuts_log.json before rendering:

• Tally the removed values. Every entry must be a filler or an event. A real word there means a pattern is too greedy: fix the regex and rebuild.
• Tokens stretched without hyphens (sooo, иии) stay on purpose: they carry a real word.

Reference result: 17.4 min → 12.9 min (283 cuts, 140 of them fillers, 25 on an active screen).

4. Render the preview (1080p30, 1.1x)

python3 $CC/scripts/render.py "$E/edl.json" -o "$E/preview_1080p.mp4" --res 1080 --fps 30 --speed 1.1

render.py extracts segments in parallel (--workers 4). Each segment gets setpts + atempo for speed and 30ms fades at both edges, and is snapped to whole frames. Then it concats with video stream-copied and audio resampled against drift, and runs two-pass loudnorm. 284 segments from the proxy render in ~4 min.

5. Self-check

• ffprobe the output: video and audio stream durations must be equal. Expect ~13ms per cut over the EDL estimate (concat rounds to AAC frames; 3.7s over 284 cuts). A/V stays in sync.
• $PY $H/timeline_view.py <out> <start> <end> -o $E/verify/<name>.png at the start, a midpoint, the last 6s, and one dense cut region. Look for waveform spikes at seams.
• The tail must end on silence, not mid-word: ffmpeg -ss <dur-0.4> -i <out> -af volumedetect -f null - → max_volume far below speech (≈ -50 dB).

6. Final (after the user approves the preview)

Point the same EDL at the original source. Cut times stay valid because the proxy shares the source timeline.

python3 -c "import json,sys;e=json.load(open(sys.argv[1]));e['sources']['S']=sys.argv[2];json.dump(e,open(sys.argv[3],'w'),indent=1,ensure_ascii=False)" \
  "$E/edl.json" "$SRC" "$E/edl_4k.json"
python3 $CC/scripts/render.py "$E/edl_4k.json" -o "$E/final_4k.mp4" --res 2160 --fps 30 --speed 1.1

Expect ~9 min for a 13 min output. final_4k.mp4 duration must equal the preview's.

7. Persist

Append the session to $E/project.md (format in video-use). Record the numbers (cuts, fillers, runtime before and after), the kept parasites, and the render commands.

Report to the user

Lead with the output path and the runtime change (before → after). Then cover what was removed (filler count, pause rule), what was kept on purpose (parasites, with counts), and the loudness change. Say what was verified and what was not: spot checks are not a full watch. End with cleanup candidates: proxy_1080p30.mov, clips_*p/.