Communitygithub.com

stable-video-cut

Detect and extract stable segments from raw handheld footage using only ffmpeg + Python, then assemble them into a polished final video with transitions.

¿Qué es stable-video-cut?

Esta skill permite extraer automáticamente los fragmentos más estables de uno o varios videos grabados a mano (por ejemplo, con teléfonos móviles), cortarlos y unirlos en un video final con transiciones fluidas, todo ello utilizando exclusivamente ffmpeg y Python (numpy). Es ideal para situaciones donde se necesita seleccionar rápidamente los segmentos aprovechables de material inestable, como grabaciones de fábricas, demostraciones de productos o videos de casos de estudio. La skill analiza la variación entre fotogramas para identificar partes estables, las ordena por nivel de estabilidad y las combina con transiciones xfade, añadiendo opcionalmente títulos y música de fondo generados con Python/Pillow. Funciona en Windows, macOS y Linux, y está diseñada para agentes como Claude Code, Cursor y Codex, que pueden ejecutar los scripts de análisis y edición sin necesidad de un software de edición de video tradicional.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace stable-video-cut?

Detecta y extrae automáticamente fragmentos "estables" de uno o varios vídeos grabados a mano, los corta, los ordena por estabilidad y los ensambla en un vídeo final con transiciones. Solo necesita ffmpeg + Python (numpy), sin ningún programa de edición de vídeo.

Cuándo usarlo

  • "Busca fragmentos estables y córtalos / Hay demasiado movimiento, elige los más estables"
  • "Combina estos clips en un solo vídeo y añade transiciones en las uniones"
  • Vídeos de fábrica, demostraciones de productos o casos de estudio grabados con teléfono o a mano, donde se necesitan segmentos directamente utilizables

Dependencias del entorno

  • ffmpeg / ffprobe: primero ejecuta which ffmpeg ffprobe (o where ffmpeg) para confirmar que están instalados. En Windows usa winget (winget install Gyan.FFmpeg) o descárgalo desde gyan.dev; en Mac, brew install ffmpeg. Los comandos siguientes usan los nombres ejecutables ffmpeg / ffprobe; si no están en PATH, exporta FF=/ruta/a/ffmpeg y FP=/ruta/a/ffprobe y luego usa "$FF" etc.
  • Python 3 + numpy (python --version / python -c "import numpy" para confirmar; si falta, pip install numpy).
  • Pillow para los títulos de portada (pip install pillow).

Flujo de trabajo

1. Explorar los materiales

Ejecuta ffprobe en cada vídeo para obtener resolución, FPS y duración:

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

Anota las especificaciones de cada clip: deben unificarse antes del ensamblaje (paso 4).

2. Análisis de estabilidad + corte

Guarda el siguiente script en la carpeta de materiales (por ejemplo, _stability_cut.py) y ejecútalo. Realiza: análisis de diferencia entre fotogramas → umbral adaptativo para encontrar segmentos estables → corte a mp4 (con audio original) → genera stable_cuts/analysis_report.json.

Los parámetros clave están al inicio del archivo; ajústalos según sea necesario:

import subprocess, numpy as np, os, json, shutil
SRC = r"E:\tu_carpeta_de_materiales"          # Cambia a la ruta real
OUT = os.path.join(SRC, "stable_cuts")
FF  = shutil.which("ffmpeg")                   # Si no está en PATH, pon la ruta real
FPS = 5          # Fotogramas por segundo para el análisis: más alto = más preciso pero más lento
W   = 160        # Ancho de la imagen en escala de grises para el análisis
MIN_SEC = 4.0    # Duración mínima de un segmento estable (segundos)
TOP_N = 4        # Número máximo de segmentos por vídeo original
THR_PCT = 45     # Percentil para el umbral adaptativo (menor = más estables pero menos segmentos)

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))   # Diferencia media entre fotogramas consecutivos = fluctuación
    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()))   # Ordenar por estabilidad
    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)
    report[name]=[{"segment":i,"start":a/FPS,"end":b/FPS,"duration_s":(b-a)/FPS,
                   "fluctuation":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(report, open(os.path.join(OUT,"analysis_report.json"),"w",encoding="utf-8"), ensure_ascii=False, indent=2)

3. Tabla global de estabilidad

Compila todos los segmentos de todos los vídeos en una sola tabla ordenada ascendentemente por fluctuation (rango, vídeo original, intervalo de tiempo, duración, uso recomendado) y escríbela como stable_cuts/global_stability_ranking.md.

Consejos:

  • Un valor de fluctuación más bajo indica mayor estabilidad, pero es relativo a cada vídeo. Sirve como referencia para ordenar, no como valor absoluto.
  • "¿Qué clip usar principalmente?" suele ser el de menor fluctuación; el más largo y estable es ideal como toma principal.
  • Si la mayoría de los segmentos estables son cortos (<4s), aumenta THR_PCT a 55-60 y vuelve a ejecutar.

4. Unificar especificaciones + ensamblaje con transiciones

Primero normaliza todos los segmentos (resolución, FPS y parámetros de audio deben ser idénticos para que xfade funcione):

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
  • Para material vertical usa 720:1280; horizontal 1280:720; cuadrado 1080:1080.
  • Si el original es más nítido que el destino, force_original_aspect_ratio=decrease lo escala para que quepa dentro del marco, y pad agrega bordes negros centrados, sin deformar.
  • Los archivos normalizados deben tener nombres ASCII (01.mp4…) dentro de la subcarpeta _norm/ para evitar problemas con rutas con caracteres chinos en concat.

Ensamblaje con xfade con 12 segmentos y transiciones de 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]

Fórmula para offset (con duración de transición d y duración de cada clip D1..Dn):

o1 = D1 - d
o2 = o1 + D2 - d
o3 = o2 + D3 - d   # Acumulativo: duración del clip anterior - d

Obtén D con ffprobe exactamente (algunos dan valores como 16.400023, no uses 16.4 manualmente). Duración total = ΣDi - (n-1)·d.

Para el audio, usa acrossfade para fundir sincronizadamente y evitar clics en las uniones. Todo en un solo filter_complex, no uses concat demuxer (no permite transiciones).

Transiciones recomendadas (elige diferentes cada vez para evitar monotonía): fade (fundido, la más segura), fadeblack (para cambios de sección/final), slideleft/slideright/smoothleft, circleopen, radial, hlslice, zoomin. Para 11 o más segmentos, coloca fadeblack en los puntos 4-5 y al final para agrupar.

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

5. Título de portada + música de fondo (empaquetado final)

Truco clave: genera los textos del título como PNG transparente con PIL, no uses drawtext para chino – drawtext en Windows es muy propenso a errores con rutas y caracteres especiales (: requiere escapado \:, textfile no acepta espacios/chinos, filter_complex_script desapareció en ffmpeg 9). PIL funciona a la primera:

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # Microsoft YaHei Bold, compatible con chino; en Linux/macOS usa Source Han Sans, etc.
img = Image.new("RGBA", (720, 1280), (0,0,0,0))
d = ImageDraw.Draw(img)
fnt = ImageFont.truetype(F, 62)
# Dibuja sombra primero, luego texto principal para asegurar legibilidad sobre fondos claros/oscuros
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")

Superpón en el vídeo (fade in/out durante los primeros 4.5s, PNG transparente con loop para 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]

Mezcla de BGM (volumen original reducido a 0.45, BGM a 0.9, fade in/out de 1-2s):

[0:a]volume=0.45[a1];
[1:a]atrim=0:<duration_total>,afade=t=in:d=1,afade=t=out:st=<duration_total-2>:d=2,volume=0.9[b1];
[a1][b1]amix=inputs=2:duration=first:normalize=0[aout]
  • Prepara tu propio BGM: usa ffprobe para ver su duración; si es más corta que el vídeo, usa -stream_loop -1 para repetir. Asegúrate de usar música libre de derechos (ej. lofi/CC0).
  • Imagen de portada: toma el fotograma central del segmento más estable, superpón el mismo título con PIL, 720×1280, guarda como PNG/JPG.

6. Convenciones de salida

  • carpeta_materiales/stable_cuts/ ← segmentos estables + analysis_report.json + global_stability_ranking.md + video_final_title+BGM.mp4 + cover_720x1280.png
  • Los archivos intermedios normalizados _norm/ y los PNG temporales se eliminan al finalizar.

Problemas comunes

  1. Concat demuxer + rutas con chino/espacios: ffmpeg da error Illegal byte sequence. La solución son los archivos intermedios ASCII + concat.txt con rutas relativas como se explicó.
  2. xfade exige que ambas entradas tengan exactamente las mismas especificaciones (resolución, FPS, formato de píxel, tasa de muestreo, número de canales; de lo contrario da error o resultados incorrectos): la normalización del paso 4 soluciona esto.
  3. En Bash de Windows, los caracteres chinos pueden aparecer como ΢ o ????: no afecta a los archivos de salida reales (los nombres son correctos), solo es un problema de visualización en la consola; no te alarmes, verifica con ls.
  4. El tiempo de análisis es lineal con la duración del vídeo. Para varios clips de 1-4 minutos grabados a mano, todo el proceso (análisis + corte + ensamblaje) toma unos 3-5 minutos.
  5. No uses drawtext para títulos en chino (ver paso 5), genera un PNG transparente con PIL y superponlo con overlay: es más fiable.

Skills relacionados