Communitygithub.com

edição-de-vídeo

Mostra a um agente como planejar, construir ou cortar uma 'edição de vídeo' de modo que a saída concreta seja um logo e uma pequena folha de identidade visual. O procedimento percorre Edição de vídeo, Fluxo de trabalho, 1. Configurar uma pasta de trabalho dentro do projeto. Use quando uma nova tarefa exigir este ofício.

O que é edição-de-vídeo?

Esta habilidade transforma um agente de IA em um editor de vídeo completo, capaz de analisar filmagens brutas, planejar a edição, criar uma EDL (Edit Decision List), renderizar e revisar o resultado final, tudo de forma autônoma. O agente começa assistindo ao material fornecido pelo usuário usando contact sheets e transcrições, decide a história e os cortes, escreve um plano detalhado de edição, gera a EDL em JSON e renderiza o vídeo final com ffmpeg. A habilidade suporta múltiplos formatos (9:16, 16:9, 1:1, etc.), legendas automáticas com correção de ASR, sincronização com música (detecção de BPM e batidas fortes), e inclui um sistema de revisão automática que verifica loudness, picos verdadeiros e inteligibilidade das legendas. É particularmente útil para agentes como Claude Code, Cursor ou Codex em tarefas de edição de vídeo repetitivas ou que exigem consistência, pois implementa um fluxo de trabalho completo desde a análise até a entrega, com defaults inteligentes e verificações de qualidade integradas.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fujiezee/cutvideo/tree/HEAD/.claude/skills/video-edit

Perguntar na sua IA favorita

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

Documentação

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-v3 para áudio difícil.
  • Filmagens longas (> 20 min no total) levam minutos; execute em segundo plano.
  • Adicione --no-transcribe para 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: natural para pessoas/fala; cinematic ou teal_orange para 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/out sã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 offset da base para que seu drop caia onde você quer, sincronize com beat_sync o intervalo de ação, fixe momentos-chave com start_at_music, verifique com --plan. Veja a receita de trailer no playbook.
  • SFX sintetizados (sounds com sfx) 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 em at; o clipe fica mais longo por hold, as legendas pausam durante o congelamento. box está 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 clipe text_behind coloca texto grande entre o fundo e a pessoa (rembg por frame, ~0,7 s/frame: limite a 3-5 s em planos estáticos); overlays adicionam 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": i com start/end, ou src_start/src_end em 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_sync reescreve os pontos out do clipe para que os cortes caiam nas batidas; defina every: 2 ou 4 para 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.font ou font por texto).
  • Saída vertical a partir de filmagem horizontal: fit: "crop" com focus: "track" (o crop se move para seguir o rosto principal, ou o corpo em planos mais abertos; track_hint: "left"|"right"|x escolhe a pessoa em um plano de dois); "auto" (uma posição estática centrada no rosto) ou [x, y]; ou fit: "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): defina focus manualmente 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.

Habilidades Relacionadas