Explicador guiado por SRT

SRT-Driven Video (Fluxo de Vídeo SRT)

Transforme um roteiro de locução em um vídeo explicativo com visuais gerados por código. SRT como única referência temporal, progresso em cinco fases, pausa ao final de cada uma para confirmação do usuário.

Ambiente e Dependências

• Windows: Playwright (channel="msedge", usa Edge local, sem instalar Chromium) + imageio-ffmpeg (fornece ffmpeg; não inclui ffprobe, usa ffmpeg -i stderr para análise).
• Instalação: pip install playwright imageio-ffmpeg (scripts já tratam localização do ffmpeg).
• Todos os scripts em scripts/ foram testados no Windows; Linux/macOS precisam remover channel="msedge" e usar ffmpeg do sistema.

Visão Geral das Cinco Fases

Fase	Produto	Portão de Confirmação
0 Roteiro	outline.md + tabela de decisões	Usuário confirma roteiro e decisões
1 Roteiro+SRT	script.md / subtitles.srt / notas_apresentador.md	Usuário confirma roteiro
2 Storyboard	storyboard.json (obrigatório passar em check_timeline.py)	Usuário confirma storyboard
3a Primeira cena + biblioteca de componentes	assets/shared/ + scene-001 amostra baixa resolução	Usuário aprova estilo antes da produção em massa
3b Cena por cena em lote	scenes/scene-NNN/scene.mp4 × N	Usuário revisa cenas-chave
4 Montagem final	output/final.mp4 + cover.png	Usuário confirma vídeo final

Detalhes do fluxo, campos da tabela de decisões, armadilhas comuns (imageio-ffmpeg sem filter_complex_script, armadilha de level do alimiter etc.) em references/pipeline.md.

Três Contratos Essenciais (não opcionais)

1. Referência temporal SRT: limites das cenas coincidem com limites das legendas; erro total ≤0,1s; python scripts/check_timeline.py <project_dir> verifica em cada fase.
2. WORKLOG de continuidade: criar WORKLOG.md na raiz do projeto (modelo em references/worklog-template.md), único estado entre sessões; tabela de decisões após travada não deve ser alterada; a partir das fases 3/4 os arquivos de base (outline/script/SRT/notas/storyboard/assets/shared/scenes) são congelados.
3. Portão de confirmação por fase: após cada fase, pausar e aguardar confirmação explícita do usuário antes de prosseguir.

Renderização de Cena (Fase 3)

Cada cena é uma página HTML independente, implementando window.setTime(t) para renderização determinística (toda animação é função pura de t); queima de legenda usa o elemento de contrato unificado div#subtitle. Contrato completo de desenvolvimento, fluxo de qualidade (check_frames.py painel de quadros-chave), regras de design em references/visual-authoring.md.

Modelo inicial: assets/neon-theme/ (tema cyberpunk já aprovado: theme.css + components.js, com partículas/dígitos voando/cartões de dados/barras de comparação/indicadores de risco/transições/componente de legenda) — usuário pode copiar diretamente para assets/shared/ do projeto para obter o mesmo estilo; outros estilos seguem a mesma estrutura.

python scripts/render_scene.py scenes/scene-001 --duration 10.5 --fps 30 --size 960x540   # amostra baixa resolução
python scripts/check_frames.py scenes/scene-NNN --times 0.5,3,6,9.2                        # qualidade antes de renderizar
python scripts/render_all.py .                                                             # lote completo
python scripts/render_all.py . --no-subtitle --outdir output/nosub                         # variação sem legenda
python scripts/concat_final.py .                                                           # montagem + capa

Módulo de Efeitos Sonoros Opcional (desligado por padrão)

Ativado apenas se o usuário explicitamente quiser efeitos sonoros nos pontos-chave, e já travado na tabela de decisões da fase 0. Material via Freesound CC0 (verifica licença um a um), timeline em assets/sfx/mix_timeline.json e submetido a pré-aprovação do usuário; entrega em duas rotas, escolha uma: mixagem automática com FFmpeg (mix_sfx.py) ou lista de marcação para剪映 (make_cue_sheet.py) para inserção manual — a segunda é mais estável na prática. Processo completo em references/sound.md.

Habilidades / Ferramentas Externas de Referência

• vibe-motion/sound (GitHub, clonar para tools/sound/): CLI de busca/download do Freesound. Repositório sem licença, apenas ferramenta interna de download; licença segue a declaração CC0 de cada efeito no Freesound.

Especificações de Entrega

final.mp4: 1920×1080 / 30fps / h264 / yuv420p, duração exata do span total do SRT; cover.png extraído do quadro de pico (determinístico por amostragem); após verificar duração, número de frames, especificações, nível de áudio, atualizar WORKLOG e reportar.