| name | trim-video-clips |
| description | cut a source video into named clips at exact time windows using ffmpeg. Use when you have a long video and a list of {name, start, end} segments and need each one as its own frame-accurate, re-encoded .mp4 — e.g. building a clip library, assembling an edit, or producing platform variants. |
trim-video-clips
Purpose
Cut one source video into a set of named clip files at exact time windows. Each clip is re-encoded (not stream-copied) with libx264, so cuts land frame-accurately on the requested in/out points — important when the clips will be dropped into an edit. This is the mechanical cutting step: deciding which windows to cut is the caller's job (e.g. build-brand-clip-library decides windows by watching the video, then calls this atom).
Inputs
source (required) — path to the source video file.clips (required) — path to a JSON array of clip specs. Each spec has name plus either end or duration. start/end accept seconds (number) or a timecode string (SS, MM:SS, HH:MM:SS, optional .ms):
[
{"name": "hook-laptop-close", "start": 0, "end": 2.6},
{"name": "mac-mini-glow", "start": "00:03", "duration": 5},
{"name": "endcard", "start": 90.0, "end": "01:34.4"}
]
output_dir (required) — destination folder for the clip files.crf (optional, default 18) — x264 quality; lower is higher quality.overwrite (optional, default false) — re-cut clips even if the output file already exists (re-runs are otherwise idempotent).
Workflow
- Verify
ffmpeg is on PATH (which ffmpeg) and the source video exists.
- Run the cutter:
python3 skills/atoms/editing/trim-video-clips/scripts/trim_clips.py \
--source /path/to/source.mp4 \
--clips /path/to/clips.json \
--output-dir /path/to/clips/ \
[--crf 18] [--overwrite]
- The script, per clip: slugifies
name → <slug>.mp4, resolves the time window, and runs
ffmpeg -y -ss <start> -i <source> -t <duration> -c:v libx264 -crf <crf> -preset fast -pix_fmt yuv420p -c:a aac -b:a 192k <out>.
- It writes
manifest.json to output_dir listing every clip, its window, status, and any warnings/errors.
Output
- One
<slug>.mp4 per clip spec in output_dir.
output_dir/manifest.json — run metadata: skill_name, run_id, input_path, output_files, per-clip records (name, file, start, duration, status), status, warnings, errors.
Quality Checks
- One clip file exists per valid spec; each is non-zero size.
- Clip durations match the requested windows (verify with
ffprobe).
- Clips are playable and re-encoded (h264/yuv420p), so they cut cleanly into an edit.
manifest.json exists and every output_files path resolves on disk.
Failure Modes
- Source missing / unreadable — the script exits with a clear error before cutting.
- Bad clip spec (no
end/duration, non-positive duration, unparseable time) — that clip is skipped and recorded in manifest.json errors; other clips still cut.
ffmpeg not installed — install via brew install ffmpeg.- Window past end of video — ffmpeg produces a shorter clip; check durations against
ffprobe.
- Source has no audio stream — clips are produced without audio; this is expected, not an error.
