Communitygithub.com

stable-video-cut

從一段(或多段)實拍素材中自動找出「畫面穩定」的片段,剪出來,再按穩定度排序拼成一條帶轉場的成片。全程只用 ffmpeg + Python (numpy),無需任何剪輯軟體。

stable-video-cut 是什麼?

stable-video-cut 是一個專為開發者與 AI 助手設計的影片自動穩定剪輯工具。它能自動分析實拍素材(如手機/手持拍攝的工廠、產品展示、案例影片)的畫面穩定度,找出穩定片段並按穩定度排序,最終拼接成帶轉場與封面的成片。此技能完全依賴 ffmpeg 與 Python(numpy),無需任何商業剪輯軟體,適合在 Claude Code、Cursor、Codex 等支援 shell 與 Python 的 AI agent 平台上使用。流程包含:透過 ffprobe 探測素材規格、Python 腳本進行幀差分析與自適應閾值穩定片段剪輯、產生穩定度排名總表、統一解析度與幀率後使用 xfade 轉場拼接,最後以 Pillow 生成中文標題透明 PNG 並疊加覆蓋與 BGM 混音。此技能能有效解決手持晃動影片中「挑出可用穩定段落」的痛點,輸出組織良好的素材目錄與最終成片。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/haorui1992/claude-skills/tree/HEAD/stable-video-cut

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

stable-video-cut 是做什麼的?

從一段(或多段)實拍素材中自動找出「畫面穩定」的片段,剪出來,再按穩定度排序拼成一條帶轉場的成片。全程只用 ffmpeg + Python (numpy),無需任何剪輯軟體。

何時使用

  • 「找穩定的畫面剪一下 / 畫面晃動的太多,挑穩的」
  • 「把這些素材合成一個影片,拼接處加轉場」
  • 手機/手持拍攝的工廠、產品展示、案例影片,需要挑出能直接用的段落

環境依賴

  • ffmpeg / ffprobe:先 which ffmpeg ffprobe(或 where ffmpeg)確認已安裝。Windows 可用 winget(winget install Gyan.FFmpeg)或從 gyan.dev 下載;Mac 用 brew install ffmpeg。下文命令一律用 ffmpeg / ffprobe 可執行檔名,不再寫死絕對路徑;若不在 PATH,先導出 FF=/path/to/ffmpeg、FP=/path/to/ffprobe 再用 "$FF" 等替代。
  • Python 3 + numpy(python --version / python -c "import numpy" 確認;缺則 pip install numpy)。
  • 涉及封面標題時另需 Pillow(pip install pillow)。

流程

1. 探測素材

對每個影片跑 ffprobe,拿到 解析度 / 幀率 / 時長:

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>

記錄各片規格——不同片拼接前必須統一(步驟 4)。

2. 穩定性分析 + 剪片段

把下面的腳本存到素材目錄(如 _stability_cut.py)再執行;它完成:幀差分析 → 自適應閾值找穩定段 → 剪成 mp4(帶原音)→ 輸出 穩定剪輯/分析報告.json。

關鍵參數都在檔案開頭,可按需調:

import subprocess, numpy as np, os, json, shutil
SRC = r"E:\你的素材資料夾"          # 改成實際路徑
OUT = os.path.join(SRC, "穩定剪輯")
FF  = shutil.which("ffmpeg")        # 不在 PATH 時改成實際路徑
FPS = 5          # 採樣幀率:分析用,越大越精細越慢
W   = 160        # 分析灰階圖寬度
MIN_SEC = 4.0    # 最短保留片段秒數
TOP_N = 4        # 每個原片最多保留幾段
THR_PCT = 45     # 自適應閾值 = 本片幀差分布的 P45(越小說出的段越穩但越少)

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))   # 相鄰幀平均差 = 波動
    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()))   # 按最穩排序
    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}_穩定{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]=[{"片段":i,"起":a/FPS,"止":b/FPS,"時長s":(b-a)/FPS,
                   "波動":round(float(S[a:b].mean()),2)} for i,(a,b) in enumerate(top,1)]
    print(name,"->",len(top),"段", [(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,"分析報告.json"),"w",encoding="utf-8"), ensure_ascii=False, indent=2)

3. 排「穩定度總表」

把所有片子的段按 波動 升序匯總成一張表(排名、原片、時間區間、時長、推薦用途),寫成 穩定剪輯/穩定度排名總表.md。

經驗:

  • 波動值越小越穩,但它是相對本片的量綱,跨片只能排序參考,不能當絕對值。
  • 「重點用哪支」一般就是波動最低的那支;最長且穩的段適合當主畫面。
  • 只有穩定段偏短(<4s 居多)時,把 THR_PCT 調大到 55-60 重跑。

4. 統一規格 + 拼接轉場

先把全部片段歸一化(解析度、幀率、音訊參數必須完全一致,xfade 才不會報錯):

for f in 片段*.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
  • 直式素材用 720:1280;橫式用 1280:720;方屏 1080:1080。
  • 源片比目標更清晰時,force_original_aspect_ratio=decrease 會縮到剛好放進目標畫框,pad 置中補黑邊,不變形。
  • 歸一化檔案一律用 ASCII 檔名(01.mp4…)放 _norm/ 子目錄——避免下面 concat 的中文路徑坑。

xfade 拼接:12 段、每段 0.5s 轉場時,filter 這樣構造:

[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]; ... 最後 -> [vout]
[0:a][1:a]acrossfade=d=0.5[a1]; [a1][2:a]acrossfade=d=0.5[a2]; ... -> [aout]

offset 遞推公式(轉場時長 d,各片時長 D1..Dn):

o1 = D1 - d
o2 = o1 + D2 - d
o3 = o2 + D3 - d   # 即前一段輸出時長 - d,逐段累加

D 用 ffprobe 精確取(注意有些是 16.400023 這種,別手算 16.4)。總時長 = ΣDi - (n-1)·d。

音訊用 acrossfade 同步淡化,避免拼接處「咔嚓」聲。一次 filter_complex 全部搞定,不要逐對 concat demuxer(那樣加不了轉場)。

常用轉場(每次挑不同的,避免重複感): fade(疊化,最安全)、fadeblack(換分組/收尾)、slideleft/slideright/smoothleft、circleopen、radial、hlslice、zoomin。11 段以上建議把 fadeblack 用在第 4-5 處和最後,做分組。

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 成片名.mp4

5. 封面標題 + 背景音樂(成片包裝)

核心技巧:標題文字用 PIL 生成透明 PNG,不要用 drawtext 畫中文——drawtext 在 Windows 下中文路徑跳脫極難除錯(冒號要 \:、textfile 路徑不能帶空格/中文、filter_complex_script 在 ffmpeg 9 裡已不存在),而 PIL 一次成功:

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # 微軟雅黑粗體,支援中文;Linux/macOS 換用思源黑體等
img = Image.new("RGBA", (720, 1280), (0,0,0,0))
d = ImageDraw.Draw(img)
fnt = ImageFont.truetype(F, 62)
# 先畫陰影再畫正文,保證在亮/暗背景上都清晰
d.text((x+3, y+3), "寵物洗護流水線", font=fnt, fill=(0,0,0,160))
d.text((x, y), "寵物洗護流水線", font=fnt, fill=(255,255,255,255))
img.save("title.png")

影片裡疊加(前 4.5s 淡入淡出,透明 PNG 用 loop 拉成 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 混音(原聲壓低 0.45,BGM 0.9,首尾 1-2s 淡入淡出):

[0:a]volume=0.45[a1];
[1:a]atrim=0:<總時長>,afade=t=in:d=1,afade=t=out:st=<總時長-2>:d=2,volume=0.9[b1];
[a1][b1]amix=inputs=2:duration=first:normalize=0[aout]
  • BGM 自備:先用 ffprobe 看時長,不夠長用 -stream_loop -1 循環。注意使用免版權音樂(如 lofi/CC0 音源)。
  • 封面圖:取最穩段中間一幀,同樣的 PIL 標題疊上去,720×1280,存 PNG/JPG。

6. 輸出約定

  • 素材目錄/穩定剪輯/ ← 各段穩定片段 + 分析報告.json + 穩定度排名總表.md + 成片_標題+BGM.mp4 + 封面_720x1280.png
  • 歸一化中間檔案 _norm/、臨時 PNG 用完刪掉

常見坑

  1. concat demuxer + 中文/空格路徑:ffmpeg 報 Illegal byte sequence。解法就是上面說的 ASCII 中間檔案 + 相對路徑 concat.txt。
  2. xfade 要求兩輸入完全同規格(解析度/幀率/像素格式/取樣率/聲道數不一致就報錯或結果錯亂)——第 4 步的歸一化就是幹這個的。
  3. Bash on Windows 裡中文輸出成亂碼(΢、????)不影響實際剪出的檔案(檔名是對的),只是 console 顯示問題;別被嚇到,用 ls 驗證即可。
  4. 分析耗時隨影片時長線性,幾支 1-4 分鐘的手持影片,整個流程(分析+剪輯+拼接)約 3-5 分鐘。
  5. 中文標題別用 drawtext(見第 5 步),PIL 生成透明 PNG 再 overlay 才穩。

相關技能