FnSGit/video-craft-skill

video-craft

Transforme qualquer tópico em um vídeo narrado. Primeiro, selecione o motor de renderização com base na forma do conteúdo; depois, siga a linha de produção compartilhada.

Anteriormente era anything2explainer (apenas vídeos explicativos com Remotion). Esta divisão extrai os ativos independentes de renderizador para core/, isola os relacionados à renderização em backends/, e adiciona routing/ para a seleção do backend.

Quando usar

• O usuário fornece um tópico para um vídeo explicativo/derivação/tutorial/promocional; ou um artigo para ser convertido em vídeo.
• Não se aplica a: recriação de um vídeo existente, narração com rosto real, ou vídeos predominantemente ao vivo.

Quatro pontos de confirmação (deve parar e aguardar resposta do usuário)

1. Duração, idioma + recomendação de backend (pergunte junto com o envio da pesquisa da fase 1): Apresente o resultado da decisão de routing/router.md junto com a tabela de durações, duas perguntas em uma. Se o usuário rejeitar a recomendação, siga a escolha dele.
2. Roteiro finalizado (fase 2, antes da dublagem): Texto completo + divisão em capítulos + contagem de palavras/duração estimada, pergunte "Este roteiro está ok?". Nomes de capítulos e seções HUD em linhas separadas. Para vídeos com múltiplos capítulos, liste as duas frases de transição de cada capítulo lado a lado. Após a aprovação, os números de quadro mudam todos; não altere o texto.
3. Dublagem (antes de executar tts_build.py): Padrão: chinês com edge-tts Yunxi, inglês com kokoro am_liam. Se houver preferência, o usuário pode fornecer seu próprio arquivo wav em script/audio.wav e preencher a timeline manualmente.
4. Amostra dos primeiros 30 segundos (fase 5a, antes de distribuir os outros grupos): Pergunte "O estilo / tamanho da fonte / velocidade da narração / ritmo estão ok?". Alterar aqui custa o trabalho de 1 grupo; alterar após a renderização completa custa o trabalho de todos os grupos.

Fluxo (8 fases)

Fase 0  Criar projeto      → Chame o new_project.sh do backend correspondente conforme o resultado do roteamento
Fase 1  Pesquisa           → core/research-brief.md (1 agente em paralelo)      [Ponto de confirmação 1]
Fase 2  Roteiro + Timeline → core/narration-guidance.md + tts_build.py         [Pontos de confirmação 2, 3]
Fase 3  Storyboard         → Escreva no formato do backend, core/render_storyboard.py
Fase 4  Elementos gráficos → Complete conforme o backend (remotion: ui.tsx / manim: figures.py)
Fase 5a Amostra           → Primeiro faça o grupo 1, preview.sh gera os primeiros 30s          [Ponto de confirmação 4]
Fase 5b Construção paralela → Cada grupo um agente, use agent-build-rules.md do backend
Fase 6  Renderização       → render.sh do backend → mp4 + fin_frames/
Fase 7  QC e correções     → core/motion_check.py + frame_metrics.py + qc-rules do backend
Fase 8  Entrega            → Instruções de entrega.md (registre o backend usado e a justificativa da decisão)

Roteamento: primeiro selecione o backend

Leia obrigatoriamente routing/router.md. Versão resumida:

Forma do conteúdo	Backend	Status
Derivação contínua de fórmulas / provas / transformação de símbolos	manim	✅ V1
Explicação de conceitos (o que é X / como funciona / por quê)	remotion	✅ V1
Tutorial real de terminal (instalação / configuração / execução de comandos)	terminal	⏸ V2
Promocional de produto / vídeo curto para redes sociais / walkthrough de PR	hyperframes	⏸ V3

A decisão não é baseada no nome do tópico, mas sim se a narração está manipulando símbolos continuamente: "O que a Transformada de Fourier faz" → remotion (explicação intuitiva); "Derivar a Transformada de Fourier a partir das Séries de Fourier" → manim (derivação contínua).

Quando um backend não implementado for selecionado, deve informar o usuário e explicar o plano de contingência, sem trocar silenciosamente de backend.

Pré-requisitos (obrigatório para máquinas novas)

Todos os backends

# Scripts Python em core/ precisam disso. Use Python 3.13 para criar o venv (3.14 tem risco de faltar wheel)
uv venv --python 3.13 ~/.venvs/video-craft
uv pip install --python ~/.venvs/video-craft/bin/python numpy pillow scipy edge-tts

⚠ Sem este venv, tts_build.py / motion_check.py / frame_metrics.py não funcionarão. Essa é uma dor já enfrentada pelo anything2explainer: dependência de venv não documentada travou todo o fluxo em máquinas novas.

Backend remotion

brew install ffmpeg          # Para extrair quadros
# Node 22+; o projeto é criado com npm install automático via new_project.sh

Backend manim

brew install pkg-config cairo pango     # Necessário para compilar pycairo; sem isso manim não instala
brew install --cask basictex            # Necessário para formatação real de fórmulas MathTex; sem isso, volta para aproximação ASCII

Sem basictex, o manim ainda funciona (com MANIM_TEX=text automático), mas as fórmulas serão aproximações ASCII como a/b. Vídeos de derivação DEVEM ter basictex — a qualidade da formatação de fórmulas é a espinha dorsal desse tipo de vídeo.

Estrutura de diretórios

video-craft/
├── SKILL.md                   ← Este arquivo
├── routing/
│   └── router.md              Árvore de decisão do backend + mecanismo de override + casos de borda
├── core/                      Independente de renderizador, compartilhado por todos os backends
│   ├── research-brief.md          Processo de pesquisa e regras de factualidade
│   ├── narration-guidance.md      13 princípios de roteiro para narração
│   ├── narration-storyboard.md    Formato do roteiro/storyboard e sistema de tokens
│   ├── tts_build.py               Dublagem + timeline.json
│   ├── render_storyboard.py       Substituição de tokens do storyboard
│   ├── motion_check.py            QC de ritmo (leitura de quadros, multi-backend)
│   ├── frame_metrics.py           QC de composição (leitura de quadros, multi-backend)
│   ├── sheet.py                   Grade de miniaturas (leitura de quadros)
│   └── lessons.md                 Lições aprendidas e causas raiz
└── backends/
    ├── remotion/              Vídeos explicativos de conceitos (antigo anything2explainer)
    │   ├── template/               Projeto React
    │   ├── scripts/                render/preview/still/test_render/new_project/selfcheck
    │   ├── reference/              style-guide/motion-vocabulary/composition-and-light/
    │   │                            agent-build-rules/agent-qc-rules/prompts/math-physics
    │   └── examples/rag/           Vídeos de exemplo (padrão de qualidade)
    ├── manim/                 Vídeos de derivação
    │   ├── template/               Projeto Python (common/ + scenes/)
    │   ├── scripts/
    │   ├── reference/
    │   └── README.md               Conclusões do ambiente real (cairo/latex/pycairo)
    ├── hyperframes/           Reservado para V3
    │   └── README.md
    └── terminal/              Reservado para V2 (confirmado como obrigatório pelo usuário)
        └── README.md

Referência rápida de arquivos principais

O que fazer	Qual arquivo usar
Decidir qual backend usar	routing/router.md
Enviar agente de pesquisa	core/research-brief.md
Escrever roteiro	Leia primeiro core/narration-guidance.md, formato em core/narration-storyboard.md
Gerar dublagem + timeline	core/tts_build.py
Gerar storyboard	core/render_storyboard.py
QC de ritmo	core/motion_check.py
QC de composição	core/frame_metrics.py
Visualizar vídeo completo	core/sheet.py
Criar projeto	backends/<backend>/scripts/new_project.sh
Enviar agente de construção	backends/<backend>/reference/agent-build-rules.md
Enviar agente de QC	backends/<backend>/reference/agent-qc-rules.md

Formatos de storyboard específicos por backend

Backend	Unidade de storyboard	Formato
remotion	Um plano (uma frase de narração com uma cena)	Token {S12.from-8} em backends/remotion/reference/narration-storyboard.md
manim	Um passo de derivação	Formato DP em backends/manim/reference/storyboard.md

Ajuste de limites de QC por backend

Os limites padrão de core/motion_check.py foram definidos para vídeos conceituais com Remotion; outros backends precisam de ajustes:

# remotion (padrão)
python3 core/motion_check.py --frames fin_frames

# manim (derivação): Aumentar limite de parada para 5s (deixar tempo para leitura após operação), desligar critério de hold (sem conceito de saída de cena)
python3 core/motion_check.py --frames fin_frames --shots DP01:1-170 --still-max 5.0 --no-hold

# terminal (V2): Paradas mais longas ao esperar saída de comandos, estimado 8-10s

Princípios rígidos (comuns a todos os backends)

1. Originalidade: Todas as cenas devem ser geradas por código ou gravações reais; é proibido usar quadros ou trechos de vídeos existentes.
2. Fontes verificáveis: Cada número, termo, ano ou nome de pessoa na tela deve ter uma URL de origem no documento de pesquisa.
3. Contexto unificado em todo o vídeo: Narração e cenas devem usar o mesmo exemplo transversal.
4. Não alterar o texto após aprovação: Os números de quadro são codificados; qualquer alteração exige realinhamento completo do vídeo.
5. Informar o backend: O resultado da decisão de roteamento e os planos de contingência devem ser comunicados ao usuário, sem decisões silenciosas.

Vídeos de exemplo e padrão de qualidade

• Backend remotion: backends/remotion/examples/rag/ (4'35", 44 frases, 44 planos) — Antes de começar, veja examples/rag/frames/overview_*.jpg para estabelecer o padrão.
• Backend manim: V1 sem vídeos de exemplo, apenas validação de ciclo mínimo completo. Os exemplos de padrão ficarão para V2.
• Contraexemplo: backends/remotion/examples/contrast/

Projetos migrados do anything2explainer

Os projetos em ~/Projects/ai-video/ (linear-function / transformer / a2e-fourier / py-course) foram criados com a skill antiga e ainda usam a estrutura antiga (template/scripts/). Eles continuam funcionais — a skill antiga foi mantida como deprecated, não a remova.

Novos projetos devem usar a nova estrutura desta skill.