Ahmed-OC/motion-video-skills

Narração TTS — com temporização em nível de palavra

Temporizações de palavra são o que fazem as legendas aparecerem na palavra certa e as cenas serem ritmadas na sílaba certa. Sempre gere a NARRAÇÃO PRIMEIRO e anime de acordo com suas temporizações reais — nunca o contrário.

Início rápido (gratuito, sem chave de API)

pip install edge-tts
python scripts/vo_gen.py --text "Pythagore. Dans un triangle rectangle…" --voice fr-FR-DeniseNeural --rate -4%

Saídas (prefixo vo por padrão):

• vo.mp3 — o áudio
• vo_words.json — { words:[{text,fromMs,toMs}], captions:[{startMs,durationMs,text,tokens[]}] } onde as legendas são agrupadas em páginas de ≤3 palavras (intervalo >700ms quebra uma página) com janelas por palavra
• vo.js — window.VO_B64 (mp3 em base64) + window.VO_DATA (o JSON), pronto para uso em um pipeline de canvas/busca: <script src="vo.js"> depois decodeAudioData para reprodução e VO_DATA.captions para desenho

Listar vozes: python scripts/vo_gen.py --list-voices fr (também: en, ja, es, de, pt, zh, ar…).

Menu de vozes (seleção rápida)

Idioma	Narrador calmo	Enérgico
fr	fr-FR-DeniseNeural	fr-FR-HenriNeural
en	en-US-AriaNeural	en-US-GuyNeural
ja	ja-JP-NanamiNeural	ja-JP-KeitaNeural
es	es-ES-ElviraNeural	es-ES-AlvaroNeural
de	de-DE-KatjaNeural	de-DE-ConradNeural
pt	pt-BR-FranciscaNeural	pt-BR-AntonioNeural
zh	zh-CN-XiaoxiaoNeural	zh-CN-YunjianNeural

Sintaxe de taxa: --rate -4% mais lento / +10% mais rápido. Frases curtas fornecem limites de palavra mais limpos; regenere por frase para refazer uma linha ruim sem refazer a faixa inteira.

Pegadinhas (aprendidas da pior forma)

• edge-tts ≥ 7: limites de palavra estão DESLIGADOS por padrão — boundary="WordBoundary" é obrigatório (vo_gen.py já passa isso). Sintoma do bug: áudio OK, words vazio.
• HTTP 403 do serviço: sua versão do edge-tts é muito antiga para o esquema de token atual — pip install -U edge-tts (use um venv se a instalação do sistema estiver bloqueada).
• Os offsets de palavra estão em unidades de 100 nanossegundos no stream bruto; divida por 10⁴ para ms.

Alternativas e upgrades

• Kokoro (pip install kokoro) — TTS neural local, 82M parâmetros, vários idiomas.
• Piper — totalmente offline, rápido, downloads de voz por idioma.
• ElevenLabs — pago, multilíngue v2; a API with-timestamps retorna tempos em nível de caractere que alimentam as legendas diretamente.
• VOICEVOX (Japonês) — API HTTP local em localhost:50021, temporizações por fonema (ótimo para animação de lábios em JP).
• Qualquer áudio existente → temporizações de palavra via faster-whisper:

  pip install faster-whisper
  python - <<'EOF'
  from faster_whisper import WhisperModel; import json
  m = WhisperModel("small"); segs, _ = m.transcribe("track.mp3", word_timestamps=True)
  json.dump([w._asdict() for s in segs for w in s.words], open("words.json","w"))
  EOF
  

Mixagem em um vídeo (referência rápida)

Voz, música e SFX como faixas SEPARADAS, depois: base musical −18…−22 LUFS abaixo da narração, duck com sidechaincompress do ffmpeg (narração como gatilho), final loudnorm=I=-14:TP=-1.5:LRA=11. Estilo de legenda que funciona: maiúsculas em negrito, 1–3 palavras por pop, palavra ativa em cor de destaque com um efeito de escala de ~20%, fundo preto tipo pílula ou contorno para contraste, mantido fora das zonas de UI da plataforma.