Sincronização Voz ↔ Vídeo
Regra zero: a faixa de voz dita o ritmo. A imagem é sincronizada com o áudio medido, nunca com durações estimadas.
1. Escreva a narração
- Comece pela situação do espectador, não por uma definição. Uma única linha narrativa; causa antes do efeito.
- Converta números para uma escala perceptível ("do tamanho de uma lista telefônica", não "3,2 MB").
- Metáforas devem ter peso; o narrador tem um ponto de vista.
- Não descreva o que a imagem já mostra; diga o que a imagem não pode.
- Termine retomando a abertura. As fronteiras de capítulo fazem a transição: a última linha do capítulo N prepara a primeira linha do N+1.
- Calcule pelo ritmo de fala: Inglês ≈ 125–150 palavras/min (vozes TTS variam — meça uma amostra); Português ≈ 140–160 palavras/min; Chinês ≈ 4–5,5 caracteres/s.
Formate o arquivo de roteiro (um parágrafo = uma cena, | divide blocos de legenda):
# CAPÍTULO 1 Por que os mapas mentem
Todo mapa que você já viu | foi desenhado por alguém | com um motivo.
Mercator queria que os marinheiros | mantivessem um curso reto.
## gap 0.6
## gap <segundos> pede uma pausa de pelo menos essa duração após o parágrafo (pausa para o último visual). Produza-a no áudio — SSML <break time="600ms"/> para TTS, ou silêncio inserido ao montar arquivos por parágrafo. A ferramenta de linha do tempo nunca altera timings; ela verifica a pausa.
2. Trave o script
Mostre o script completo com contagem de palavras e duração estimada e obtenha uma aprovação explícita. Após a trava, cada timing é derivado do áudio; alterar uma palavra re-temporiza todas as cenas seguintes.
3. Produza a voz
- TTS (padrão quando não há gravação): pergunte ao usuário por um motor/voz preferido. Enviar texto para um TTS em nuvem (ElevenLabs, Azure, OpenAI, Google, edge-tts) compartilha o script com esse provedor — confirme primeiro. Opções locais (Kokoro, Piper) mantêm tudo na máquina.
- Locução gravada: aceite WAV 48 kHz. Corte silêncio, mantenha respirações naturais, normalize depois na mixagem.
- Mantenha um arquivo por parágrafo ou um arquivo mestre com timestamps; ambos funcionam com a ferramenta de linha do tempo.
4. Obtenha timestamps
Use timestamps de palavra ou segmento da resposta da API TTS, ou force-align o áudio com o script (WhisperX, whisper-timestamped, stable-ts ou Whisper com word_timestamps=True). Normalize-os para este JSON:
{"segments": [{"text": "Todo mapa que você já viu", "start": 0.00, "end": 1.42,
"words": [{"word": "Todo", "start": 0.00, "end": 0.21}]}]}
5. Construa a linha do tempo
python3 <plugin-root>/scripts/build_timeline.py words.json --script script.txt --fps 30 \
--out-dir timeline/ --max-chars 42 --min-dwell 1.0
Produz timeline.json (cenas com quadros de início/fim, blocos de legenda, inícios de capítulo), captions.srt, captions.vtt e avisos para: palavras do script ausentes no áudio (ou palavras do áudio ausentes no script), legendas muito longas ou rápidas para ler, cenas cuja última legenda deixa menos de --min-dwell segundos antes da próxima cena (adicione uma pausa no áudio ou mescle), pausas ## gap solicitadas que o áudio não possui e silêncios com mais de 3 s. Palavras que um alinhador forçado deixou sem timing (comum para números no WhisperX) são interpoladas entre seus vizinhos. Alimente timeline.json para a composição; nunca redigite números de quadro manualmente.
6. Regras de legenda
- ≤42 caracteres por linha, ≤2 linhas, ≥1,0 s na tela, ≈17 caracteres/s de velocidade de leitura máxima.
- Quebre em limites de frase, nunca entre artigo e substantivo.
- Mantenha as legendas fora da zona inferior da interface do usuário em 9:16 e longe de texto de interface na tela.
- Legendas incorporadas para redes sociais; SRT/VTT sidecar para YouTube e players web.
7. Mixagem
| Camada | Alvo |
|---|---|
| Loudness integrado (final) | −14 LUFS para social/web (−16 aceitável); −23 LUFS para broadcast |
| Pico verdadeiro | ≤ −1 dBTP |
| Música sob locução | duck 8–12 dB enquanto a fala estiver presente, 150–300 ms ataque/soltura |
| Efeitos sonoros | ≈10 dB abaixo da música; no quadro causador, não depois |
Meça com <plugin-root>/scripts/qc.sh loudness final.mp4 (adicione -23 para broadcast). Quando as skills de áudio do HyperFrames estiverem instaladas, hyperframes-audio fornece ducking ("entalhe de voz"), EQ e automação dentro da composição; caso contrário, use sidechaincompress e loudnorm do FFmpeg (duas passagens).
8. Ponto de verificação de pré-visualização
Renderize os primeiros ≤30 s com voz, legendas e música e pergunte: "Voz, ritmo, tamanho da legenda e ritmo — OK?" Alterar o ritmo após este ponto significa executar novamente o TTS e re-temporizar tudo.