vincesector/talking-head-pipeline

/autocut

Gravação bruta entra, arquivo pré-editado limpo sai. Você executa todos os comandos; o humano aprova um plano e assiste ao resultado. Nunca entregue a eles uma linha de comando para executar.

Raiz do repositório (scripts estão lá):

THP_HOME=${THP_HOME:-$(cat ~/.config/talking-head-pipeline/root)}

Escopo

Situação	Pipeline
Gravação bruta; silêncios, erros e sincronia precisam de ajuste	este aqui
Material já cortado de uma pessoa na câmera que deve parecer dinâmico	/dynamic-edit, alimentado com o clean.mp4 desta skill

Esta skill não adiciona efeitos, legendas ou gráficos. Ela produz o arquivo que o /dynamic-edit recebe como entrada. O encadeamento é o caminho normal: /autocut então /dynamic-edit.

Por que funciona (explique desta forma)

Dois fatos fazem com que cortadores automáticos ingênuos "mastiguem" palavras e saiam da sincronia:

1. Microfones sem fio e softwares de captura entregam áudio adiantado ou atrasado, em uma quantidade que muda entre as sessões (+240 ms foi medido em uma configuração). Portanto, a sincronia é MEDIDA por arquivo a partir do movimento labial (SyncNet) e aplicada antes de qualquer outra coisa. Nunca codificada.
2. Os timestamps de palavras do Whisper acertam um limite real de palavra apenas cerca de 2 vezes em 12. O preenchimento ao redor de um número errado ainda corta palavras. Portanto, cada palavra é re-temporizada com um alinhador forçado, e no momento da renderização, cada borda de corte é ajustada na própria forma de onda.

E um fato faz com que erros de fala passem despercebidos: O Whisper suaviza repetições. "Então vamos falar sobre, então vamos falar sobre o que aconteceu" volta como uma frase limpa. Uma segunda transcrição, ipsis litteris (CrisperWhisper), mantém todos os falsos inícios, repetições e muletas; hesitações são encontradas nela.

Fluxo de Trabalho

1. Encontre o arquivo, nunca o toque

Use o arquivo que o humano nomeou, ou a gravação mais recente na pasta de captura deles (pergunte uma vez onde ela fica). Confirme o nome do arquivo e a duração em uma linha. O arquivo bruto é somente leitura durante todo o trabalho; toda saída vai para <raw dir>/<raw stem>_autocut/.

2. Modo de Planejamento

python3 "$THP_HOME/scripts/autocut/autocut.py" "<raw.mp4>"

A detecção de sincronia é a parte lenta (3 a 10 minutos, mais em uma máquina ocupada ou Linux apenas com CPU). Diga isso antes de começar. O resto do modo de planejamento leva cerca de um minuto depois que os modelos estão em cache; a primeira execução por idioma baixa modelos (vários minutos). Adicione --lang en|pt|it|es|fr|de|nl apenas se o idioma detectado estiver errado. --offset SECONDS pula a detecção quando o deslocamento já é conhecido; --no-sync para filmagens apenas de tela, sem rosto.

Se a detecção falhar (sem rosto, baixa confiança) o script avisa e continua com deslocamento 0. Não invente um número. Diga ao humano que não foi possível medir e pergunte: prosseguir sem sincronia, ou usar um valor que ele forneça.

3. Mostre o plano como uma tabela compacta, então PARE

Leia plan.md do diretório de trabalho e apresente-o (nunca cole o arquivo bruto):

  Fonte     take-01.mp4   01:47.9
  Sincronia +240 ms (áudio adiantado), confiança 5.5, dispersão 0 ms
  Resultado 01:40.5 planejado, 7.3 s removidos, 5 cortes

  00:00.0-00:02.8   corte   silêncio 3.0 s          2.8 s
  00:23.6-00:24.9   corte   silêncio 2.0 s          1.3 s

  Hesitações (aplicadas):  "então vamos falar sobre, | então vamos falar sobre"   manter a segunda tentativa
  Reinícios (propostos): 01:12.4 "haverá uma perda em" x2 ...      comando apply_spans listado
  Propostas de retake (não aplicadas):
  1  01:45.9-01:47.0  "e então"  ->  manter 01:47.0-01:48.1 "e então"

Sinalize no mesmo bloco: dispersão de sincronia acima de 40 ms ou confiança abaixo de 3.5; deslocamento inicial de alinhamento p90 acima de 500 ms (a transcrição é incerta); qualquer linha de retake sinalizada como um loop do decodificador Whisper.

Repetições e falsos inícios são cortados por padrão. É para isso que serve a passagem palavra por palavra. Precisão ainda supera recuperação: um corte errado custa uma regravação, uma hesitação perdida custa mais um corte. Correspondências confiantes (repetições imediatas, um abandono sem pontuação entre tentativas) são aplicadas; as mais ambíguas são listadas como candidatos restart?. Leia cada candidato no contexto. Vete qualquer coisa que seja uma repetição retórica deliberada ("abaixo de 60, abaixo de 70, abaixo de 80"). Muletas (hum, ah) são listadas, nunca cortadas automaticamente. Mantenha a ÚLTIMA tentativa; quando uma pausa fica entre duas tentativas, a pausa marca onde a segunda tentativa começa.

Faça uma pergunta: aprovar como está, ou nomear algo para recolocar. Se uma frase for ambígua, pergunte sobre ela especificamente; não adivinhe. Nada é renderizado sem uma resposta.

4. Aplique edições a partir dos números, nunca da memória

• Aceite um retake ou reinício pelas palavras, não por timestamps digitados:

  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --drop "[email protected]"   # frase mais próxima de 22 s
  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --span 71.20:74.85     # a partir do comando listado no plan.md
  

  Leia cada linha de contexto que ele ecoar de volta.
• Releia plan.json do disco antes de renderizar; o humano pode tê-lo editado. Um plano editado após um corte é recortado automaticamente.
• Pausas intencionadas são conteúdo: uma batida deliberada ("e a resposta é... [pausa] nada") vai em plan.json como keep_silences: [[s, e]] (em segundos da fonte) para que o cortador nunca a aperte.

5. Renderize

python3 "$THP_HOME/scripts/autocut/autocut.py" "<raw.mp4>" --render

O que a renderização faz, para que você possa explicar falhas:

• 09p takes longos (acima de 3 min): limita pausas acima de 0,65 s para 0,30 s após o último som + 0,20 s antes do próximo. Silêncio aqui significa cada quadro de 5 ms abaixo de -55 dB. Nunca aumente esse limite: as caudas das palavras decaem entre -42..-55 dB e um limite mais alto come as consoantes finais.
• 09a ajusta cada borda de corte para fora de sequências de som e a pelo menos 50 ms de distância do som que remove; corta o início e o fim para a primeira e última palavra reais; corta ruídos de colchetes ([UH], [estalo de lábios]) em lacunas de 0,4 s ou mais.
• 09b move qualquer início mantido com som entrando nele de volta para o silêncio (restaura um início cortado).
• O cortador descarta qualquer pedaço abaixo de 1 s sem som (uma "lascas silenciosa" entre dois cortes de salto) e imprime CHECK pedaço curto com som para pedaços sub-1 s que mantém. Ouça cada um.

6. Verifique o corte (não opcional, nesta ordem)

1. qa.md ## Auditoria de intervalos removidos primeiro. Cada lacuna removida é verificada quanto a fala remanescente (energia + uma transcrição isolada). Uma linha FLAGRADO significa que o corte não pode ser enviado: investigue (janela mais alta em dB primeiro, depois ouça qa/removed/spanNN.wav), corrija keep, e re-renderize. Um único fragmento de uma palavra com janela mais alta dB baixa é geralmente um clique ou respiração, não fala; confie no número de energia sobre o texto da transcrição. Linhas corte aprovado estão ok.
2. Leia qa/verbatim_cut.txt de ponta a ponta, como um editor. É a transcrição ipsis litteris do CrisperWhisper DO CORTE. Procure por qualquer frase repetida, fragmento ou retake de frase inteira que tenha sobrevivido. **Nunca verifique um corte com uma transcrição Whisper regular: ela esconde exatamente esses. Retakes de frase inteira ditos consecutivamente após uma pausa só são pegos desta forma.
3. ## Reinícios ainda no corte e ## Corte de borda em qa.md: resolva toda linha FLAGRADO (sequências de números como "928 ... 939" podem ser falsos positivos; leia-as).
4. Verificações que os scripts não podem fazer:
   • duração da saída vs. planejada: um delta acima de 0,6 s é um problema;
   • varra cada junção a 5 fps (quadros 0,5 s de cada lado, a partir de timemap.json): nenhuma junção sobre um borrão de gesto ou um quadro duplicado;
   • nenhuma pausa interna acima de 1,0 s; nenhum pedaço sem um quadro acima de -45 dB;
   • taxa de quadros constante: quadros contados / duração do fluxo deve ser igual ao fps nominal exatamente (30,0000, não 29,98). Gravadores dropam quadros sob carga, e toda ferramenta indexada por quadro a jusante deriva se isso estiver errado.

Reexecute apenas a QA sem recortar: autocut.py --qa-only --workdir <dir>.

Abra clean.mp4 para o humano (open no macOS, xdg-open no Linux).

7. Reporte e passe adiante

O que foi removido (tabela), onde clean.mp4 está, e uma linha: esta é a entrada pré-cortada; diga "tornar dinâmico" para continuar com /dynamic-edit. Legendas para a próxima etapa vêm das palavras ipsis litteris, mapeadas na timeline do corte:

python3 "$THP_HOME/scripts/autocut/verbatim_cut_words.py" <workdir> -o words.json

8. Limpeza, apenas quando o humano disser que o vídeo está pronto

O diretório de trabalho contém synced.mp4 (uma cópia completa do take) e peças tmp/ da renderização. Pergunte antes de deletar. plan.json, transcript.json, verbatim.json e qa.md são pequenos; mantenha-os.

Regras rígidas

• Portão de planejamento é obrigatório. Sem renderização sem o aval do humano.
• Nunca codifique um deslocamento de sincronia. Meça por arquivo, ou use um que o humano forneça.
• O arquivo bruto nunca é modificado.
• Verifique um corte com a transcrição ipsis litteris do corte, nunca uma transcrição Whisper regular.
• Nunca fixe uma borda gerada automaticamente. _meta.pinned_edges é para bordas que um humano verificou contra a forma de onda; fixar bordas de máquina pula a verificação de folga e come palavras.
• Silêncio é apenas abaixo de -55 dB. Nada entre -40 e -55 dB é silêncio em um microfone com gate.
• Nenhum pedaço montado abaixo de 1 s sem fala.
• Quando uma palavra ou instrução for ambígua, faça uma pergunta específica.

Armadilhas

• O Whisper alucina segmentos vazios em ruído ambiente residual, com timestamps além do fim do arquivo. Esperado; o localizador de retakes os filtra. Mil "retakes" em dois segundos no final é um loop do decodificador, não retakes reais, e plan.md informa isso.
• A detecção de sincronia precisa de um rosto na tela. Filmagens apenas de tela: --no-sync, e informe.
• Muitos microfones gravam baixo (cerca de -30 LUFS). autocut não normaliza. O volume pertence ao mestre final (scripts/master/sync_trim.sh --loudnorm); nunca aplique silenciosamente.

Referência completa etapa por etapa: $THP_HOME/docs/AGENT_GUIDE.md.