Communitygithub.com

stable-video-cut

Extrahiert automatisch stabilste Segmente aus einer oder mehreren Rohaufnahmen, schneidet sie aus, sortiert sie nach Stabilität und montiert sie mit Übergängen zu einem fertigen Video – nur mit ffmpeg und Python (numpy). Keine Videobearbeitungssoftware nötig.

Was ist stable-video-cut?

Diese Fähigkeit (Skill) automatisiert die Videoproduktion aus handgehaltenen Aufnahmen, wie sie z. B. in Fabriken, bei Produktpräsentationen oder Kundenreferenzen anfallen. Sie analysiert die Bildsequenz auf Bewegungsunschärfe und Verwacklungen mittels Framedifferenzen, ermittelt die stabilsten Abschnitte und schneidet sie als einzelne Videoclips aus. Diese Clips werden nach steigendem Stabilitätsgrad sortiert, in einheitliches Format (Auflösung, Bildrate, Audio) normalisiert und mit ffmpeg's xfade-Filter nahtlos aneinander montiert – inklusive wählbarer Überblendungen. Ein optionaler letzter Schritt fügt eine Titelgrafik (erstellt mit Python PIL) und Hintergrundmusik hinzu, bei gleichzeitiger Absenkung des Originaltons. Die gesamte Pipeline kommt ohne teure Schnittsoftware aus und ist vollständig in Python mit numpy und ffmpeg realisiert. Der Skill eignet sich besonders für Anwender, die aus vielen verwackelten Rohaufnahmen schnell nutzbare, stabilisierte Sequenzen extrahieren und zu einem ansprechenden Endvideo kombinieren möchten – alles über die Kommandozeile und ideal für CI/CD oder lokale Batch-Verarbeitung.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht stable-video-cut?

Aus einer (oder mehreren) Rohaufnahmen automatisch die stabilsten Bildsegmente extrahieren, ausschneiden, nach Stabilität sortiert montieren und mit Übergängen versehen – nur mit ffmpeg + Python (numpy). Keine Schnittsoftware nötig.

Wann verwenden

  • „Finde stabile Stellen und schneide sie aus / zu viele Verwackler, wähle die ruhigen Sequenzen“
  • „Füge diese Aufnahmen zu einem Video zusammen, mit Überblendungen an den Schnitten“
  • Handy- oder handgeführte Aufnahmen von Fabriken, Produktdemos, Referenzvideos – brauchbare Passagen sollen automatisch isoliert werden

Voraussetzungen

  • ffmpeg / ffprobe: Mit which ffmpeg ffprobe (Linux/Mac) oder where ffmpeg (Windows) prüfen. Windows: winget install Gyan.FFmpeg oder Download von gyan.dev; Mac: brew install ffmpeg. Die Befehle verwenden ffmpeg/ffprobe ohne absoluten Pfad – falls nicht im PATH, setze FF=/pfad/zu/ffmpeg und FP=/pfad/zu/ffprobe und verwende "$FF" etc.
  • Python 3 + numpy: Prüfe mit python --version und python -c "import numpy" (fehlt numpy: pip install numpy).
  • Für Titelgrafiken zusätzlich Pillow (pip install pillow).

Ablauf

1. Aufnahmen analysieren (Metadaten)

Für jedes Video ffprobe laufen lassen, um Auflösung / Bildrate / Dauer zu ermitteln:

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

Spezifikationen der einzelnen Clips notieren – unterschiedliche Formate müssen vor dem Zusammenschnitt vereinheitlicht werden (Schritt 4).

2. Stabilitätsanalyse + Segmente ausschneiden

Das folgende Skript im Quellverzeichnis speichern (z. B. _stability_cut.py) und ausführen: Es führt eine Framedifferenzanalyse durch → adaptive Schwelle zur Erkennung stabiler Abschnitte → schneidet diese als mp4 (mit Originalton) aus → erzeugt StabilSchnitte/analysebericht.json.

Wichtige Parameter stehen am Skriptanfang und können nach Bedarf angepasst werden:

import subprocess, numpy as np, os, json, shutil
SRC = r"C:\DeinQuellordner"          # anpassen
OUT = os.path.join(SRC, "StabilSchnitte")
FF  = shutil.which("ffmpeg")        # falls nicht im PATH, absoluten Pfad eintragen
FPS = 5          # Abtastbildrate: höher = genauer, aber langsamer
W   = 160        # Breite des Grauwertbilds (Analyse)
MIN_SEC = 4.0    # Mindestlänge eines stabilen Segments (Sekunden)
TOP_N = 4        # max. Anzahl Segmente pro Originalvideo
THR_PCT = 45     # Perzentil der Framedifferenzen (niedriger = strenger, weniger Segmente)

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))   # Framedifferenz = Bewegung
    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()))   # nach Stabilität sortieren
    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}_stabil{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,"Ende":b/FPS,"Dauer_s":(b-a)/FPS,
                   "Bewegung":round(float(S[a:b].mean()),2)} for i,(a,b) in enumerate(top,1)]
    print(name,"->",len(top),"Segmente", [(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,"analysebericht.json"),"w",encoding="utf-8"), ensure_ascii=False, indent=2)

3. Stabilitäts-Rangliste erstellen

Alle Segmente aus allen Videos nach aufsteigender Bewegung sortiert in einer Tabelle zusammenfassen (Rang, Quelle, Zeitbereich, Dauer, Empfehlung) und als StabilSchnitte/stabilitaet_rangliste.md speichern.

Erfahrungswerte:

  • Niedrigerer Bewegungswert = stabiler, aber relativ zum jeweiligen Video; Quervergleiche nur als Richtwert nutzbar.
  • „Welches Video verwenden?“ → meist das mit dem niedrigsten Bewegungswert; das längste und stabilste Segment eignet sich als Hauptbild.
  • Falls viele stabile Segmente kürzer als 4 s sind, THR_PCT auf 55–60 erhöhen und erneut ausführen.

4. Normierung + Zusammenschnitt mit Überblendungen

Zuerst alle Segeme auf einheitliches Format bringen (Auflösung, Bildrate, Audioparameter müssen identisch sein, sonst gibt xfade Fehler):

for f in segment*.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
  • Hochkant-Material: 720:1280; Querformat: 1280:720; quadratisch: 1080:1080.
  • Ist das Quellvideo schärfer als die Zielauflösung, skaliert force_original_aspect_ratio=decrease passend hinein, pad zentriert mit schwarzen Balken – keine Verzerrung.
  • Normalisierte Dateien erhalten ASCII‑Namen (01.mp4 …) im Unterordner _norm/ – vermeidet Probleme mit chinesischen Pfaden im folgenden concat-Befehl.

xfade-Zusammenschnitt: Bei 12 Segmenten mit jeweils 0,5 s Überblendung wird der Filter wie folgt aufgebaut:

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

Offset-Berechnung (Überblendungsdauer d, Segmentlängen D1..Dn):

o1 = D1 - d
o2 = o1 + D2 - d
o3 = o2 + D3 - d   # also vorherige Ausgabelänge - d, schrittweise aufaddieren

Dauer D exakt mit ffprobe ermitteln (z. B. 16.400023 statt gerundet 16.4). Gesamtlänge = ΣDi - (n-1)·d.

Audio mit acrossfade synchron überblenden, um Knackser an den Schnitten zu vermeiden. Alles in einem filter_complex erledigen – nicht den concat-Demuxer verwenden (der keine Überblendungen unterstützt).

Gängige Überblendungen (jeweils abwechseln, um Monotonie zu vermeiden): fade (sicherste Wahl), fadeblack (für Gruppenwechsel/Ende), slideleft/slideright/smoothleft, circleopen, radial, hlslice, zoomin. Bei 11+ Segmenten fadeblack an Position 4–5 und am Ende einsetzen, um Gruppen zu bilden.

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

5. Titelgrafik + Hintergrundmusik (Endbearbeitung)

Kern-Tipp: Titeltext mit PIL als transparentes PNG erzeugen, nicht mit drawtext für chinesische Zeichen verwenden – drawtext unter Windows ist mit chinesischen Pfaden extrem fehleranfällig (Doppelpunkte escapen, textfile-Pfad ohne Leerzeichen/Chinesisch, filter_complex_script in ffmpeg 9 nicht mehr vorhanden). PIL funktioniert auf Anhieb:

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # Microsoft YaHei Bold (chinesisch; Linux/Mac: Noto Sans CJK o. ä.)
img = Image.new("RGBA", (720, 1280), (0,0,0,0))
d = ImageDraw.Draw(img)
fnt = ImageFont.truetype(F, 62)
# Erst Schatten, dann Text – so auf hellem und dunklem Hintergrund lesbar
d.text((x+3, y+3), "Haustierpflege-Fließband", font=fnt, fill=(0,0,0,160))
d.text((x, y), "Haustierpflege-Fließband", font=fnt, fill=(255,255,255,255))
img.save("titel.png")

Im Video einblenden (erste 4,5 s mit fade-in/fade-out, transparentes PNG mit loop auf 4,5 s gestreckt):

[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-Mischung (Originalton auf 0.45, BGM auf 0.9, jeweils 1–2 s fade-in/fade-out an Anfang/Ende):

[0:a]volume=0.45[a1];
[1:a]atrim=0:<Gesamtlaenge>,afade=t=in:d=1,afade=t=out:st=<Gesamtlaenge-2>:d=2,volume=0.9[b1];
[a1][b1]amix=inputs=2:duration=first:normalize=0[aout]
  • BGM selbst bereitstellen: Mit ffprobe die Länge prüfen, bei Bedarf mit -stream_loop -1 loopen. Auf lizenzfreie Musik achten (z. B. Lofi/CC0).
  • Titelbild: Mittelsten Frame des stabilsten Segments extrahieren, mit demselben PIL-Titel versehen, 720×1280, als PNG/JPG speichern.

6. Ausgabe-Konvention

  • Quellverzeichnis/StabilSchnitte/ ← alle stabilen Segmente + analysebericht.json + stabilitaet_rangliste.md + endvideo_titel+BGM.mp4 + cover_720x1280.png
  • Normierungs-Zwischendateien _norm/ und temporäre PNGs nach Abschluss löschen

Häufige Fallstricke

  1. concat-Demuxer + chinesische/Leerzeichen-Pfade: ffmpeg meldet Illegal byte sequence. Lösung: ASCII-Zwischendateien wie oben beschrieben und relativen Pfad in concat.txt verwenden.
  2. xfade erfordert exakt gleiche Formate (Auflösung, Bildrate, Pixelformat, Abtastrate, Kanalzahl – sonst Fehler oder falsches Ergebnis) → Die Normierung in Schritt 4 ist dafür da.
  3. Bash unter Windows: chinesische Ausgabe als Müll („΢“, „????“) – betrifft nur die Konsolenausgabe, die tatsächlichen Dateinamen sind korrekt. Mit ls überprüfen.
  4. Die Analysezeit skaliert linear mit der Videolänge; bei mehreren 1–4 Minuten langen Handyclips dauert der ganze Durchlauf (Analyse + Schnitt + Montage) etwa 3–5 Minuten.
  5. Chinesische Titel nicht mit drawtext (siehe Schritt 5), sondern mit PIL als transparentes PNG erzeugen und per overlay einblenden.

Verwandte Skills