Edição de vídeo
Você é o editor. O usuário fornece apenas a filmagem; você a assiste (contact sheets + transcrição), decide a história e o corte, escreve uma EDL, renderiza, revisa sua própria renderização e itera até ficar bom. Faça perguntas apenas quando uma escolha for genuinamente deles e não puder ser inferida (veja "Defaults").
Os scripts ficam em .claude/skills/video-edit/scripts/ (execute-os com python3). Requisitos:
ffmpeg, Python 3 com numpy, opencv-python, Pillow; faster-whisper para transcrições
(pip3 install --user faster-whisper; o modelo é baixado no primeiro uso). Opcional: rembg
para recortes mais limpos em introduções de personagens.
Fluxo de trabalho
1. Configurar uma pasta de trabalho dentro do projeto
Coloque tudo em edits/<job-name>/ no projeto atual (não em /tmp): as ferramentas de arquivo
só podem ler imagens dentro do projeto, e você precisa olhar as contact sheets.
J=edits/<job-name>; mkdir -p $J
S=.claude/skills/video-edit/scripts
2. Analisar (assistir à filmagem)
python3 $S/analyze.py IN1.mp4 IN2.mov ... --out $J/work [--music song.mp3] [--lang zh] [--model small]
--model:baseé rápido,small(padrão) é um bom equilíbrio,large-v3para áudio difícil.- Filmagens longas (> 20 min no total) levam minutos; execute em segundo plano.
- Adicione
--no-transcribepara filmagens sem fala significativa.
Em seguida, leia $J/work/summary.md e abra cada contact sheet em $J/work/sheets/ com a
ferramenta Read. Cada tile é rotulado como v<n> s<shot> m:ss.xx. A partir disso, escreva para si mesmo um breve
registro de conteúdo: quem/o que/onde, os melhores momentos (com timestamps), planos fracos (borrados,
escuros, instáveis, duplicados), o que é dito e a ordem natural da história. Se precisar de uma
olhada mais de perto em um momento, extraia frames:
python3 $S/preview.py IN.mp4 --at 12.5 13.0 13.5 --every 999 --out $J/work/look
analysis.json tem todos os dados: lista de planos com motion / brightness / sharpness / colorfulness / loudness_db / score, audio.silences, audio.speech_spans, segmentos de transcrição
com timings de palavras e, para música, bpm, beats, strong_beats, drops.
Corrija erros de ASR antes da legendagem: palavras ouvidas erradas vão em subtitles.replace; palavras
faltantes ou com timing errado são corrigidas no próprio analysis.json (mantenha uma cópia do original).
Verifique nomes, números e qualquer palavra que as legendas destacarão.
2b. Quando perguntado no que a filmagem pode se tornar: o menu de estilos
python3 $S/styles.py $J/work/analysis.json [--exclude 588-708 v2:0-5]
Escreve work/styles.md: características da filmagem (densidade de diálogo, falas citáveis, ação, rostos,
close-ups, retratos estáticos, planos abertos calmos, planos escuros/neon, áudio com qualidade musical) e uma pontuação
por estilo com razões, planos de apoio e lacunas. Primeiro olhe as contact sheets e exclua
créditos, claquetes e filmagens de teste (--exclude, segundos). Depois verifique os principais estilos contra
o que você viu, remova ou adicione estilos a critério, e apresente o menu: por estilo, uma linha de
"como seria" (história / aparência), formato e duração, e o que está faltando. Ofereça-se para cortar
vários; cada estilo escolhido recebe seu próprio plano (etapa 3).
3. Projetar a edição: escreva $J/plan.md antes de qualquer EDL
Nunca vá da filmagem diretamente para uma EDL. Escolha uma abordagem de
reference/editing-playbook.md, depois escreva o plano com esta estrutura:
# Plano de edição: <job>
Objetivo / público / plataforma: ... Formato: 9:16 1080x1920, ~30 s, crop ajustado
Logline: <a história deste vídeo em uma frase>
## Estrutura
| # | Seção | Tempo | Imagem (v/plano @ tempo fonte) | Som (diálogo / música / SFX) | Texto |
|---|---|---|---|---|---|
| 1 | Gancho | 0-3 s | v1 s12 @ 41.2 melhor reação | "linha..." + boom | título |
## Música
Faixa, offset, BPM, onde o drop / hits caem (pins), o que está sincronizado com a batida
## Aparência
Correção de cor, correções por plano, transições e orçamento de efeitos (quais cortes recebem acentos)
## Texto
Estilo de legenda (simples / karaokê / bilíngue), títulos, cartelas, introduções de personagens
## Riscos / perguntas em aberto
Filmagem fraca, cobertura faltante, licença/atribuição, coisas que o usuário deve decidir
Em seguida, mostre ao usuário um breve resumo do plano (logline, estrutura em poucas linhas, duração,
formato, música) e prossiga, a menos que algo mude o resultado e não possa ser
inferido (propósito, plataforma/aspecto, um limite de duração, qual pessoa é o sujeito): pergunte
isso, no máximo 3 perguntas, antes de renderizar. Se o usuário pediu para aprovar o plano primeiro,
espere. A EDL implementa o plano; quando você desviar durante a edição, atualize plan.md.
Atalho opcional para uma primeira passagem, depois refine manualmente:
python3 $S/draft_edl.py $J/work/analysis.json --mode jumpcut|montage --out $J/edl.json \
[--format 9:16|16:9|1:1|4:5|source] [--duration 30] [--music song.mp3] [--title "..."] [--grade cinematic]
jumpcut mantém a fala e remove silêncios (usa a transcrição); montage pega os
planos com maior pontuação e os sincroniza com a batida. Um rascunho nunca é a edição final: remova retakes,
preenchimento e erros que você encontrou na transcrição, reordene para a história, adicione
cortes de B-roll sobre a fala, punch-ins, títulos.
4. Escrever a EDL
Escreva $J/edl.json. Formato completo: reference/edl.md. Estrutura mínima:
{
"analysis": "work/analysis.json",
"output": {"path": "out/final.mp4", "width": 1080, "height": 1920, "fps": 30, "fit": "blur"},
"grade": "natural",
"clips": [
{"src": "v1", "in": 3.2, "out": 7.9, "effects": [{"type": "zoom_in", "amount": 0.08}]},
{"src": "v2", "in": 0.0, "out": 2.4, "transition": {"type": "fade", "duration": 0.3}}
],
"texts": [{"text": "Título", "start": 0.2, "end": 2.5, "style": "title"}],
"subtitles": {"enabled": true, "style": "caption"},
"music": [{"path": "song.mp3", "volume": 0.3, "duck": true}]
}
Os caminhos na EDL são relativos ao arquivo EDL. src pode ser v1, v2... (ids da análise).
5. Renderizar, depois revisar seu próprio corte
python3 $S/render.py $J/edl.json --draft # meia resolução, rápido: use durante a iteração
python3 $S/render.py $J/edl.json # final
Os clipes renderizados são armazenados em cache em $J/.render/clips/, então re-renderizações após pequenas alterações na EDL são
rápidas. O comando imprime a timeline (tempo de saída ↔ intervalo de origem) e escreve as folhas de revisão
em $J/.render/review/. Abra as folhas de revisão e verifique: enquadramento após a mudança
de aspecto (cortes de cabeça? use focus ou fit: "blur"), legibilidade do texto e sobreposição com
rostos, precisão das legendas (corrija palavras ouvidas erradas com subtitles.replace), quadros pretos/congelados,
ritmo, consistência da correção de cor. Também releia $J/.render/subtitles.json em relação à transcrição.
Corrija e re-renderize. Faça pelo menos uma passagem de revisão antes de relatar.
Você não pode ouvir o resultado, então a renderização final deve ser executada com --qa:
python3 $S/render.py $J/edl.json --qa # ou: python3 $S/qa.py OUT.mp4 --subs $J/.render/subtitles.json
Ele mede o loudness (alvo cerca de -14 LUFS) e o pico verdadeiro (≤ -1 dBFS), lista longos silêncios,
e re-transcreve a saída para verificar se cada legenda ainda é reconhecível na mixagem.
Uma linha abaixo de 60 % provavelmente está mascarada por música/SFX, muito baixa, ou cortada por um corte ou um
congelamento: aumente o volume do clipe, abaixe ou duck a música, mova o corte, depois execute novamente. Leia
.render/qa.json (mostra o que foi ouvido) antes de decidir: uma incompatibilidade também pode ser um erro de ASR
ou uma legenda errada. Verifique também a timeline da --plan / last_render.json em relação às
batidas de música que você segmentou. Diga no handoff que a mixagem foi verificada por medição e
peça ao usuário para ouvir.
6. Entregar
Outras plataformas a partir da mesma edição:
python3 $S/render.py $J/edl.json --formats 16:9,9:16,1:1 --qa
Cada formato recebe sua própria saída (nome_9x16.mp4, ...): alvos mais estreitos mudam para
cortes com rastreamento facial, as legendas são reposicionadas e re-embrulhadas, as caixas de introdução são re-detectadas.
Coloque ajustes por formato em "formats": {"9:16": {...}} na EDL e revise todos os formatos.
Forneça ao usuário: o caminho da saída, duração/formato, uma descrição do corte em 3-6 linhas (história,
momentos-chave usados, efeitos, música), o caminho do .srt se as legendas foram criadas, e qualquer coisa em
plan.md que mudou ou não pôde ser feita. Ofereça
alternativas que valem a pena tentar (outra duração, outro formato, música diferente) em uma linha.
Mantenha edl.json: alterações posteriores são edições nele mais uma re-renderização.
Defaults (quando o usuário não diz)
- Formato: mesma orientação da maior parte da filmagem. "短视频 / 抖音 / Reels / Shorts / 小红书" ⇒ 9:16 1080x1920; "B站 / YouTube" ⇒ 16:9 1920x1080.
- Duração: talking head ⇒ todo o conteúdo significativo, apertado. Montagem / destaque ⇒ 15-45 s. Curta para redes sociais ⇒ menos de 60 s.
- Legendas: ligadas sempre que houver fala (embutidas, além de
.srt). - Música: apenas se o usuário a forneceu ou a filmagem não tem nenhuma e o usuário pediu música.
Nunca invente uma fonte de música; se a música claramente ajudaria e nenhuma foi fornecida, diga isso no
handoff. A fala original sempre permanece inteligível (
duck: true, volume 0,15-0,35). - Correção de cor:
naturalpara pessoas/fala;cinematicouteal_orangepara viagem/montagem; mantenha uma correção de cor por vídeo, a menos que uma mudança seja um efeito deliberado. - Loudness: -14 LUFS (definido automaticamente).
- Idioma do texto na tela: o idioma falado na filmagem / usado pelo usuário.
Pegadinhas
in/outsão segundos da fonte; a duração na tela é(out-in)/speed(+freeze).- Uma transição xfade sobrepõe dois clipes por sua duração, encurtando o total. Mantenha transições ≤ 0,5 s e mais curtas do que ambos os clipes vizinhos.
- As legendas vêm da transcrição e seguem cortes e mudanças de velocidade automaticamente; clipes sem áudio ou
invertidos não recebem legendas. Legendas manuais:
subtitles.items. - Edições baseadas em música: defina o
offsetda base para que seu drop caia onde você quer, sincronize combeat_synco intervalo de ação, fixe momentos-chave comstart_at_music, verifique com--plan. Veja a receita de trailer no playbook. - SFX sintetizados (
soundscomsfx) não precisam de arquivos de amostra; mantenha-os abaixo da música, exceto em drops e no título. - Introduções de personagens (efeito
{"type": "intro"}) congelam o clipe emat; o clipe fica mais longo porhold, as legendas pausam durante o congelamento.boxestá em coordenadas do frame de saída (após crop/pad); omita para encontrar a pessoa a partir do rosto. Close-ups extremos recebem automaticamente o visual sem recorte. Escolha um quadro onde a pessoa esteja parada e claramente separada do fundo (plano médio, rosto visível). - Legendas karaokê (
subtitles.karaoke) precisam de timings de palavras precisos: corrija a transcrição primeiro; legendas sem timings de palavras distribuem suas palavras uniformemente. - 3D: estilo
text3d(extrudado, gradiente na face,flip_in/swing,rotate_x/y) para títulos; efeito de clipetext_behindcoloca texto grande entre o fundo e a pessoa (rembg por frame, ~0,7 s/frame: limite a 3-5 s em planos estáticos);overlaysadicionam efeitos de luz three.js (particles,hologram,streaks,grid) renderizados por headless Chrome e mapeados por brilho, então eles adicionam luz como uma mesclagem de tela. Use-os como acentos, não em todos os planos. - Prefira ancorar textos e legendas manuais a clipes (
"clip": icomstart/end, ousrc_start/src_endem segundos da fonte) em vez de tempos absolutos de saída: eles permanecem corretos quando os clipes são cortados, reordenados ou as transições mudam. beat_syncreescreve os pontosoutdo clipe para que os cortes caiam nas batidas; definaevery: 2ou4para um ritmo mais lento.- Esta versão do ffmpeg pode não ter
drawtext/libass; todo o texto é desenhado pelo Pillow, então qualquer fonte que o Pillow possa abrir funciona (output.fontoufontpor texto). - Saída vertical a partir de filmagem horizontal:
fit: "crop"comfocus: "track"(o crop se move para seguir o rosto principal, ou o corpo em planos mais abertos;track_hint: "left"|"right"|xescolhe a pessoa em um plano de dois);"auto"(uma posição estática centrada no rosto) ou[x, y]; oufit: "blur"para manter a imagem inteira. O tracking volta a um crop estático quando pessoas são encontradas em menos de 30 % das amostras (planos muito abertos): definafocusmanualmente nesses casos. - Introduções com frame congelado são movidas para fora das palavras automaticamente (o áudio pausa durante o congelamento); o log diz quando.