cut-segment

Cut Segment

Extract precise time ranges from a video. Replaces the legacy cut-video-segment command.

Procedure

1. Inputs

Field	Default
Source	required
Segments	required: one or more start..end ranges (e.g. 00:01:30..00:03:45) or a JSON array [{start, end, label?}, ...]
Output dir	default: same dir as source (or <project>/exports/ when run inside a project)
Mode	copy (lossless, stream-copy) — precise (re-encode for frame-accurate cuts)
Stitch	no (one file per segment) — yes (concatenate all segments into a single output)

2. Validate ranges

SRC="$(realpath "$INPUT")"
DUR=$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$SRC")

to_seconds() {
  awk -F: '{
    n = NF
    if (n == 3)      print $1*3600 + $2*60 + $3
    else if (n == 2) print $1*60 + $2
    else             print $1
  }' <<<"$1"
}

For each segment: convert start/end to seconds; reject if start >= end, if start < 0, or if end > DUR. Report which segments were rejected and abort.

3. Mode: copy (default)

Stream-copy each segment. Fast, lossless, but cuts land on the nearest keyframe (typically within 1–2s of the requested mark).

i=0
for seg in "${SEGMENTS[@]}"; do
  read s e <<<"$seg"
  OUT="$OUTDIR/$(basename "${SRC%.*}")_seg_$(printf '%02d' $i)${EXT}"
  ffmpeg -y -ss "$s" -to "$e" -i "$SRC" -c copy -avoid_negative_ts make_zero "$OUT"
  i=$((i+1))
done

-ss before -i enables fast seek; combined with -c copy this is the lossless path.

4. Mode: precise

Frame-accurate cuts via re-encode. -ss goes after -i to force decode-side seek.

ffmpeg -y -i "$SRC" -ss "$s" -to "$e" \
  -c:v libx264 -crf 18 -preset medium \
  -c:a aac -b:a 192k \
  "$OUT"

If a render profile name was supplied (from render-profiles.json), build the encoder args from that profile instead.

5. Stitch (optional)

If STITCH=yes:

LIST=$(mktemp)
for f in "${SEGMENT_OUTPUTS[@]}"; do printf "file '%s'\n" "$f" >> "$LIST"; done
ffmpeg -y -f concat -safe 0 -i "$LIST" -c copy "$OUTDIR/$(basename "${SRC%.*}")_stitched${EXT}"