Communitygithub.com

stable-video-cut

Analisa automaticamente trechos estáveis de um ou mais vídeos brutos, recorta-os e os une em uma sequência ordenada por estabilidade com transições, usando apenas ffmpeg e Python (numpy), sem necessidade de software de edição.

O que é stable-video-cut?

O stable-video-cut é uma skill para agentes de IA que automatiza a seleção de trechos estáveis de vídeos gravados à mão (como em fábricas, demonstrações de produtos ou cases), eliminando a necessidade de editores tradicionais. A skill utiliza apenas ferramentas de linha de comando (ffmpeg, ffprobe) e Python com numpy para analisar a estabilidade quadro a quadro, detectar segmentos com baixa variação de movimento e recortá-los. Os trechos são então classificados por estabilidade e concatenados em um vídeo final com transições suaves (xfade e acrossfade). Suporta plataformas como Claude Code, Codex e Cursor, e é ideal para cenários onde o usuário precisa de trechos prontos para uso, sem tremores, de forma rápida e programática. Todo o processo é descrito em detalhes no SKILL.md, incluindo scripts Python e comandos ffmpeg, garantindo reprodutibilidade e personalização (parâmetros como taxa de quadros de análise, limiar de estabilidade, duração mínima dos trechos, etc.).

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que stable-video-cut faz?

A partir de um (ou mais) vídeos brutos, encontra automaticamente os trechos com "imagem estável", recorta-os e os une em uma sequência ordenada por estabilidade com transições, resultando em um vídeo final. Usa apenas ffmpeg + Python (numpy), sem necessidade de qualquer software de edição.

Quando usar

  • "Encontre trechos estáveis e corte-os / o vídeo está muito tremido, filtre os estáveis"
  • "Una esses materiais em um único vídeo, adicione transições nas emendas"
  • Vídeos de fábrica, demonstrações de produtos ou cases gravados com celular/câmera na mão, que precisam de trechos prontos para uso

Dependências

  • ffmpeg / ffprobe: Execute which ffmpeg ffprobe (ou where ffmpeg) para confirmar a instalação. No Windows, use winget (winget install Gyan.FFmpeg) ou baixe de gyan.dev; no Mac, use brew install ffmpeg. Os comandos abaixo usam ffmpeg / ffprobe como nomes de executáveis (sem caminhos absolutos); se não estiverem no PATH, exporte FF=/caminho/para/ffmpeg e FP=/caminho/para/ffprobe e use "$FF" etc.
  • Python 3 + numpy (python --version / python -c "import numpy" para confirmar; se faltar, pip install numpy).
  • Para títulos de capa, também precisa do Pillow (pip install pillow).

Fluxo

1. Análise do material

Para cada vídeo, execute ffprobe para obter resolução, taxa de quadros e duração:

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

Registre as especificações de cada vídeo – os vídeos devem ser unificados antes da concatenação (passo 4).

2. Análise de estabilidade + corte

Salve o script abaixo no diretório dos materiais (por exemplo, _stability_cut.py) e execute-o; ele realiza: análise de diferença entre quadros → identificação adaptativa de trechos estáveis → corte em mp4 (com áudio original) → geração de estaveis/relatorio_analise.json.

Os parâmetros principais estão no início do arquivo; ajuste conforme necessário:

import subprocess, numpy as np, os, json, shutil
SRC = r"E:\SuaPastaDeMateriais"          # Altere para o caminho real
OUT = os.path.join(SRC, "estaveis")
FF  = shutil.which("ffmpeg")              # Se não estiver no PATH, coloque o caminho real
FPS = 5          # Taxa de quadros da análise: quanto maior, mais preciso, porém mais lento
W   = 160        # Largura da imagem em escala de cinza para análise
MIN_SEC = 4.0    # Duração mínima dos trechos (em segundos)
TOP_N = 4        # Número máximo de trechos por vídeo original
THR_PCT = 45     # Percentil adaptativo = P45 da distribuição de diferenças do vídeo (quanto menor, mais estáveis e menos trechos)

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

relatorio={}
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))   # Diferença média entre quadros consecutivos = flutuação
    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 pelo mais estável
    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}_estavel{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)
    relatorio[name]=[{"trecho":i,"inicio":a/FPS,"fim":b/FPS,"duracao_s":(b-a)/FPS,
                   "flutuacao":round(float(S[a:b].mean()),2)} for i,(a,b) in enumerate(top,1)]
    print(name,"->",len(top),"trechos", [(f"{a/FPS:.1f}-{b/FPS:.1f}s",round(float(S[a:b].mean()),1)) for a,b in top])
json.dump(relatorio, open(os.path.join(OUT,"relatorio_analise.json"),"w",encoding="utf-8"), ensure_ascii=False, indent=2)

3. Montar "Tabela Geral de Estabilidade"

Agregue todos os trechos de todos os vídeos ordenados por flutuacao crescente em uma tabela (classificação, vídeo original, intervalo de tempo, duração, uso recomendado) e salve como estaveis/tabela_estabilidade_geral.md.

Experiência:

  • Quanto menor o valor de flutuação, mais estável, mas ele é relativo ao vídeo atual, servindo apenas como referência para ordenação entre vídeos, não como valor absoluto.
  • "Qual usar como destaque" geralmente é o trecho com menor flutuação; o trecho mais longo e estável é ideal como plano principal.
  • Se os trechos estáveis forem muito curtos (a maioria <4s), aumente THR_PCT para 55-60 e execute novamente.

4. Uniformização + concatenação com transição

Primeiro, normalize todos os trechos (resolução, taxa de quadros, e parâmetros de áudio devem ser idênticos para que o xfade não gere erros):

for f in trecho*.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, use 720:1280; para horizontal, 1280:720; para quadrado, 1080:1080.
  • Se a fonte for mais nítida que o destino, force_original_aspect_ratio=decrease reduz para caber no quadro, e pad adiciona bordas pretas centralizadas, sem distorcer.
  • Use nomes de arquivo ASCII (01.mp4…) no subdiretório _norm/ para evitar problemas de caminho com caracteres chineses na concatenação posterior.

Concatenação com xfade: Para 12 trechos com transição de 0,5s cada, o filtro é construído assim:

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

Fórmula para offset (duração da transição d, duração de cada trecho D1..Dn):

o1 = D1 - d
o2 = o1 + D2 - d
o3 = o2 + D3 - d   # ou seja: duração do trecho anterior - d, acumulando

Use ffprobe para obter a duração exata (alguns podem ser 16.400023, não calcule manualmente como 16.4). Duração total = ΣDi - (n-1)·d.

Áudio usa acrossfade para fade suave, evitando "estalos" nas emendas. Tudo em um único filter_complex, sem usar concat demuxer (que não permite transições).

Transições comuns (varie para evitar repetição): fade (dissolução, a mais segura), fadeblack (mudança de grupo/final), slideleft/slideright/smoothleft, circleopen, radial, hlslice, zoomin. Para 11 ou mais trechos, recomenda-se usar fadeblack na 4ª-5ª transição e na última, 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 na capa + trilha sonora (empacotamento final)

Dica principal: use PIL para gerar PNG transparente com o título, não use drawtext para caracteres chineses – drawtext no Windows é extremamente difícil de depurar com caminhos chineses (dois pontos precisam de \:, textfile não pode ter espaços/caracteres chineses, filter_complex_script não existe mais no ffmpeg 9), enquanto o PIL funciona de primeira:

from PIL import Image, ImageDraw, ImageFont
F = "C:/Windows/Fonts/msyhbd.ttc"        # Microsoft YaHei Bold, suporta chinês; no Linux/macOS use Noto Sans CJK etc.
img = Image.new("RGBA", (720, 1280), (0,0,0,0))
d = ImageDraw.Draw(img)
fnt = ImageFont.truetype(F, 62)
# Primeiro desenhe a sombra, depois o texto principal, para garantir legibilidade em fundos claros/escuros
d.text((x+3, y+3), "Linha de Higiene para Pets", font=fnt, fill=(0,0,0,160))
d.text((x, y), "Linha de Higiene para Pets", font=fnt, fill=(255,255,255,255))
img.save("titulo.png")

Sobreposição no vídeo (fade in/out de 4,5s, PNG transparente repetido com loop):

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

Mixagem de BGM (áudio original reduzido para 0.45, BGM a 0.9, fade in/out de 1-2s no início e fim):

[0:a]volume=0.45[a1];
[1:a]atrim=0:<duracao_total>,afade=t=in:d=1,afade=t=out:st=<duracao_total-2>:d=2,volume=0.9[b1];
[a1][b1]amix=inputs=2:duration=first:normalize=0[aout]
  • BGM: prepare o arquivo; use ffprobe para ver a duração; se for curta, use -stream_loop -1 para repetir. Lembre-se de usar músicas livres de direitos autorais (como lofi/CC0).
  • Imagem de capa: extraia o quadro central do trecho mais estável, sobreponha o título com PIL no mesmo tamanho 720×1280, salve como PNG/JPG.

6. Estrutura de saída

  • Diretório dos materiais/estaveis/ ← trechos estáveis + relatorio_analise.json + tabela_estabilidade_geral.md + video_final_titulo+BGM.mp4 + capa_720x1280.png
  • Arquivos intermediários normalizados em _norm/ e PNGs temporários (exclua após o uso)

Problemas comuns

  1. Concat demuxer + caminhos com caracteres chineses/espaços: ffmpeg gera erro Illegal byte sequence. A solução é usar arquivos intermediários com nomes ASCII e arquivo concat.txt com caminhos relativos.
  2. xfade exige que ambas as entradas tenham exatamente as mesmas especificações (resolução, taxa de quadros, formato de pixel, taxa de amostragem, número de canais — caso contrário, ocorre erro ou resultado incorreto) – a normalização do passo 4 resolve isso.
  3. No Bash do Windows, saída em chinês pode parecer ilegível (΢、????) mas não afeta os arquivos gerados (nomes estão corretos); é apenas um problema de exibição no console. Verifique com ls.
  4. O tempo de análise é linear com a duração do vídeo; para alguns vídeos de 1 a 4 minutos gravados à mão, todo o processo (análise + corte + concatenação) leva cerca de 3 a 5 minutos.
  5. Não use drawtext para títulos em chinês (veja passo 5); gere PNG transparente com PIL e sobreponha com overlay, que é mais confiável.

Habilidades Relacionadas