morrimoz/revisão-de-clipes-de-cabeça-falante

Revisão de clipes de cabeça falante

Transforme gravações brutas de cabeça falante em seleções aprovadas sem que ninguém precise vasculhar manualmente. O agente transcreve, alinha e sugere. Uma pessoa aprova em uma única página. O agente então monta exatamente o que foi aprovado.

A transcrição permanece na máquina. Os vídeos originais nunca são modificados.

Regras rígidas

• Nunca modifique, mova ou re-exporte os vídeos originais. Tudo são pontos de entrada/saída mais arquivos derivados.
• Nunca exclua as filmagens do usuário nem esvazie a Lixeira. Se o disco estiver cheio, avise e deixe que o usuário resolva.
• Trabalhe em uma pasta temporária (scratch). Apenas prévias, pôsteres, a página de revisão e as seleções vão ao lado da mídia.
• Não invente palavras. O texto do clipe vem da transcrição. Correções opcionais de frases ficam em um mapa JSON passado com --fix (veja references/term-corrections.example.json). Não aplique o arquivo de exemplo.
• Verifique fatos ditos na câmera (horários, números, "10 minutos atrás") contra a gravação real antes de selecioná-los.
• Sem olhares para o monitor, batidas no microfone, cliques ou ruídos de respiração em um segmento mantido. Reexecute a análise de olhar (passo 5) e ouça cada ponto de edição após qualquer re-edição, não apenas na primeira seleção. Silencie ou corte o ruído, nunca a palavra ao lado.
• Peças (pickups) e linhas regravadas devem corresponder ao tom, nível e ambiente da take principal (mesmo microfone, ganho, distância, EQ e redução de ruído). Sinalize uma linha que soará abafada ou abafada (“boxed-in”) em vez de enviá-la.
• Use hífens, não travessões, em tudo que escrever para o usuário.
• Limites de palavras são limites rígidos, mesmo quando um prompt pedir cortes apertados ou ajustes de olhar. Os clipes recebem um pré-rolamento de 0,15s e uma cauda de 0,25s ao redor dos tempos de palavra do Whisper (suas bordas de palavra são frequentemente adiantadas ou atrasadas), limitados para nunca invadir uma palavra vizinha. Cortes de pausa e ajustes de olhar só cortam dentro de lacunas entre palavras e mantêm pelo menos 0,1s ao lado de cada palavra. Se um desvio de olhar sobrepor uma palavra falada, mantenha a palavra e sinalize-a (away_words, borda vermelha no stringout), nunca a corte. Use build_review.py --gaze-trim para cortes de borda em vez de escrever seu próprio script de corte. exact_spans definidos manualmente também são empurrados de volta para as bordas das palavras.

Configuração (uma vez por máquina)

Execute scripts/check_deps.sh. Ele precisa de ffmpeg, ffprobe, python3 e um backend Whisper. Swift é opcional para a etapa de olhar. Passos de instalação: references/setup.md.

Estrutura de diretórios

WORK/                      pasta temporária, por exemplo ./talk/
  tx/<take>.wav|json|txt   áudio mono 16 kHz, JSON do Whisper com palavras, transcrição legível
  picks.json               beats + candidatos (o agente edita isso)
  picks_resolved.json      spans precisos por palavra, texto, durações (gerado)
  pose.json                intervalos de desvio de olhar (opcional, macOS)
REVIEW/                    ao lado da mídia, por exemplo ./review/
  previews/<take>.mp4      cópias H.264 540p para a página
  posters/<beat>-<i>.jpg
  "<Título> - take review.html"
  "<Título> - picks stringout (540p).mp4"
SELECTS/                   selects.json, selects.csv, selects.edl, selects.mp4

Nomeie o episódio de acordo com a peça, por exemplo lancamento-01. Mantenha as chaves das takes curtas (A, B, C) e mapeie-as para nomes de arquivo em picks.json.

Passos

1. Inventário. ffprobe em cada take (duração, tamanho, fps, rotação). Gravações de telefone geralmente têm taxa de quadros variável e são retrato. As prévias e renders normalizam isso. Pergunte quais arquivos são as exportações corrigidas (graded) para editar e quais são os originais da câmera a ignorar.
2. Transcrever. python3 scripts/transcribe.py --out WORK/tx TAKE.... Use o interpretador que check_deps.sh informou se o pacote Whisper não estiver no python3 padrão. Se os arquivos ainda estiverem exportando, use --watch PASTA --expect N em segundo plano: ele espera até que cada arquivo pare de crescer por 30s. Modelo preferido em Apple Silicon: mlx-community/whisper-large-v3-turbo, timestamps de palavra, com condition_on_previous_text desligado. Defina --lang quando a fala não for inglês.
3. Rascunhar as seleções.
   • Modo (a), takes de um roteiro: escreva WORK/script.txt com uma linha ou ponto de fala por linha (id | nome | texto se quiser IDs). Execute python3 scripts/segment.py takes --tx WORK/tx --script WORK/script.txt --out WORK/picks.json A=take-a B=take-b .... Ele encontra cada tentativa de cada linha em cada take (correspondência fuzzy de janela de palavras, então reinícios aparecem como candidatos separados) e pré-marca o mais fluente.
   • Modo (b), um vídeo longo: python3 scripts/segment.py single --tx WORK/tx --out WORK/picks.json A=take-longa corta em pausas de 1,2s ou mais e em finais de frases, em clipes de 4 a 40s.
   • Em seguida, leia você mesmo as transcrições .txt. Corrija pontos de entrada/saída, adicione cut: [[a,b]] para reinícios e falhas, mescle ou divida beats, e escreva um why real por candidato (limpo, reinício, palavra errada, corresponde à gravação de tela). Prefira a take que foi filmada com a gravação de tela correspondente. A pontuação automática só desempata.
4. Construir a página. python3 scripts/build_review.py --work WORK --media SRC --out REVIEW --title "lancamento-01" --stringout. Os spans são divididos em lacunas de palavras acima de 0,6s e apertados com silencedetect -35dB / 0.35s. Adicione keep_pauses: true em um candidato para pular isso. Flags de padding: --pre 0.15 --tail 0.25 --guard 0.1. Passe --fix caminho/para/correcoes.json apenas quando você tiver um mapa de frases real. Abra o HTML no navegador. Os vídeos carregam ao clicar, então a página abre rápido.
5. Opcional, macOS: olhar. python3 scripts/gaze.py --work WORK --review REVIEW, então reexecute o passo 4 com --stringout --gaze-trim. Quadros de desvio de olhar ganham borda vermelha no stringout. Cubra-os depois com filmagem de tela e mantenha o áudio.
6. Revisão humana. Diga ao usuário o que fazer: Reproduzir, Usar/Pular, anotações, depois "Salvar decisões (JSON)". Ele baixa <slug>-decisoes.json. "Copiar como texto" é a alternativa. Cartões não tocados mantêm a sugestão.
7. Aplicar anotações. Leia o JSON de decisões. Transforme cada anotação em edições no picks.json: cut, in/out, audio_only: true, grade: "eq=gamma=1.28:brightness=0.03", optional: true. Faça um backup primeiro (cp picks.json picks.antes-anotacoes.json). Reexecute o passo 4 e resuma cada anotação e o que você fez.
8. Montar. python3 scripts/assemble.py --work WORK --media SRC --decisions /caminho/para/<slug>-decisoes.json --out SELECTS --render. Você obtém um selects.mp4 em resolução total com quadros precisos, um selects.edl CMX3600 (importável via Premiere, Resolve, Final Cut), selects.csv e selects.json com intervalos de desvio de olhar e anotações.
9. Verificar. Ouça cada ponto de edição (sem primeira ou última sílaba cortada, sem olhar, sem ruído). ffprobe na duração do render contra a soma em selects.json, e faça uma folha de contato: ffmpeg -i selects.mp4 -vf "fps=1/6,scale=180:-1,tile=10x3" -frames:v 1 sheet.jpg. Visualize-a, depois relate a duração, o que mudou e o que ainda precisa do usuário.

Formato do picks.json

{"episode":"lancamento-01","mode":"takes","takes":{"A":"take-a","B":"take-b"},
 "beats":[{"id":"01a","name":"Gancho","script":"...","cands":[
   {"take":"B","in":0.82,"out":21.2,"pick":true,"why":"Limpo, corresponde à tela.","cut":[[51.4,53.82]],
    "note":"","audio_only":false,"grade":null,"optional":false,"signals":{"dur":20.1,"wpm":162,"fillers":0,"repeats":0}}]}]}

Dicas

• Verifique a qualquer momento a precisão dos tempos de palavra com o JSON da transcrição. Um despejo de word@inicio-fim ao redor de uma anotação é a maneira mais rápida de posicionar um corte.
• Se o ffmpeg não tiver drawtext, marque os quadros com drawbox ou hue, não com texto.
• Renders grandes: verifique o espaço livre em disco primeiro. Takes em 4K acumulam rapidamente.