Communitygithub.com

stable-video-cut

複数の実写素材から「画面安定」した部分を自動検出し、安定度順に繋ぎ、トランジション付きの完成動画を生成します。ffmpeg + Python(numpy)のみで実現。

stable-video-cut とは?

このスキルは、ffmpegとPython(numpy)のみを使用して、手持ち撮影や不安定な動画素材から「画面が安定している」部分だけを自動的にクリップし、安定度に基づいて並べ替え、トランジション効果を付けて合成するためのAIエージェントスキルです。具体的には、素材動画からフレーム間の差分(輝度変化)を分析し、適応的閾値で安定区間を検出、各素材から安定しているセグメントを切り出します。その後、全セグメントの解像度・フレームレート・音声パラメータを統一し、xfadeフィルターを使ってトランジションを施しながら一つの完成動画に結合します。さらに、PILを使用して中国語のタイトルを透明PNGとして生成し、オーバーレイやBGMのミックス、カバー画像の作成も可能です。このスキルはClaude CodeやCursor、Codexなどの開発エージェントに統合でき、工場、製品デモ、ケーススタディ動画など、実用的なシーンで役立ちます。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 トランジションの場合、フィルターは以下のように構築:

[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. タイトル + BGM(完成動画パッケージング)

核心: タイトル文字は PIL で透明 PNG を生成、drawtext は使わない——drawtext は Windows で中国語パスのエスケープが極めて困難(コロンには \:、textfile パスはスペース/中国語不可、filter_complex_script は ffmpeg 9 で削除済み)。PIL なら一度で成功:

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # 微软雅黑 Bold、中国語対応; Linux/macOS では Noto Sans CJK などに変更
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.5 秒、フェードイン/アウト; 透明 PNG は loop で 4.5 秒に延長):

[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-2 秒フェードイン/アウト):

[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. Windows 上の Bash で中国語が文字化け(΢、????)は実際の出力ファイルに影響なし(ファイル名は正しい); コンソール表示の問題なので ls で確認すれば安心。
  4. 分析時間は動画の長さに比例。数本の 1-4 分手持ち動画の場合、全処理(分析+クリップ+結合)で約 3-5 分。
  5. 中国語タイトルに drawtext は使わない(ステップ5参照); PIL で透明 PNG を生成し overlay する方が安定。

関連スキル