Communitygithub.com

stable-video-cut

Détecte automatiquement les séquences stables dans une ou plusieurs vidéos brutes, les découpe, puis les assemble par ordre de stabilité en une vidéo finale avec transitions. Utilise uniquement ffmpeg et Python (numpy), sans logiciel de montage.

Qu'est-ce que stable-video-cut ?

Ce skill permet aux agents IA (comme Claude Code, Cursor, Codex) d’analyser des vidéos brutes pour en extraire les passages les plus stables, puis de les assembler en une vidéo cohérente avec transitions. Il fonctionne sur toutes les plateformes supportant ffmpeg et Python (Windows, macOS, Linux). L’analyse de stabilité repose sur la différence entre trames consécutives (frame difference) avec un seuil adaptatif configurable (THR_PCT). Le skill gère l’ensemble du pipeline : analyse, découpage, normalisation des formats, concaténation avec xfade, ajout de titres en PNG (via Pillow) et mixage audio. Il est particulièrement adapté aux vidéos tournées avec un téléphone ou à main levée (usine, produit, cas client) où l’on a besoin de sélectionner les plans utilisables sans outil de montage complexe. Les sorties incluent un rapport JSON, un classement des séquences, et la vidéo finale avec titre et musique de fond optionnelle.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait stable-video-cut ?

Détecte automatiquement les séquences « stables » dans une ou plusieurs vidéos brutes, les découpe, puis les assemble par ordre de stabilité en une vidéo finale avec transitions. Utilise uniquement ffmpeg + Python (numpy), sans logiciel de montage.

Quand l’utiliser

  • « Trouve les plans stables et coupe les passages trop tremblants »
  • « Assemble ces vidéos en une seule, avec des transitions aux jonctions »
  • Vidéos tournées au téléphone ou à main levée (usine, démo produit, cas client) où il faut extraire les segments directement exploitables

Dépendances

  • ffmpeg / ffprobe : vérifiez l’installation avec which ffmpeg ffprobe (ou where ffmpeg sur Windows). Windows : winget install Gyan.FFmpeg ou téléchargement depuis gyan.dev ; Mac : brew install ffmpeg. Les commandes utilisent ffmpeg / ffprobe sans chemin absolu ; si hors PATH, exportez FF=/chemin/vers/ffmpeg, FP=/chemin/vers/ffprobe et utilisez "$FF" etc.
  • Python 3 + numpy (python --version / python -c "import numpy" ; si absent, pip install numpy).
  • Pillow pour les titres de couverture (pip install pillow).

Procédure

1. Analyse des métadonnées

Pour chaque vidéo, utilisez ffprobe pour obtenir résolution, framerate et durée :

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 <fichier>

Consignez les spécifications de chaque clip – ils doivent être unifiés avant l’assemblage (étape 4).

2. Analyse de stabilité + découpage

Placez le script ci-dessous dans le dossier des sources (ex. _stability_cut.py) et exécutez-le. Il effectue : analyse des différences inter-trames → seuil adaptatif pour détecter les segments stables → découpage en mp4 (avec son original) → sortie stabilites/rapport_analyse.json.

Les paramètres clés sont en tête de fichier, ajustables :

import subprocess, numpy as np, os, json, shutil
SRC = r"E:\votre_dossier_sources"        # à modifier
OUT = os.path.join(SRC, "stabilites")
FF  = shutil.which("ffmpeg")              # ou chemin explicite si hors PATH
FPS = 5          # taux d’échantillonnage : plus élevé = plus précis mais plus lent
W   = 160        # largeur de l’image en niveaux de gris pour l’analyse
MIN_SEC = 4.0    # durée minimale d’un segment stable
TOP_N = 4        # nombre max de segments par vidéo source
THR_PCT = 45     # centile du seuil adaptatif (plus bas = segments plus stables mais moins nombreux)

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")

rapport={}
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))   # différence inter-trame = mouvement
    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()))   # tri par stabilité
    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)
    rapport[name]=[{"segment":i,"debut":a/FPS,"fin":b/FPS,"duree_s":(b-a)/FPS,
                   "mouvement":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(rapport, open(os.path.join(OUT,"rapport_analyse.json"),"w",encoding="utf-8"), ensure_ascii=False, indent=2)

3. Classement général de stabilité

Agrégez tous les segments de toutes les vidéos triés par mouvement croissant dans un tableau (rang, source, intervalle temporel, durée, usage recommandé), écrivez-le dans stabilites/classement_stabilite.md.

Retour d’expérience :

  • Plus la valeur de mouvement est faible, plus le plan est stable, mais elle est relative à chaque vidéo ; elle ne sert qu’à comparer entre segments d’une même source, pas comme valeur absolue.
  • Le segment avec le mouvement le plus bas est généralement le meilleur ; le plus long et stable convient comme plan principal.
  • Si les segments stables sont trop courts (<4s en majorité), augmentez THR_PCT à 55-60 et relancez.

4. Normalisation + assemblage avec transitions

Normalisez d’abord tous les fragments (résolution, framerate, paramètres audio identiques pour éviter les erreurs xfade) :

for f in fragment*.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
  • Pour du portrait : 720:1280 ; paysage : 1280:720 ; carré : 1080:1080.
  • Si la source est plus nette que la cible, force_original_aspect_ratio=decrease réduit pour tenir dans le cadre, pad ajoute des bandes noires centrées sans déformation.
  • Les fichiers normalisés doivent avoir des noms ASCII (01.mp4…) dans _norm/ pour éviter les problèmes de chemins avec la concaténation suivante.

Assemblage avec xfade : pour 12 segments avec transition de 0,5 s, construisez le filtre ainsi :

[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]

Formule de décalage (durée de transition d, durées des segments D1..Dn) :

o1 = D1 - d
o2 = o1 + D2 - d
o3 = o2 + D3 - d   # soit durée de sortie du précédent - d, cumulée

Utilisez ffprobe pour obtenir les durées exactes (attention : parfois 16.400023, ne calculez pas à la main 16.4). Durée totale = ΣDi - (n-1)·d.

Audio : utilisez acrossfade pour un fondu synchronisé, évite les clics aux jonctions. Un seul filter_complex suffit, pas de concat demuxer (qui ne permet pas les transitions).

Transitions courantes (variez pour éviter la répétition) : fade (le plus sûr), fadeblack (changement de groupe/fin), slideleft/slideright/smoothleft, circleopen, radial, hlslice, zoomin. Pour plus de 11 segments, placez fadeblack au 4-5e et au dernier.

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 video_finale.mp4

5. Titres + musique de fond (habillage final)

Astuce clé : générez les titres avec PIL sous forme de PNG transparent, n’utilisez pas drawtext pour le chinois – drawtext sous Windows est très pénible avec les chemins et caractères spéciaux (doubles points à échapper \:, textfile sans espaces/unicode, filter_complex_script supprimé dans ffmpeg 9). PIL fonctionne du premier coup :

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # Gras Microsoft YaHei, support chinois; Linux/macOS : Source Han Sans etc.
img = Image.new("RGBA", (720, 1280), (0,0,0,0))
d = ImageDraw.Draw(img)
fnt = ImageFont.truetype(F, 62)
# Ombre puis texte pour lisibilité sur fond clair/foncé
d.text((x+3, y+3), "Ligne de lavage pour animaux", font=fnt, fill=(0,0,0,160))
d.text((x, y), "Ligne de lavage pour animaux", font=fnt, fill=(255,255,255,255))
img.save("titre.png")

Superposition dans la vidéo (fondu 4,5 s, PNG transparent bouclé) :

[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]

Mixage BGM (son original réduit à 0,45, BGM à 0,9, fondu entrée/sortie de 1-2 s) :

[0:a]volume=0.45[a1];
[1:a]atrim=0:<duree_totale>,afade=t=in:d=1,afade=t=out:st=<duree_totale-2>:d=2,volume=0.9[b1];
[a1][b1]amix=inputs=2:duration=first:normalize=0[aout]
  • BGM à fournir : vérifiez sa durée avec ffprobe ; si trop courte, utilisez -stream_loop -1. Utilisez des musiques libres de droits (lofi, CC0).
  • Image de couverture : extrayez l’image centrale du segment le plus stable, superposez le titre PIL, 720×1280, sauvegardez en PNG/JPG.

6. Structure de sortie

  • dossier_sources/stabilites/ ← tous les segments stables + rapport_analyse.json + classement_stabilite.md + video_finale_titre+BGM.mp4 + couverture_720x1280.png
  • Fichiers intermédiaires _norm/ et PNG temporaires supprimés après usage

Problèmes courants

  1. Concat demuxer avec chemins chinois/espaces : ffmpeg renvoie Illegal byte sequence. Solution : utiliser des noms ASCII et un fichier concat.txt en chemin relatif (comme ci-dessus).
  2. xfade exige que les deux entrées aient exactement les mêmes spécifications (résolution, framerate, format pixel, taux d’échantillonnage, nombre de canaux) — l’étape 4 de normalisation résout ce problème.
  3. Affichage chinois en console sous Windows (΢, ????) : n’affecte pas les fichiers générés (les noms sont corrects) ; vérifiez avec ls ou dir.
  4. Le temps d’analyse est linéaire avec la durée des vidéos ; pour quelques vidéos de 1 à 4 minutes tournées à main levée, le processus complet (analyse + découpage + assemblage) prend environ 3 à 5 minutes.
  5. N’utilisez pas drawtext pour les titres chinois (voir étape 5) : générez un PNG transparent avec PIL et superposez-le avec overlay.

Skills associés