zroeschen/Vídeo-Produção-Fábrica

Cortar Silêncios (Agente 1 do Pipeline)

Primeira etapa da edição automatizada. Pega uma gravação bruta + sua transcrição a nível de palavra e remove apenas silêncio: pausas mortas antes da primeira palavra e após a última palavra, mais pausas entre palavras maiores que um limite (aparadas até uma respiração natural, nunca um gap zero absoluto). Deixa as palavras do falante intactas — falsos começos, retomadas e gaguejos são trabalho do agente de cortar erros (Agente 2).

Este agente é determinístico e orientado por transcrição, portanto sua saída (*.silence-transcript.json) alimenta de forma limpa os próximos agentes e o validador de sincronização de batidas.

Quando usar

• "cortar os silêncios", "aparar as pausas", "remover pausas mortas", "apertar o ritmo"
• Como o primeiro estágio do fluxo de edição mestre, logo após a transcrição.

Pré-requisitos

Um JSON de transcrição a nível de palavra. Ou no formato ElevenLabs Scribe ({ words: [{ text, start, end, type }], audio_duration_secs }) ou um genérico { words: [{ text, start, end }] }. Gere um com o transcritor do workspace:

node scripts/transcribe-elevenlabs.mjs caminho/para/bruto.mp4    # -> caminho/para/bruto.json

Uso

# 1) Apenas planejamento — calcular o corte, escrever EDL + transcrição re-temporizada (nenhum vídeo tocado)
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcricao.json> \
  --out-dir video-projects/<slug>/assets

# 2) Com um vídeo — também escreve o comando ffmpeg (ainda não renderiza)
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcricao.json> \
  --video video-projects/<slug>/assets/bruto.mp4 --out-dir video-projects/<slug>/assets

# 3) Renderizar o vídeo cortado (ffmpeg local, re-codificar, A/V mantido em sincronia)
#    adicione --apply para realmente executar ffmpeg
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcricao.json> \
  --video video-projects/<slug>/assets/bruto.mp4 --apply \
  --output video-projects/<slug>/assets/editado-silencio.mp4

Opções

Flag	Padrão	Significado
--video <caminho>	—	Vídeo de origem; habilita o comando / renderização ffmpeg
--out-dir <dir>	próximo à transcrição	Onde as saídas são escritas
--output <caminho>	<video-stem>.silenced.mp4	Caminho do vídeo cortado
--gap <s>	0.55	Pausa mínima tratada como silêncio cortável
--head-pad <s>	0.22	Silêncio mantido antes da primeira palavra
--tail-pad <s>	0.34	Silêncio mantido após a última palavra
--apply	desligado	Executar realmente ffmpeg para renderizar o corte

Como decide (as regras de silêncio)

• Pausas abaixo de --gap (0,55s) são deixadas como estão — ritmo natural da fala.
• Para uma pausa cortada, uma respiração natural é mantida, escalada pelo contexto: 0,24s para pausas longas (≥2s), 0,20s após um terminador de frase (. ! ?), 0,14s caso contrário. A respiração mantida é levemente deslocada para o final da frase anterior.
• A pausa morta no início/fim é cortada para --head-pad / --tail-pad.
• Os intervalos de exclusão são mesclados; os intervalos de manutenção são o complemento. O corte é renderizado com um grafo de filtros ffmpeg trim/atrim + concat (escrito em um script *.silence-filter.txt e passado via -/filter_complex), de modo que vídeo e áudio permaneçam sincronizados.

Saídas (escritas em --out-dir)

Arquivo	Finalidade
<stem>.silence-edl.json	Intervalos de manter/excluir, durações, parâmetros — a lista de edição
<stem>.silence-transcript.json	Palavras re-temporizadas na linha do tempo editada (alimenta Agente 2 + batidas)
<stem>.silence-decisions.md	Resumo legível por humanos + maiores pausas cortadas
<stem>.silence-filter.txt	O grafo de filtros ffmpeg (apenas com --video)
<video-stem>.silenced.mp4	O vídeo cortado (apenas com --apply)

O resumo JSON impresso no stdout inclui removed, removedPct, contagens de intervalo e caminhos de saída — útil para o fluxo de trabalho mestre registrar e encadear.

Notas de ajuste

• Padrão para YouTube de cabeça falante (--gap 0.55) remove aproximadamente 15-20% de uma gravação bruta típica como silêncio puro. Reduza --gap para um corte mais rápido e enérgico; aumente para preservar mais espaço natural para respiração.
• Se um corte parecer muito agressivo nos limites de frases, aumente a respiração na quebra de frase, ou aumente --gap.

Entrega para o próximo agente

Passe <stem>.silence-transcript.json (e o silenced.mp4 se renderizado) para o agente de cortar erros. Como os timestamps já estão na linha do tempo editada, o tempo das batidas downstream e o scripts/validate-beat-sync.mjs funcionam sem ajustes adicionais.