Clip Editing — ffmpeg-based video editing for screen-capture clips

When to Use

• User records short screen-capture demo clips (e.g. product marketing clips) and wants:
  • junk removed from start/end (fumbling with files, cmd windows visible)
  • a middle segment cut out
  • two takes merged into one clip
  • a text overlay added (e.g. "E:\ → F:")
  • visual verification of a clip before publishing
• Trigger phrases: "trim the clip", "cut out the middle", "merge the takes", "add text to the clip", "check the clip", "edit the clip"

Environment

• ffmpeg 8.1.1 (winget full build) — verified working on Windows Server 2025 via gdigrab
• ffprobe sits next to ffmpeg in the same bin directory
• Path resolution order: FFMPEG_PATH/FFPROBE_PATH env vars → winget Packages path (derived from %LOCALAPPDATA%) → ffmpeg/ffprobe on PATH
• All scripts are Python 3 (stdlib only — subprocess + json), run from anywhere

Quick Reference (scripts in scripts/)

Procedure

1. Probe first — probe.py gives duration/fps so you know how much junk to trim and the exact timestamps to cut.
2. Extract frames — frames.py at 1-2fps so the agent can SEE the clip (via vision) and pick precise trim/cut points. Review the frames before deciding.
3. Edit — trim / cut / merge / overlay as needed.
4. Verify the OUTPUT — extract frames from the edited clip and visually confirm: clean start frame, correct content, no fumbling visible. Never deliver an unverified clip.
5. Report — state the before/after duration and what was changed.

Pitfalls

• -c copy trims snap to keyframes — screen captures have sparse keyframes, so stream-copy trims can be off by seconds. trim.py re-encodes by default for accuracy; --fast is only for quick drafts.
• drawtext escaping — fontfile colons must be escaped (C\:/Windows/Fonts/segoeui.ttf), and the path must use forward slashes (backslashes get mangled by drawtext's escape parser). Text colons/percent/backslashes must be escaped in order: backslash → colon → percent → quote. overlay_text.py handles all of this internally — verified pixel-identical to a textfile= reference render (diff YAVG=0).
• Fonts on Server 2025 — arial.ttf may not exist; the script falls back to segoeui.ttf (always present on Windows).
• Merge needs matching codecs — clips from the same recorder are fine. merge.py re-encodes via the concat filter so minor mismatches still work.
• concat.py vs merge.py — use concat.py when joining same-codec clips (stream copy, lossless, near-instant) via a concat list file; it auto-probes and falls back to re-encode if any clip differs in codec/resolution/pix_fmt/fps/timebase. concat.py is the right tool for joining multiple takes of marketing clips shot with identical settings; merge.py is the simpler video-only re-encode for arbitrary mismatched clips. Both route filenames with apostrophes to the re-encode path automatically.
• Windows paths in bash — pass native C:\... paths; Python handles them. Quote paths containing spaces.
• Always verify with frames.py after editing — the agent's vision check is the final gate.

Verification

• probe.py on output shows the expected duration (e.g. 10s after trimming to 10s).
• frames.py on output shows a clean first frame (no fumbling, no stray windows) and the correct content.