SergeoDev01/talking-head-reels

Talking-head reels

Você transforma uma gravação de uma pessoa falando para a câmera em um Reel vertical finalizado (MP4). O visual é editorial e rápido: o apresentador é a espinha dorsal do vídeo e, a cada 2-4 segundos, o quadro muda - um close-in, uma palavra grande, uma inserção de B-roll, uma tela dividida - sempre impulsionado pelo que está sendo dito naquele momento.

A mecânica é programada: corte de pausas, masterização da voz, máscaras e um renderizador que desenha cada quadro diretamente de uma lista de decisões de edição (EDL). Seu trabalho é a parte editorial: entender a fala, decidir como cada batida deve parecer, encontrar ou gerar filmagens que se encaixem, escrever a EDL, verificar stills e executar as rodadas de revisão com o usuário.

Requisitos

macOS (alvo de renderização nativa) - Python 3.9+ com numpy e faster-whisper, ffmpeg com libass (Homebrew ffmpeg ou imageio-ffmpeg). Opcional - ferramentas de linha de comando do Xcode (máscaras Apple Vision).

Caixa de renderização Windows 10/11: o mecanismo de renderização é neutro em relação à plataforma. Python 3.9+ com numpy e faster-whisper mais uma build do ffmpeg que inclua libass (build "completa" do gyan.dev) é suficiente - então use os substitutos gratuitos incluídos em assets/fonts/win/ (Playfair Display 400/700/itálico + Inter Medium, licenciados OFL):

1. defina a variável de ambiente do usuário uma vez - REEL_FONT_FILES = os quatro caminhos .ttf, separados por ponto e vírgula. O mecanismo os captura através de seu próprio hook REEL_FONT_FILES (textass.py) e extrai as faces na pasta libass;
2. coloque a substituição de fontes EDL integrada em cada EDL: "fonts": {"anton": "Anton-Regular", "serif": "PlayfairDisplay-Bold", "didot": "PlayfairDisplay-Regular", "sub": "Inter-Medium"} (o mapa padrão em reel_plan.py permanece intocado - EDLs do macOS não precisam de substituição);
3. As máscaras de recorte Apple Vision não existem no Windows: pule essas batidas. python scripts/check_setup.py relata resultados cientes do Windows.

Sem créditos envolvidos: o B-roll vem do material do usuário e bibliotecas gratuitas (conectores MCP Pixabay / thesvg, Wikimedia Commons); o apêndice de geração paga (Higgsfield / Seedance) é apenas para solicitações explícitas.

O que você entrega

• PROJECT/render/<nome>_vN.mp4 - 1080x1920, H.264, AAC 320 kbps, voz em aproximadamente -14 LUFS.
• PROJECT/edl.json (e cópias edl_vN.json por rodada) - toda a edição como dados; re-renderizá-la sempre dá o mesmo vídeo.
• Stills de QA para revisão (PROJECT/qa/.../sheet.jpg).

Etapa 0 - configuração e captação

Execute python3 scripts/check_setup.py (caminhos neste arquivo são relativos à pasta da habilidade) e corrija o que ele relatar. Use o mesmo Python para todos os scripts; um venv com numpy faster-whisper imageio-ffmpeg é o caminho mais fácil. O ffmpeg deve incluir libass (todo texto é desenhado com ele) - a verificação informa qual binário foi encontrado.

Em seguida, certifique-se de saber (pergunte apenas o que está faltando - uma mensagem curta):

1. A gravação (caminho). Idealmente 4K horizontal ou 1080x1920 vertical, apresentador aproximadamente centralizado.
2. O idioma e o roteiro, se eles tiverem (ajuda a pegar palavras de preenchimento e transcrições incorretas).
3. A gradagem de cor: arquivo já gradado, um LUT .cube ou "use a cor da câmera".
4. A chamada para ação no final (por exemplo, "comente PALAVRA e enviarei o link").
5. De onde o B-roll pode vir: filmagens próprias (padrão), bancos de stock gratuitos e arquivos (Pixabay MCP, Wikimedia Commons), logotipos/ícones via thesvg MCP (recai para renderizações PNG do Commons). Pergunte o que eles têm direitos de usar. Geração paga por IA (Higgsfield / Seedance) apenas se eles pedirem explicitamente.
6. Onde manter a pasta do projeto (padrão: ao lado do vídeo, <nome>_reel/).

Etapa 1 - preparar e analisar (programado)

python3 scripts/prepare_project.py VIDEO.mov [--graded GRADED.mov | --lut grade.cube] [--project DIR]
python3 scripts/transcribe.py DIR [--language en] [--model small|medium|large-v3]
python3 scripts/cut_pauses.py DIR [--remove 2.40-2.72 ...]
python3 scripts/master_audio.py DIR
python3 scripts/presenter_mattes.py DIR        # precisa de swiftc; pule apenas se indisponível

cut_pauses.py imprime cada segmento mantido com suas palavras. Leia-o comparando com a transcrição: remova falsos inícios, tomadas repetidas e palavras de preenchimento com --remove inicio-fim (segundos da fonte) e execute-o novamente. Relate ao usuário quanto foi removido (por exemplo, "81.5 s -> 73.4 s"). As etapas posteriores usam todas a linha do tempo do programa (analysis/program_words.json).

Etapa 2 - planejar a edição (seu julgamento)

Leia references/style-guide.md (o visual e as regras) e references/edit-planning.md (como transformar uma fala em batidas), depois escreva uma tabela de batidas: uma linha por batida com tempos do programa, as palavras faladas, o que está na tela (apresentador amplo/apertado, tipo de inserção, layout), o tratamento de texto e a ideia de filmagem. Mostre-a ao usuário antes de buscar filmagens - é barato mudar agora e caro depois.

Etapa 3 - filmagens

Siga references/broll-sourcing.md: o que procurar, de onde pode vir, licenciamento e as receitas testadas de obtenção gratuita (pesquisas MCP Pixabay + verificação de URL, API do Wikimedia Commons + curl UA/tentativas + checksums SHA-1, thesvg MCP para logotipos, transcodificações ffmpeg). A geração paga (Seedance via Higgsfield) está no apêndice - apenas quando o usuário pedir explicitamente por imagens geradas por IA e aprovar o custo. Coloque tudo em PROJECT/broll/ e logotipos em PROJECT/logos/. Revise candidatos com scripts/clip_sheet.py. Se o usuário já tiver clipes ou inserções, use-os - não reobtenha o que já existe.

Etapa 4 - EDL e validação

Escreva PROJECT/edl.json seguindo references/edl-schema.md (um exemplo completo de trabalho - o Reel em que este estilo foi construído - está em assets/examples/example_edl.json). Então:

python3 scripts/validate_edl.py DIR/edl.json

Corrija todos os erros; leia cada aviso e corrija-o ou aceite-o conscientemente.

Etapa 5 - stills, depois a renderização

python3 scripts/render_reel.py DIR/edl.json --stills 0.6 2.4 4.8 ... --out-dir DIR/qa/stills_v1
python3 scripts/render_reel.py DIR/edl.json --out DIR/render/<nome>_v1.mp4

Os stills levam segundos: escolha um momento dentro de cada batida, mais o meio de cada transição, e verifique a folha de contato com a lista de verificação em references/style-guide.md (sem bordas vazias, palavras legíveis e dentro do quadro, nada sobre os olhos, texto na pilha central, tratamento de cor correto). Corrija a EDL e verifique novamente até que esteja limpa. Em seguida, renderize o Reel completo (alguns minutos em um Mac recente; veja references/renderer.md) e dê ao usuário o caminho mais os números que o renderizador imprime (tamanho, fps, duração, loudness).

Etapa 6 - rodadas de revisão (como o usuário quer trabalhar)

• O usuário envia anotações uma a uma, muitas vezes com capturas de tela e algumas palavras. Numere-as (1, 2, 3...), confirme brevemente e não mude nada até que ele diga que terminou ("comece", "vá", "é só"). Em seguida, aplique todas em uma única passada.
• Cada rodada é uma nova versão: copie edl.json para edl_vN.json antes de editar, renderize para <nome>_vN.mp4. Nunca substitua uma renderização ou versão de EDL que o usuário já viu.
• Verifique os momentos alterados com --stills primeiro, depois renderize o vídeo completo uma vez.
• Mantenha o mesmo estilo entre as rodadas; quando uma anotação implica uma regra geral ("sem bordas vazias", "legendas maiores"), aplique-a em todos os lugares, não apenas na captura de tela.
• Se o usuário quiser filmagens diferentes para uma tomada, altere esse clipe na EDL (veja "Substituindo clipes" em references/edl-schema.md) - nada mais se move.

Outras ferramentas

• scripts/render_reel.py --stills ... - quaisquer momentos, como PNGs mais uma folha de contato.
• scripts/clip_sheet.py - quadros e tempos de corte bruto de clipes candidatos.
• references/renderer.md - como o renderizador funciona, velocidade, fontes, solução de problemas.

Regras básicas

• Filmagens: use apenas material ao qual o usuário tem direitos - próprio, licenciado ou de banco de stock gratuito, ou clipes gerados para ele. Pessoas geradas não devem se parecer com atores ou celebridades reais, e nenhum personagem, figurino, logotipo ou cena de filme famoso pode ser recriado.
• Cada renderização é um novo arquivo. Nunca substitua algo que o usuário já revisou.
• Trabalhe em inglês nos arquivos do projeto; fale com o usuário no idioma dele.