BigBeeCN/vertical-talking-head-edit

Edição de Vídeos Curtos Verticais com Talking Head (Windows + Codex + CapCut)

Cenário de uso: você tem apenas material bruto de terceiros (talking head + B-roll) e precisa editá-lo em um vídeo curto vertical de 1080×1920, com 30–50 segundos, para que o editor finalize no CapCut ou entregue o vídeo pronto.

As regras rígidas (não negociáveis) estão em references/AGENTS_rules.md; coloque-o no AGENTS.md do projeto antes de começar. Este documento trata apenas do fluxo.

Entrada

• Diretório do material (somente leitura, nunca modificar originais; copie primeiro uma versão para o diretório de trabalho).
• Estilo e hábitos do editor (se houver). Os hábitos declarados pelo editor = padrão rígido; vídeos de referência servem apenas como catálogo de técnicas, não como parâmetros. Em conflito, prevalece o editor.
• Opcional: vídeo de referência, posição da marca, texto CTA (não colocar telefones/endereços não verificados).

Saída

• spec.json (storyboard, única base para edição), corte bruto ou vídeo final MP4, .srt, composição de quadros para QC quadro a quadro, relatório QC.
• Rota A adicional: rascunho do CapCut; Rota B adicional: camada de sobreposição transparente ProRes 4444 .mov.

Passo 0: Autoverificação do Ambiente (não iniciar sem aprovação)

Siga references/windows_env.md para verificar: ffmpeg completo (com zscale, tonemap, prores_ks), Python 3.10/3.11, faster-whisper + whisperX, Playwright + Chromium + fontes chinesas alvo, opcionalmente demucs / RVM; diretório de rascunhos do CapCut preenchido na configuração e adicionado a writable_roots. O sandbox do Codex está offline por padrão: modelos e dependências devem ser instalados antecipadamente. Se qualquer item falhar, informe o que está faltando, não force execução. Comandos específicos de cada etapa estão em references/windows_commands.md.

Passo 1: Inventário do Material

1. Use ffprobe em cada arquivo: resolução, framerate (variável?), rotação, duração, transferência de cor (HLG/PQ = HDR). Gere inventory.csv.
2. Não exportar arquivos intermediários SDR: converta ao ler quadros usando cadeia de filtros. Todos os materiais com fps=30; materiais HDR começam a cadeia de leitura com conversão HDR→SDR, caso contrário a imagem fica acinzentada (inclusive para quadros de capa; comandos na seção 2 do windows_commands.md).
3. Extraia thumbnails de cada material e etiquete (conteúdo, pessoa(s), trechos utilizáveis, obstrução/cenas escuras no início/marca de terceiros). Marque materiais e trechos não utilizáveis.

• Verificação: cada material tem etiqueta; materiais com característica de transferência arib-std-b67 ou smpte2084 devem ter cadeia de filtros iniciando com conversão HDR.

Passo 2: Transcrição e Revisão

1. Transcrição inicial com faster-whisper: modelo medium, device='cpu', compute_type='int8', language='zh', vad_filter=True, word_timestamps=True, initial_prompt com vocabulário específico do domínio. O VAD pode pular frases; execute mais uma vez sem VAD, com condition_on_previous_text=False.
2. Revisão manual completa contra o áudio: termos técnicos, números, homófonos; Whisper também pode inventar frases que não foram ditas – remova-as. Palavras inaudíveis: corte o trecho do áudio, não adivinhe.
3. Antes de transcrever, extraia WAV mono 16 kHz com ffmpeg e alimente ao whisper. Depois, envie o texto revisado para whisperX para alinhamento forçado (escreva no campo align do spec), obtendo início de cada palavra (erro 0–3 quadros). O tempo final do whisperX não é confiável; use detecção de energia para o ponto de saída.

• Verificação: transcrição sem termos técnicos e números não revisados; cada frase tem início de palavra.

Passo 3: Reestruturação Narrativa (narrativa primeiro, efeitos depois)

1. O primeiro segundo deve ser um gancho: "contraste + resultado", usando fala original. Sem B-roll ou logo no início.
   • O gancho pode concatenar duas frases não adjacentes, mas com src_t em cada metade sem alterar o significado.
   • Duas opções de áudio, definidas no spec: primeira frase começa normalmente, com texto grande sobreposto; ou a frase de resultado (≤3s) é colocada no início como cold open, depois a ordem normal.
2. Remova frases que não impulsionam a história (slogans, preenchimento, repetições de opinião); alvo: 30–50 segundos.
3. Identifique 3–4 pontos de virada narrativa (gancho inicial / transição de cena / clímax-resultado / frase de fechamento impactante); pontos explosivos apenas nessas posições; intensidade do clímax em primeiro lugar, depois o início. Dois pontos explosivos com pelo menos 6 segundos de intervalo; ~30 s → 3 pontos; ~50 s → 4 pontos.

• Verificação: todo texto exibido na tela pode ser encontrado na transcrição com timestamp e contexto (a mesma palavra pode ter significados diferentes em frases diferentes).

Passo 4: Escrever Storyboard spec.json e Obter Aprovação do Usuário

Especificação dos campos em references/spec_schema.md; exemplos de categorias de palavras-chave em references/kw_class.example.json (os exemplos são de um projeto específico; reescreva para cada projeto). Cada segmento: material de origem, ponto de entrada/saída, layout, legendas, kw_class, predefinição de efeitos, B-roll, efeitos sonoros, trecho musical, src_t (timestamp da fala original). Envie o storyboard para o usuário confirmar antes de renderizar.

Passo 5: Edição

1. Detecção de energia RMS em janelas de 10 ms para pontos de entrada/saída (não usar final de palavra do Whisper). Corte respirações e pausas completamente.
   • Abordagem testada: corte por energia com limiar = max(10º percentil + 14 dB, −48 dBFS), 3 janelas consecutivas de 10 ms acima do limiar contam como início de fala, deixe 0,10 s antes, 0,14 s depois; depois aperte manualmente; verifique que o comprimento total contínuo abaixo de −42 dBFS em cada lado do corte ≤90 ms.
   • Hábito do editor alvo: apenas 1–2 quadros (≤67 ms) antes do som de cada palavra (não testado ainda). Método de verificação: após separar vocal com demucs, meça do ponto de corte até o início de 3 janelas consecutivas de 10 ms acima de −42 dBFS; cada corte ≤67 ms, consoante inicial não cortada, segmento deve passar ASR sem palavra quebrada para ser aprovado; após aprovação, adote como padrão.
   • Opcional: versão alternativa com 2–3 quadros entre frases para o editor escolher.
2. Exporte cada segmento com precisão de quadro: -ss antes de -i, -vf com fps=30, use -frames:v nf para comprimento fixo (nf = round((ponto_saída − ponto_entrada) × 30)), libx264 -preset veryfast -crf 12, com as três tags de cor BT.709; áudio concatenado por amostra, fade in de 8 ms / fade out de 15 ms para evitar estouro.
3. Cortes de mesma câmera com zoom de 1,08x; transição para B-roll com whip pan + desfoque horizontal.
4. B-roll apenas onde a fala menciona o conteúdo correspondente; não inserir apenas para preencher ritmo.

Passo 6: Efeitos de Legenda (Dois Níveis)

Nível Normal: uma a cada 1,5–2 s, intervalo máximo ≤3 s, moderado.

• Legenda inferior: texto branco com contorno preto, até 12 caracteres por linha, exibida como frase completa (se deve colorir palavras-chave é parâmetro, definido pelo editor).
• Destaque no meio da tela: letras grandes douradas (palavras-chave 1,75×, números 2×), entrada caractere por caractere 115%→100%, 6–8 quadros; opcional: sublinhado ou círculo desenhado à mão, textura de papel, sombra suave.
• Técnicas opcionais: contagem numérica, sobreposição de imagem com efeito sonoro correspondente, lista cumulativa (tamanho ≥1,2× da legenda inferior, depois ampliar ao agrupar), frases impactantes verticais (ocultar legenda inferior correspondente), etiqueta de identidade no início (usar uma vez apenas, marcar como "não é fala original").

Nível Explosivo: 3–4 no total, contando na densidade geral, cada uma com tudo:

• Letras grandes ocupando 75–85% da largura da tela (85% é o limite, priorizar zona segura); zoom de 1,15–1,25 em 4 quadros; tremor de tela com motion blur em 2–3 quadros; fundo escurecido 6–30% e levemente dessaturado (parâmetros, ajustar para que o rosto da pessoa ainda mantenha detalhes no celular); camada da pessoa não colorizada; efeito sonoro composto pré-misturado (conta como 1).
• Intensidade: o mais pesado zoom 1,25 e tremor 3 quadros; os demais zoom 1,15 e tremor 2 quadros.
• Cada técnica usada apenas uma vez no vídeo: texto atrás da pessoa (recorte)/transição com máscara de texto/contagem numérica em tela cheia + carimbo vermelho/frase vertical que aparece + luz varrendo.
• Texto atrás da pessoa: posicionar acima da linha do ombro, evitando mãos e objetos; cabeça deve cobrir 25–30% do texto (<15% não perceptível no celular); antes de adicionar contorno, apagar objetos acidentalmente recortados (cadeiras, etc.) da máscara.
• Carimbo vermelho: única cor vermelha do vídeo, largura 30–40% da tela, caindo de 150%→100% em 3 quadros + tremor de 2 quadros.
• Congelamento: apenas em silêncio natural após uma frase (voz < −45 dB), escolher quadro com boca mais próxima de fechada, ≤0,4 s, no máximo um por vídeo; efeito sonoro de impacto no início do congelamento. Esta é a única exceção à regra "nenhuma pausa".
• Todas as animações de entrada começam 1 quadro antes.

Passo 7: Áudio

• Voz: high-pass 80 Hz → redução de ruído → EQ leve → compressor.
• Música: troca por capítulo (hábito do editor), crossfade 300–600 ms; ducking lateral durante fala. Use apenas música com autorização confirmada ou auto-produzida.
• Efeitos sonoros: cerca de 0,5/s, distribuídos uniformemente, janela de 4 s com 1–3 efeitos, intervalo mínimo entre dois efeitos ≥0,25 s; nível padrão: RMS do efeito 14 dB abaixo da parte sonora da voz (db=-14); efeitos combinados com o conteúdo visual têm prioridade sobre pops genéricos.
• Loudness: primeira medição com loudnorm=I=-14:TP=-1.5:LRA=11; segunda passagem com valores medidos e linear=true, seguido por aresample=48000,alimiter=limit=0.7:attack=1:release=30:level=false; finalmente verifique com ebur128 e aplique ganho g = min(−14 − I, −2,9 − Peak). Alvo: −14 LUFS, pico verdadeiro ≤ −1 dBTP.

Passo 8: Renderização e Entrega (escolher uma ou combinar)

• Rota A: Rascunho CapCut (padrão quando o editor usa apenas CapCut). Codex gera corte bruto, legendas, pontos de efeito sonoro e musical, cria rascunho com pyJianYingDraft; editor abre CapCut para finalização e exportação. Limitações e cuidados em references/jianying_route.md. Toda a rota deve ser verificada em máquina Windows real.
• Rota B: Sobreposição (obrigatória para pontos explosivos). Camada de efeitos usando HTML/Canvas, Playwright aciona Chrome do sistema para capturar PNG transparente quadro a quadro: viewport 1080×1920, device_scale_factor=1, argumento de inicialização --font-render-hinting=none, aguardar window.READY e document.fonts.ready, omit_background=True; todas as animações escritas como funções puras do tempo t. Sequência PNG alimentada a -framerate 30 e codificada como ProRes 4444 (-alpha_bits 16), depois composta com ffmpeg overlay. Colocar a sobreposição como faixa de vídeo no rascunho do CapCut: não testado. ffmpeg drawtext não consegue entrada caractere por caractere nem texto atrás da pessoa.
• Entrega mínima: corte bruto + SRT + storyboard; finalização feita pelo editor no CapCut.
• Antes de sobrepor, aplicar correção de cor leve no material de fundo: eq=contrast=1.04:saturation=1.07.
• Codificação final: libx264 -profile:v high -preset slow -crf 17 -maxrate 16M -bufsize 24M -g 60 -r 30 -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709, AAC 192k, -movflags +faststart.

Passo 9: Controle de Qualidade (entregar apenas se todos os itens passarem)

Siga references/qc_checklist.md item por item. O relatório deve conter apenas informações verificadas por extração de quadros e audição, cada uma com número e unidade; para o que não foi medido, escreva "não medido".

Capa

• Divisão: planejamento fornece texto e quadros candidatos (campo cover no spec); editor faz layout e exporta (1080×1920 e 3:4).
• Título principal: condensar fala original, ordem pode ser ajustada (ex.: "apertar parafusos por um mês e meio"); não adicionar fatos não presentes na fala original; ≤7 caracteres, no máximo 2 linhas. Subtítulo: número do resultado; 2–3 adesivos.
• Título e rosto dentro da área central 1080×1440 (y 240–1680); grade inicial do TikTok corta em 3:4.
• Pelo menos 3 quadros candidatos, com timestamp e justificativa; marca "não final".
• Varra todo o segmento a cada 0,5 s em busca de quadros de perfil ou expressão; direção do olhar define layout (pessoa olhando para cima/esquerda → pessoa no canto inferior direito, título no canto superior esquerdo); proibido espelhar se roupa ou fundo tiver texto.

Critérios de Sucesso

• Duração de 30–50 segundos, primeiro segundo é gancho de fala original; 100% do texto exibido na tela rastreável à fala original.
• Efeitos normais com intervalo máximo ≤3 s; 3–4 pontos explosivos com intensidade graduada e técnicas não repetidas.
• Efeitos sonoros ≈0,5/s, sem sobreposição simultânea; acerto de batida ≤2 quadros; −14 LUFS ±1, pico verdadeiro ≤ −1 dBTP.
• Zero violação de zona segura; sem quadros pretos ou congelados inesperados; texto não sobrepõe rosto nem marca.
• Storyboard confirmado pelo usuário; todos os itens de entrega presentes.

Armadilhas Comuns → Soluções

Armadilha	Solução
Material HLG acinzentado	Converter para SDR com zscale + tonemap=hable, gamma ~1,12
Timestamp de palavra do Whisper adiantado, final arrastando para o silêncio	Usar alinhamento whisperX para início, detecção de energia para final
VAD pula frases	Executar mais uma vez sem VAD
Texto na tela não é fala original / contexto errado	Cada item com src_t, QC verifica contra transcrição
Efeitos com mesma intensidade, parece genérico	Dividir em nível normal e explosivo; explosivo com tudo
Texto atrás da pessoa não perceptível	Medir proporção de cobertura; cabeça cobre 25–30%
Cadeira recortada junto com a pessoa	Texto acima da linha do ombro; apagar itens acidentais antes do contorno
Batida medida errada	Medir a partir do "primeiro quadro visível"; animação de entrada começa 1 quadro antes
Sibilância confundida com efeito sonoro	Separar vocal com demucs e medir apenas na trilha de acompanhamento
Efeitos sonoros aglomerados	Janela de 4 s com 1–3 efeitos; efeito composto de clímax conta como 1
Texto grande entra na área do botão do TikTok	Borda direita ≤ x=930
Congelamento durante fala, boca não corresponde	Congelamento apenas em silêncio, ≤0,4 s
Animação desliza sobre o rosto ou sai da tela	Substituir por fade out + fade in ampliado na posição alvo
Ferramenta de visualização usa caminho para cache de imagem antiga	Renomear arquivo de verificação a cada vez
Caminho chinês ou espaço quebra comando	Usar Python subprocess com lista de argumentos; leitura/escrita de arquivo explicitamente utf-8
Whisper alucina frases não ditas	Revisão manual completa contra áudio antes de alinhar
Quer mudar para outro esquema de renderização (ex.: Remotion)	Não testado; não substituir por conta própria; usar apenas HTML/Canvas + Playwright para camada de efeitos
Novo rascunho não aparece na lista do CapCut / fonte errada	Abrir e fechar rascunho existente ou reiniciar; abrir rascunho duas vezes