pro-video-editing

Edição de Vídeo Profissional

Esta skill tem três partes que trabalham juntas:

1. Juízo editorial: o que cortar, onde e por quê, para que o resultado pareça feito por uma pessoa com bom gosto, não montado por uma máquina.
2. O editor (vedit): um editor de timeline pequeno que você opera inteiramente pela linha de comando. Cortes, títulos, fades, efeitos sonoros e presets de voz passam por ele, e a pessoa pode abrir o mesmo projeto em um navegador.
3. Ferramentas de som: indexar uma biblioteca de efeitos sonoros, pesquisá-la e posicionar sons para que o impacto caia no quadro exato.

Os caminhos abaixo são relativos à pasta desta skill. As ferramentas precisam de Python 3.9+ e FFmpeg 5+ (nada mais para instalar).

Seja honesto sobre o que você pode e não pode fazer

• Você não pode ouvir áudio nem assistir vídeo. Julgue por medição (transcrições, detecção de cena e silêncio, scripts/qc_audio.py) e diga isso. Após a renderização, nomeie dois ou três timestamps para o usuário verificar ouvindo.
• Nunca invente nomes ou IDs de arquivos de som. Use apenas IDs retornados por scripts/sfx_search.py.
• Se scripts/sfx_search.py --stats disser que não há catálogo, a biblioteca de sons ainda não foi configurada. Ofereça a configuração única abaixo e aguarde um sim antes de baixar. Se o usuário recusar ou falhar, faça o trabalho editorial mesmo assim e aponte para references/sfx-library-setup.md. Nunca baixe nenhuma outra biblioteca de sons por conta própria.

Princípios básicos (a versão resumida)

Texto completo com exemplos: references/editorial-principles.md. Leia antes de cortar ou revisar um corte.

1. Emoção primeiro. Pergunte o que o espectador deve sentir em cada ponto. Se ele sente isso durante todo o tempo, a edição funciona.
2. Hierarquia de corte. Quando um corte não pode satisfazer tudo, abra mão de itens do final desta lista primeiro: emoção, história, ritmo, rastreamento visual, planaridade, continuidade espacial. Nunca troque um item superior por um inferior.
3. Corte onde um pensamento termina, no momento em que um espectador piscaria. Um ponto de corte deve ser um possível ponto de piscada.
4. Faça o máximo com o mínimo. Sugestão vence exposição. Menos escolhas, melhores. Não cortar também é uma decisão.
5. Julgue apenas o que está na tela. Ignore esforço, custo e intenção.
6. Desvie a atenção como um mágico: decida para onde o olho vai e faça o próximo plano encontrá-lo.
7. Diagnostique antes de consertar. Um problema geralmente está antes de onde os espectadores dizem que o sentiram.

Fluxo de trabalho

Etapa	O que fazer	Referência
1. Captação	Confirmar o entregável (plataforma, proporção, fps, duração) e a intenção em uma frase.	technical-pipeline.md
2. Registro	Indexar todo o material: transcrição com tempos das palavras, tipo de plano, silêncios, melhores takes. Escolher um quadro representativo por configuração.	editorial-principles.md
3. Montagem	Construir a história em ordem com o melhor material. Estrutura antes do polimento.	editorial-principles.md
4. Refinamento	Aplicar a hierarquia de corte e o tempo de piscada. Revisitar material rejeitado após a primeira passada completa.	editorial-principles.md
5. Som	Localizar, pesquisar, colocar e mixar SFX.	sfx-placement.md
6. Verificação	Assistir direto como uma audiência. Executar o script de QC.	abaixo
7. Entrega	Religar à qualidade total, equalizar cor/níveis, exportar primeiro um master.	technical-pipeline.md

Ao devolver o trabalho, informe: a intenção para a qual editou, as principais escolhas estruturais, o que removeu e por quê, compromissos conhecidos e alternativas que valem a pena tentar.

O editor (vedit)

Use-o para realmente fazer a edição. Leia references/editor.md primeiro; ele tem todos os comandos, o formato do projeto e um método de trabalho. O essencial:

python3 editor/vedit.py new myfilm --size 1920x1080          # uma pasta de projeto (use `python` no Windows se python3 não existir)
python3 editor/vedit.py -p myfilm settings --preset vertical # canvas para o destino (Reels/TikTok/Shorts); também --lufs -14
python3 editor/vedit.py -p myfilm analyze clip.mp4           # silêncios e mudanças de cena, para escolher cortes
python3 editor/vedit.py -p myfilm import clip.mp4            # imprime um id de asset como a1
python3 editor/vedit.py -p myfilm add a1 --in 12.5 --dur 8   # colocar 8 s dele na timeline
python3 editor/vedit.py -p myfilm grade c1 --look cinematic  # cor; também --brightness --contrast --saturation --temperature --lut FILE
python3 editor/vedit.py -p myfilm key c1 scale --at 0 --value 1; python3 editor/vedit.py -p myfilm key c1 scale --at 8 --value 1.15 --ease inout   # zoom lento
python3 editor/vedit.py -p myfilm transition c1 c2 --type dissolve --dur 0.5
python3 editor/vedit.py -p myfilm key c1 speed --at 0 --value 1   # rampa de velocidade: adicione mais keyframes em `speed` (o som do clipe é mutado); também: reverse c1, freeze c1 --at 4 --dur 2
python3 editor/vedit.py -p myfilm tracker add c1 --at 4 --x 0.6 --y 0.3   # seguir um ponto; depois: mask c1 --effect blur, follow c1 m1 t1 (desfocar um rosto) ou attach c2 t1 (um título sobre ele)
python3 editor/vedit.py -p myfilm stabilize c1               # suavizar trepidação de câmera (precisa de FFmpeg com libvidstab)
python3 editor/vedit.py -p myfilm captions subtitles.srt     # um clipe de texto por legenda
python3 editor/vedit.py -p myfilm sfx a3f9c012 --at 8.0      # id do som de scripts/sfx_search.py; o impacto cai em 8.0 s
python3 editor/vedit.py -p myfilm set c1 preset="voice enhancer"
python3 editor/vedit.py -p myfilm check                      # corrigir todos os erros que relatar
python3 editor/vedit.py -p myfilm render --preview           # rápido; depois `frame --at T` e olhe o PNG
python3 editor/vedit.py -p myfilm measure --at 4             # números de brilho/cor, para julgar exposição e correção
python3 editor/vedit.py -p myfilm serve                      # deixar a pessoa abrir e ajustar no navegador

• Você tem controle total: cada comando imprime JSON, erros são simples, batch aplica várias edições como uma única alteração e undo desfaz uma. Keyframes podem animar zoom, posição, rotação, opacidade, cor, volume e velocidade; editor.md lista o resto (máscaras, tracking, tela verde, corte, espelhamento, mudo e ocultação de faixas, presets de canvas).
• Olhe a imagem com frame --at T em vez de adivinhar, julgue a cor com measure e julgue o som por medição, não afirmando que soa bem.
• Use moderação: um look suave, um estilo de transição, alguns movimentos lentos. Se remover um efeito não perder nada, remova-o.
• Tracking e máscaras são medidos, não vistos: após tracker add, verifique found e olhe os quadros com frame --at T. Tracking funciona para coisas rígidas e texturizadas com tamanho estável; perde alvos que giram ou se escondem.
• A pessoa pode alterar a timeline no navegador enquanto você trabalha. Execute show antes de editar depois que ela disser que fez alterações.
• Presets de voz (phone call, deeper voice, robot voice, ...) vêm do .prfpset do Premiere incluído e podem ser extraídos de qualquer outro com presets import FILE.prfpset. Eles aproximam os efeitos do Premiere; veja references/voice-presets.md.
• Se nenhuma biblioteca de som estiver configurada, sfx falha com uma mensagem clara; ofereça a configuração de SFX abaixo.

Kit de ferramentas SFX

Todos os scripts imprimem --help. Eles usam apenas a biblioteca padrão e FFmpeg.

Configuração única. A skill não vem com áudio, porque a licença dos sons proíbe redistribuí-los. A biblioteca padrão é o pacote gratuito Sonniss GDC 2026 Game Audio Bundle, baixado do próprio servidor da Sonniss. Antes de executar isso, informe ao usuário o tamanho (parte 1 tem 1,3 GB com 82 sons; todas as 5 partes têm 7,5 GB com 347 sons) e a licença em uma linha (gratuito para projetos pessoais e comerciais de mídia, sem atribuição; sem revenda ou redistribuição dos sons; sem treinamento de IA), e obtenha seu sim:

python3 scripts/setup_library.py --accept-license               # parte 1
python3 scripts/setup_library.py --accept-license --parts all   # tudo

Isso salva os zips em library/ dentro desta skill, retoma downloads interrompidos, reutiliza partes já existentes e, em seguida, constrói o catálogo. No Windows use python se python3 não for encontrado.

Para usar os próprios sons do usuário (adicionalmente ou como alternativa), indexe-os diretamente (veja references/sfx-library-setup.md):

python3 scripts/build_catalog.py /caminho/para/sons.zip        # ou uma pasta, ou uma pasta de zips

De qualquer forma, o resultado é um catálogo somente texto em ~/.pro-video-editing/catalog.json. Não contém áudio.

Por projeto:

python3 scripts/sfx_search.py --stats                       # o que está disponível
python3 scripts/sfx_search.py "whoosh rápido e arejado" --max-dur 1.5 --limit 8
python3 scripts/sfx_search.py "clique de botão" --exclude ID1,ID2    # evitar repetir um take

python3 scripts/render_mix.py in.mp4 cues.json --check      # validar a folha de cues
python3 scripts/render_mix.py in.mp4 cues.json -o out.mp4   # renderizar
python3 scripts/render_mix.py in.mp4 cues.json --sfx-only fx.wav   # stem de SFX para DAW ou colorista

python3 scripts/qc_audio.py out.mp4 --target -14            # verificação de loudness e pico verdadeiro

Colunas da saída da busca: id, duração, categoria, peak@ (onde o som atinge o pico), tags, nome do arquivo. Use peak@ para entender o que se alinhará com o corte.

Folha de cues (Cue sheet)

{
  "default_gain_db": -9,
  "duck": true,
  "humanize": true,
  "cues": [
    {"id": "a3f9c012", "at": 2.50, "sync": "peak", "note": "whoosh para o cartão de título"},
    {"id": "19be4d70", "at": 2.50, "gain_db": -12, "note": "camada suave por baixo"}
  ]
}

• at é o tempo do vídeo onde o ponto de sincronia do som deve cair. at_frame posiciona pelo número do quadro.
• sync: peak (padrão) posiciona o momento mais alto, onset posiciona o ataque, start posiciona a primeira amostra. A ferramenta calcula o tempo de início para você, de modo que o impacto seja frame-accurate mesmo quando o som começa antes do corte.
• Opcional por cue: gain_db, fade_in, fade_out, trim_start, duration, pitch_semitones (dentro de 12), note.
• duck reduz o volume dos SFX sob o áudio original (diálogo). humanize adiciona pequena variação de ganho e pitch quando o mesmo som se repete.
• Coloque o motivo em note. Isso torna a folha revisável e ajuda na próxima edição.

--check relata IDs desconhecidos, tempos fora do vídeo, takes repetidos, camadas empilhadas e folhas excessivamente carregadas. Corrija tudo que ele relatar antes de renderizar.

Regras de SFX

Guia completo com um método de localização: references/sfx-placement.md.

• Localize com um motivo. Cada som deve servir à emoção ou à história. Se removê-lo não perder nada, remova-o.
• Faça o impacto cair no corte ou no movimento, não perto dele. Use sync: peak para whooshes e impactos.
• Crie camadas leves: no máximo três sons ao mesmo tempo (por exemplo, impacto, sub, cauda).
• Varie os takes. Nunca use o mesmo som duas vezes seguidas; use --exclude ao pesquisar novamente.
• Deixe silêncio. Uma pausa antes de um impacto faz o impacto cair mais forte.
• Mantenha a fala clara. Mantenha duck ativado quando houver diálogo e mantenha o ganho padrão em -9 dB ou menos sob a fala.
• Densidade: aproximadamente 12 cues a cada 10 segundos já é muito movimentado. Material calmo precisa de muito menos.

Lista de verificação

Antes de dizer que um corte está finalizado:

• Cada corte passa na hierarquia, com emoção em primeiro lugar
• Nenhum corte existe apenas para adicionar ritmo; pausas são intencionais
• Os pontos de corte estão em fronteiras de pensamento, não no meio de um pensamento
• render_mix.py --check não relata erros, e avisos são resolvidos ou justificados
• qc_audio.py mostra pico verdadeiro em ou abaixo de -1 dBTP e loudness próximo ao alvo
• A duração, o tamanho do quadro, a taxa de quadros e a configuração de áudio da saída correspondem à especificação de entrega
• O usuário recebeu timestamps específicos para ouvir

Índice de referências

• references/editorial-principles.md: a filosofia, hierarquia de corte, tempo de piscada, diálogo, ritmo, diagnóstico de problemas
• references/editor.md: comandos do editor, keyframes, correção de cor, transições, legendas, configurações de entrega, formato do projeto, método de trabalho para IA, editor no navegador
• references/voice-presets.md: presets de voz, extração de arquivos .prfpset do Premiere, limites de precisão
• references/sfx-placement.md: método de localização, guia de som por propósito, níveis, camadas, ducking
• references/sfx-library-setup.md: como obter uma biblioteca, construir o catálogo, curar tags, licenciamento
• references/technical-pipeline.md: organização de mídia, proxies, cor, codecs, intercâmbio, exportação