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(ouwhere ffmpeg) para confirmar a instalação. No Windows, use winget (winget install Gyan.FFmpeg) ou baixe de gyan.dev; no Mac, usebrew install ffmpeg. Os comandos abaixo usamffmpeg/ffprobecomo nomes de executáveis (sem caminhos absolutos); se não estiverem no PATH, exporteFF=/caminho/para/ffmpegeFP=/caminho/para/ffprobee 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_PCTpara 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=decreasereduz para caber no quadro, epadadiciona 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 -1para 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
- 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. - 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.
- 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 comls. - 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.
- 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.