aleksanderstevens191-sudo/course-video-skill

Vídeo do curso

Você transforma o material didático do aluno em vídeos de estudo. A única regra que diferencia esta skill:

Todo número, exemplo e afirmação vem do material didático do aluno. Nada é inventado. Os alunos usam esses vídeos para estudar para provas corrigidas pelo professor deles. Um exemplo "melhorado" com números inventados, uma fórmula com notação diferente ou um fato de fora do curso é um erro, mesmo que seja economicamente/fisicamente/etc. correto.

0. Requisitos (verificar uma vez)

python3 -m pip install -r requirements.txt && python3 -m playwright install chromium
ffmpeg -version | head -1          # brew install ffmpeg  /  apt install ffmpeg

Opcional: Blender 4.2+ para cenas 3D e o mascote apresentador (BLENDER=/caminho/para/blender se não estiver no PATH), pdftotext (poppler) ou pip install pypdf para ler slides em PDF, openai-whisper para transcrever gravações, XAI_API_KEY para a voz Grok (caso contrário, a voz neural gratuita da Microsoft é usada).

1. Coletar as fontes

Crie uma pasta <curso>/sources/ e coloque apenas material do curso nela: transcrições de aulas (.txt/.srt/.vtt), slides (.pdf ou texto exportado), anotações do aluno, listas de exercícios, provas anteriores.

• Gravação mas sem transcrição → whisper aula.mp4 --model base --output_format txt --output_dir sources/
• .docx → textutil -convert txt arquivo.docx (macOS) ou pandoc arquivo.docx -t plain -o arquivo.txt
• Pergunte ao aluno quais aulas/tópicos o vídeo deve cobrir. Não adicione material de outras semanas a menos que solicitado.

Leia as fontes completamente antes de escrever qualquer coisa. Anote a notação exata do professor, os termos, exemplos resolvidos e números.

2. Escrever o roteiro (JSON de conteúdo)

Escreva <curso>/<nome>.json seguindo engine/SCHEMA.md (tipos visuais, palavras de transição, formato de quiz, limites de layout). examples/lemonade/ é um exemplo pequeno completo.

Regras:

• Exemplos: use os exemplos resolvidos da própria aula com os números da própria aula. Se a aula usa "preço $4, 3 unidades", o vídeo usa "preço $4, 3 unidades", não "preço $10, 5 unidades".
• Quizzes: retire-os das questões de prática, perguntas de clicker ou exemplos resolvidos do curso. Se você escrever uma nova pergunta, construa-a apenas com números das fontes e informe isso no rótulo do quiz ("Prática", não "Questão de prova").
• Números derivados (um total que você calculou, uma diferença) são permitidos, mas declare cada um no mapa "derived" de nível superior com a aritmética, usando apenas números das fontes: "derived": {"16": "4 * 4", "-6": "120 - 126"}.
• Pequenas contagens que não são dados ("Três coisas para lembrar", "Passo 2") vão em "allow": ["3"]. 0 e 1 são sempre permitidos.
• Notação e termos: use os do professor (se a aula escreve "RMg = CMg", não mude para "∂R/∂q").
• Se um fato que o vídeo precisa não estiver nas fontes, pare e pergunte ao aluno pelo material, ou deixe-o de fora. Nunca preencha a lacuna com conhecimento geral.
• A narração (say) é escrita para o ouvido: palavras, não símbolos ("4 vezes 4 é 16 reais").

3. Verificar cada número contra as fontes (obrigatório, antes de construir)

python3 tools/check_sources.py <curso>/<nome>.json <curso>/sources --report <curso>/<nome>.sources.md

Ele extrai cada número da narração, texto na tela, opções de quiz e quaisquer rótulos de cena 3D, e encontra cada um nas fontes (dígitos ou palavras escritas por extenso, ex.: "cento e vinte"). Números derivados são recalculados e seus operandos verificados. Ele deve sair com código 0 antes de você construir. Para cada problema, ele relata:

• o número é um erro de digitação ou inventado → corrija o roteiro para usar o número da fonte;
• é um cálculo real → adicione-o a "derived";
• está nas fontes em uma forma que o verificador não capturou (ex.: em uma imagem) → peça ao aluno para confirmar, depois adicione-o a "derived" ou "allow" com uma nota em sua resposta.

Em seguida, leia você mesmo a seção de Evidências do relatório, verificando por amostragem se cada número é usado no mesmo significado que na fonte (o verificador compara valores, não significados: "$40" o preço vs. "40 unidades" a quantidade).

4. Construir e renderizar

cd engine
python3 build.py ../<curso>/<nome>.json              # voz, tempo, legendas, música (TTS=xai XAI_API_KEY=... para Grok)
python3 lint.py build/<video-id>/spec.json            # elementos visuais que chegam tarde
python3 qa.py <video-id>                              # imagens de cada batida + folhas de contato: OLHE para elas
OUT=../out python3 render.py <video-id> --workers 6   # renderização completa 1080p -> ../out/<video-id>.mp4 + .srt

Olhe as folhas de contato do QA antes de renderizar: texto sobreposto, telas vazias, números errados na tela.

5. Opcional: cenas 3D, mascote, efeitos sonoros

Uma batida com "v": {"type": "clip", "scene": "<nome>"} reproduz uma cena do Blender de engine/blender/scene_defs/<nome>.py (veja o docstring em engine/blender/scenelib.py; market.py e safe.py são exemplos completos, escritos para um curso de economia, então seus rótulos carregam os números daquele curso. Altere os rótulos para corresponder às suas fontes). Os rótulos da cena também são verificados por check_sources.py.

cd engine
python3 blend.py prep <video-id>                         # linha do tempo do mascote + entradas por cena
python3 blender/stills.py <cena> --dry                  # capture erros rapidamente, depois sem --dry para imagens
python3 blend.py clips <video-id>                        # renderize as cenas 3D (lento: minutos por cena)
python3 blend.py mascot <video-id> && python3 blend.py pack <video-id>
python3 sfx.py mix <video-id>                            # efeitos sonoros sob a narração
OUT=../out python3 blend.py comp <video-id>              # -> ../out/<video-id>-3d.mp4
OUT=../out python3 blend.py site <id1>,<id2> --title "Meu curso" --out ../out/site   # uma página web com capítulos

A renderização é lenta e consome muito disco (vários GB de quadros por vídeo durante a execução). Verifique o espaço livre primeiro, renderize uma cena de cada vez em laptops e mantenha a máquina acordada.

6. Entrega

Informe ao aluno: onde está o vídeo, quanto tempo dura, quais aulas cobre e o resultado da verificação das fontes (números verificados, quaisquer derivados ou permitidos). Se algo nas fontes estava ambíguo, diga o que você assumiu. Lembre-o de que o vídeo é uma ferramenta de estudo construída a partir dos materiais dele, não um substituto para a aula, e que os materiais do curso podem não ser de sua propriedade para publicar: verifique antes de postar um vídeo publicamente.