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(ouwhere ffmpegsur Windows). Windows :winget install Gyan.FFmpegou téléchargement depuis gyan.dev ; Mac :brew install ffmpeg. Les commandes utilisentffmpeg/ffprobesans chemin absolu ; si hors PATH, exportezFF=/chemin/vers/ffmpeg,FP=/chemin/vers/ffprobeet 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=decreaseréduit pour tenir dans le cadre,padajoute 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
- 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). - 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.
- Affichage chinois en console sous Windows (
,????) : n’affecte pas les fichiers générés (les noms sont corrects) ; vérifiez aveclsoudir. - 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.
- N’utilisez pas drawtext pour les titres chinois (voir étape 5) : générez un PNG transparent avec PIL et superposez-le avec overlay.