Communitygithub.com

stable-video-cut

Automatically detect stable segments from one or more handheld videos, trim them, and splice them into a single video with crossfade transitions using only ffmpeg and Python (numpy). No video editing software required.

What is stable-video-cut?

The `stable-video-cut` skill is an AI Agent tool (compatible with code-interpreter capable agents like Claude Code, Codex, and Cursor) that automates the video editing pipeline for handheld or shaky footage. It performs frame-difference analysis to identify visually stable segments, ranks them by stability, and produces a final composite video with smooth transitions, title overlays, and background music. The entire process is powered by `ffmpeg`, `ffprobe`, Python 3, and `numpy`, with optional `Pillow` for title generation. It is ideal for quickly curating usable clips from product showcases, factory tours, or any real-world shooting scenario without using traditional video editing software. The skill outputs a structured directory with stability reports, a ranked markdown table, normalized intermediate files, and the final edited video.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/haorui1992/claude-skills/tree/HEAD/stable-video-cut

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does stable-video-cut do?

Automatically detect stable segments from one or more real-shot videos, trim them out, sort by stability, and splice them into a final video with crossfade transitions. The entire process uses only ffmpeg + Python (numpy), with no video editing software required.

When to Use

  • "Find stable parts and cut them out / too much camera shake, pick the steady ones"
  • "Combine these clips into one video, add transitions at the joints"
  • Handheld phone/phone-recorded factory tours, product demos, case studies where you need to extract usable segments for final production

Dependencies

  • ffmpeg / ffprobe: First run which ffmpeg ffprobe (or where ffmpeg on Windows) to confirm installation. On Windows you can use winget (winget install Gyan.FFmpeg) or download from gyan.dev; on Mac brew install ffmpeg. All commands below use the executable names ffmpeg / ffprobe without hardcoded paths; if they are not in PATH, export FF=/path/to/ffmpeg, FP=/path/to/ffprobe and use "$FF" etc.
  • Python 3 + numpy (verify with python --version / python -c "import numpy"; if missing, pip install numpy).
  • For cover titles, also need Pillow (pip install pillow).

Workflow

1. Probe Source Material

Run ffprobe on each video to get resolution / frame rate / duration:

ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate,duration \
  -show_entries format=duration -of default=noprint_wrappers=1 <file>

Record each clip's specs – they must be unified before concatenation (step 4).

2. Stability Analysis + Cut Segments

Save the script below into the source folder (e.g., _stability_cut.py) and run it. It performs: frame-difference analysis → adaptive threshold to find stable segments → trims each into an mp4 (with original audio) → outputs 稳定剪辑/analysis_report.json.

Key parameters at the top of the script; adjust as needed:

import subprocess, numpy as np, os, json, shutil
SRC = r"E:\your_source_folder"          # change to actual path
OUT = os.path.join(SRC, "稳定剪辑")
FF  = shutil.which("ffmpeg")        # change if not in PATH
FPS = 5          # sampling frame rate: higher = more precise but slower
W   = 160        # analysis grayscale width
MIN_SEC = 4.0    # minimum segment length to keep
TOP_N = 4        # max segments per source video
THR_PCT = 45     # adaptive threshold = P45 of frame-diff distribution (lower = stricter/less segments)

def gray(path):
    p = subprocess.run([FF,"-hide_banner","-loglevel","error","-i",path,
        "-vf",f"scale={W}:-2,fps={FPS}","-f","rawvideo","-pix_fmt","gray","-"],
        stdout=subprocess.PIPE)
    fp = FF.replace("ffmpeg","ffprobe")
    if shutil.which("ffprobe"):
        fp = shutil.which("ffprobe")
    pr = subprocess.run([fp,"-v","error",
        "-select_streams","v:0","-show_entries","stream=width,height","-of","json",path],
        capture_output=True,text=True)
    w,h = json.loads(pr.stdout)["streams"][0]["width"], json.loads(pr.stdout)["streams"][0]["height"]
    h = (h*W//w)//2*2
    return np.frombuffer(p.stdout,np.uint8).reshape(-1,h,W).astype(np.float32)

def smooth(x,w=5):
    k=np.ones(w)/w; return np.convolve(x,k,mode="same")

report={}
for name in sorted(f for f in os.listdir(SRC) if f.lower().endswith((".mp4",".mov",".m4v"))):
    f = gray(os.path.join(SRC,name)); n=f.shape[0]
    D = np.mean(np.abs(f[1:]-f[:-1]),axis=(1,2))   # mean absolute diff between frames = motion
    S = smooth(D)
    thr = float(np.percentile(D,THR_PCT))
    good = S<thr
    runs,start=[],None
    for i in range(len(good)):
        if good[i] and start is None: start=i
        if not good[i] and start is not None: runs.append((start,i)); start=None
    if start is not None: runs.append((start,len(good)))
    runs=[(a,b) for a,b in runs if (b-a)>=FPS*MIN_SEC]
    runs.sort(key=lambda ab: float(S[ab[0]:ab[1]].mean()))   # sort by most stable
    top=runs[:TOP_N]; top.sort(key=lambda ab:ab[0])
    os.makedirs(OUT,exist_ok=True)
    base=os.path.splitext(name)[0]
    for i,(a,b) in enumerate(top,1):
        outp=os.path.join(OUT,f"{base}_stable{i}_{a/FPS:05.1f}s-{b/FPS:05.1f}s.mp4")
        subprocess.run([FF,"-hide_banner","-loglevel","error","-y","-ss",f"{a/FPS:.2f}",
            "-i",os.path.join(SRC,name),"-t",f"{(b-a)/FPS:.2f}",
            "-c:v","libx264","-preset","veryfast","-crf","20",
            "-c:a","aac","-b:a","128k","-movflags","+faststart",outp],check=True)
    report[name]=[{"segment":i,"start":a/FPS,"end":b/FPS,"duration_s":(b-a)/FPS,
                   "motion":round(float(S[a:b].mean()),2)} for i,(a,b) in enumerate(top,1)]
    print(name,"->",len(top),"segments", [(f"{a/FPS:.1f}-{b/FPS:.1f}s",round(float(S[a:b].mean()),1)) for a,b in top])
json.dump(report, open(os.path.join(OUT,"analysis_report.json"),"w",encoding="utf-8"), ensure_ascii=False, indent=2)

3. Build "Stability Ranking Table"

Collect all segments from all clips, sort by motion ascending into a table (rank, source clip, time range, duration, recommended use), and write it as 稳定剪辑/stability_ranking_table.md.

Experience:

  • Lower motion values = more stable, but it is relative to each clip; cross-clip sorting is only a reference, not absolute.
  • "Which clip to focus on" is generally the one with the lowest motion; the longest stable segment is best for the main shot.
  • If most stable segments are short (<4s), increase THR_PCT to 55-60 and rerun.

4. Unify Specs + Splice with Transitions

First normalize all segments (resolution, frame rate, audio parameters must be exactly identical or xfade will fail):

for f in segments*.mp4; do
  ffmpeg -y -i "$f" -vf "scale=720:1280:force_original_aspect_ratio=decrease,pad=720:1280:(ow-iw)/2:(oh-ih)/2,setsar=1" \
    -r 30 -c:v libx264 -crf 20 -pix_fmt yuv420p -c:a aac -b:a 128k -ar 44100 -ac 2 "_norm/$(printf '%02d' $i).mp4"
done
  • Use 720:1280 for portrait footage; 1280:720 for landscape; 1080:1080 for square.
  • When source is sharper than target, force_original_aspect_ratio=decrease scales down to fit the canvas, and pad centers with black borders – no distortion.
  • Normalized files should always use ASCII filenames (01.mp4…) placed in _norm/ subdirectory – this avoids Chinese path issues with the xfade filter below.

Build xfade chain: For 12 segments with 0.5s transition each, construct filters like this:

[0:v][1:v]xfade=transition=<T1>:duration=0.5:offset=<o1>[v1];
[v1][2:v]xfade=transition=<T2>:duration=0.5:offset=<o2>[v2]; ... final -> [vout]
[0:a][1:a]acrossfade=d=0.5[a1]; [a1][2:a]acrossfade=d=0.5[a2]; ... -> [aout]

Offset recurrence (transition duration d, each clip duration D1..Dn):

o1 = D1 - d
o2 = o1 + D2 - d
o3 = o2 + D3 - d   # i.e., previous output duration - d, accumulated

Get D precisely with ffprobe (note some durations are 16.400023, don't manually round to 16.4). Total duration = ΣDi - (n-1)·d.

Audio uses acrossfade for simultaneous fading, avoiding clicks at joints. Use a single filter_complex – do NOT use concat demuxer for multiple clips (it doesn't allow transitions).

Common transitions (pick different ones to avoid repetition): fade (safest), fadeblack (for section changes/endings), slideleft/slideright/smoothleft, circleopen, radial, hlslice, zoomin. For 11+ segments, use fadeblack at the 4th-5th joint and the last one as a group boundary.

ffmpeg -y -i _norm/01.mp4 ... -i _norm/12.mp4 -filter_complex "$FILTER" \
  -map "[vout]" -map "[aout]" -c:v libx264 -crf 20 -preset veryfast -pix_fmt yuv420p \
  -c:a aac -b:a 128k -movflags +faststart final_video_name.mp4

5. Title Overlay + Background Music (Final Polish)

Core tip: generate title text as a transparent PNG using PIL, not drawtext for Chinese – drawtext on Windows is extremely tricky with Chinese paths (colons must be escaped as \:, textfile paths can't have spaces/Chinese, filter_complex_script was removed in ffmpeg 9). PIL works first time:

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # Microsoft YaHei Bold, supports Chinese; on Linux/macOS use Noto Sans CJK etc.
img = Image.new("RGBA", (720, 1280), (0,0,0,0))
d = ImageDraw.Draw(img)
fnt = ImageFont.truetype(F, 62)
# First draw shadow then main text so it's legible on both light and dark backgrounds
d.text((x+3, y+3), "Pet Grooming Line", font=fnt, fill=(0,0,0,160))
d.text((x, y), "Pet Grooming Line", font=fnt, fill=(255,255,255,255))
img.save("title.png")

Overlay in video (4.5s fade in/out, transparent PNG looped to 4.5s):

[1:v]loop=loop=449:size=1:start=0,fps=30,format=rgba,
      fade=t=in:st=0:d=0.4:alpha=1,fade=t=out:st=3.8:d=0.7:alpha=1,
      trim=duration=4.5,setpts=PTS-STARTPTS[ov];
[0:v][ov]overlay=0:0:eof_action=pass,format=yuv420p[vout]

BGM mixing (reduce original volume to 0.45, BGM at 0.9, fade in/out first/last 1-2s):

[0:a]volume=0.45[a1];
[1:a]atrim=0:<total_duration>,afade=t=in:d=1,afade=t=out:st=<total_duration-2>:d=2,volume=0.9[b1];
[a1][b1]amix=inputs=2:duration=first:normalize=0[aout]
  • Prepare BGM yourself: check its duration with ffprobe; if too short, loop with -stream_loop -1. Use royalty-free music (e.g., lofi/CC0).
  • Cover thumbnail: extract the mid-frame of the most stable segment, apply the same PIL title overlay, save as 720×1280 PNG/JPG.

6. Output Convention

  • Source folder/稳定剪辑/ ← all stable segments + analysis_report.json + stability_ranking_table.md + final_title+BGM.mp4 + cover_720x1280.png
  • Normalized intermediate files _norm/ and temporary PNGs are deleted after use

Common Pitfalls

  1. concat demuxer + Chinese/spaces in paths: ffmpeg throws Illegal byte sequence. Solution: use ASCII intermediate files + relative path concat.txt as described above.
  2. xfade requires both inputs to have identical specs (resolution/framerate/pixel format/sample rate/channels – if mismatched, it fails or produces artifacts). Normalization in step 4 exists to fix this.
  3. Bash on Windows displays Chinese as garbled (e.g., ΢、????) – this does not affect actual output files (filenames are correct); it's only a console display issue. Verify with ls.
  4. Analysis time scales linearly with video duration; for a few handheld clips of 1–4 minutes, the entire workflow (analysis+trim+splice) takes about 3–5 minutes.
  5. Avoid drawtext for Chinese titles (see step 5); use PIL to generate a transparent PNG and overlay it instead.

Related Skills