Semantic Video Clipper

Overview

Segment a long video into clips by having AI analyze subtitle semantics and identify natural topic boundaries. The lightweight Python script handles parsing, timing calculation, and FFmpeg clipping based on AI-provided segment indices. Output clips and matching subtitles with filenames basename_<index>.* in same directory as the source video.

Workflow

Step 1: AI Analysis

Read full subtitle content (.vtt or .srt)
Understand semantic flow and topic transitions
Identify natural split points that:
- Align with complete sentence endings
- Occur at topic shifts (new concepts, examples, recaps)
- Fit within duration constraints (typically 25-60 seconds)
Return segment ranges as cue index pairs: [(0, 12), (12, 25), (25, 40), ...]

Step 2: Python Script Execution

Parse subtitles into Cue objects with timing
Convert cue indices to time ranges
Call FFmpeg in parallel to clip video segments
Shift subtitle times so each segment starts at 00:00
Save output files as basename_1.mp4 + basename_1.vtt, basename_2.*, etc.

Scripted execution

Script location: skills/semantic-video-clipper/scripts/clip_video.py

Option 1: From skill directory (recommended)

cd skills/semantic-video-clipper
python3 scripts/clip_video.py /path/video.mp4 /path/subtitles.vtt "0-12,12-25,25-40"

Option 2: From any location

python3 skills/semantic-video-clipper/scripts/clip_video.py /path/video.mp4 /path/subtitles.vtt "0-12,12-25,25-40"

The segments argument uses 0-based cue indices:

"0-12,12-25,25-40" - Three segments: cues 0-11, 12-24, 25-39

Optional flags:

--workers 4          # Number of parallel workers (default: 4)
--dry-run            # Only print segment plan without clipping

Dependencies

ffmpeg (external - must be in PATH)

Notes:

AI handles semantic analysis; Python script only handles parsing, timing, and FFmpeg clipping.
Output files always land beside the source video, named with an underscore plus 1-based index.
Parallel processing (--workers) provides 3-4x speedup for multi-clip videos.