trim-video-clips

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

1. Verify ffmpeg is on PATH (which ffmpeg) and the source video exists.
2. 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]
   

3. 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>.
4. 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.