JustinChenzeting/Notas-de-aula-para-videos

Notas de aula → vídeo de aula narrado

Você escreve exatamente um arquivo: um lecture.tex beamer contendo os slides, diagramas e narração juntos. Os scripts incluídos fazem todo o resto (instalação, LaTeX → páginas PNG → texto-para-fala → ffmpeg → MP4), então o custo é aproximadamente uma resposta longa por aula, e edições posteriores re-sintetizam apenas as linhas que mudaram.

Início rápido: todo o pipeline

Cada passo é um comando: python3 <skill-dir>/scripts/lv.py <comando>, onde <skill-dir> é o caminho absoluto da pasta que contém este arquivo (no Windows use py -3 em vez de python3). Abaixo, lv é uma abreviação para todo esse comando; escreva-o por extenso cada vez, porque variáveis de shell geralmente não persistem entre seus comandos.

lv setup                           # 0. instalação única; dê a ele um timeout de 10 minutos ou execute em segundo plano
lv init FISICA101-AULA05                # 1. imprime a pasta de trabalho (WORK) e copia o template para dentro dela
lv ingest notas.pdf --out WORK    #    qualquer combinação de .pdf .png .jpg .heic .md .txt; vários arquivos são aceitos
#                                       leia as notas (§1), planeje (§2), escreva WORK/lecture.tex (§3-4)
lv check WORK/lecture.tex          # 2. compile + folhas de contato numeradas + avisos de layout, sem áudio
lv render WORK/lecture.tex         # 3. -> WORK/FISICA101-AULA05.mp4 (ou forneça um caminho de saída)

• O passo 0 instala tudo (uv, um Python 3.12 privado, TinyTeX somente quando não há um LaTeX funcional, ffmpeg, vozes Kokoro) em um cache por usuário: cerca de 3 minutos em uma conexão rápida, até 10 em uma lenta, sem necessidade de direitos de administrador. É idempotente: quando já está feito, termina em segundos e, se for interrompido, executá-lo novamente retoma. Informe ao usuário que é uma instalação única. Ele termina com uma linha iniciando por [setup] READY; qualquer outro final é um erro com uma correção na mensagem ou em references/troubleshooting.md. lv doctor mostra o que está instalado sem alterar nada. Os outros comandos também executam a instalação se ela estiver faltando.
• Execute o pipeline de ponta a ponta sem pedir confirmação em cada etapa. Pare apenas para bloqueios reais: notas que você não pode abrir ou ler, uma etapa de instalação que precisa de uma senha de administrador ou uma solicitação ambígua de uma forma que altere o vídeo.
• WORK padrão é ./lecture-videos/<nome> (ou o work_root configurado pelo usuário). Coloque o MP4 onde o usuário pediu; caso contrário, o padrão em WORK está bom. Mantenha WORK: o .tex, a transcrição e o cache de áudio tornam edições posteriores baratas.

1. Leia as notas primeiro

ingest escreve WORK/source.txt (páginas com uma camada de texto), WORK/manifest.tsv (como cada página foi lida), imagens em tamanho real das páginas que precisam de olhos (WORK/pages/), e folhas de relance (WORK/glance-*.jpg, seis páginas cada).

• Olhe para cada folha de relance. Elas capturam anotações nas margens, passagens destacadas e figuras que a extração de texto perde, aproximadamente pelo custo de token de uma página inteira por folha. Se uma folha mostrar escrita à mão ou anotações em uma página digitada, execute novamente com --visual 3,7-9 para obter essas páginas em tamanho real.
• Páginas manuscritas ou digitalizadas ([manuscrito/digitalizado], [imagem]) devem ser lidas em tamanho real: abra cada imagem e escreva WORK/transcript.md com o conteúdo em ordem, equações em LaTeX e uma descrição de uma linha de cada figura (eixos, rótulos, números-chave). Marque qualquer coisa ilegível como [ilegível] em vez de inventar. Notas manuscritas geralmente são as próprias anotações de aula do usuário, portanto, trate-as como a fonte primária. Se você não puder visualizar imagens, diga isso e peça uma versão digitada em vez de adivinhar.
• Páginas digitadas com figuras ([tem figura]): abra a imagem em tamanho real somente quando precisar de um valor ou rótulo que não consiga ler na folha de relance.
• A partir de então, planeje apenas a partir de source.txt + transcript.md; não releia imagens.
• Notas .docx, .pptx ou .key: exporte-as para PDF primeiro (por exemplo, com LibreOffice soffice --headless --convert-to pdf), depois faça o ingest do PDF.

Enquanto lê, observe erros ou inconsistências nas notas (erros de digitação em números, rótulos trocados). Use o valor correto no vídeo e liste cada correção em seu relatório final.

1b. Preencha lacunas de fontes confiáveis

As notas geralmente são concisas: uma etapa de derivação pulada, um termo usado antes de ser definido, uma figura sem explicação. Quando algo confundiria um aluno e você tiver acesso à web, pesquise brevemente (2 a 5 consultas direcionadas, não uma revisão de literatura) por uma explicação clara no nível certo: notas de curso universitário e OCW, LibreTexts, livros didáticos padrão, artigos de revisão para pontos de nível de pós-graduação. Prefira fontes que concordem com a notação das notas; quando entrarem em conflito, siga as notas e mencione a diferença. Mantenha as adições curtas e a serviço do conteúdo das notas, voltadas primeiro para alunos de graduação, com um comentário opcional de nível de pós-graduação, e liste as fontes que usou no relatório final. Não adicione tópicos que a aula não cobre.

2. Planeje antes de escrever (mentalmente ou em algumas linhas)

• Duração: mire em cerca de 10 minutos (9-11), a menos que o usuário forneça outra duração. Profundidade supera cobertura: se as notas contêm mais do que 10 minutos podem explicar sem pular etapas, cubra o essencial a fundo, depois informe ao usuário o que foi deixado de fora e ofereça uma parte 2. Orce a narração em ≈ 155 palavras por minuto de duração alvo, menos 15 s por checkpoint (a voz padrão fala ~165 ppm; as pausas de linha usam o restante). Um vídeo de 10 minutos ≈ 1.350 palavras + 4 checkpoints (medido: 1.481 palavras + 4 checkpoints = 9,9 min).
• Arco: título → motivação → conceitos na ordem das notas → exemplo(s) resolvido(s) → resumo. Uma ideia por quadro, 1 a 5 etapas de sobreposição por quadro, ~40-70 páginas no total.
• Cadeia lógica: liste a cadeia de raciocínio como etapas numeradas (o que é assumido, o que se segue e por quê). Cada derivação vai do princípio inicial ao resultado sem pular etapas: cada movimento algébrico ganha sua própria linha, cada suposição é declarada onde é usada e cada novo símbolo é definido antes de aparecer. Se as notas pularem ("pode-se mostrar que…"), preencha a lacuna (§1b). Um aluno nunca deve perguntar "de onde veio isso?"
• Os visuais carregam a aula: planeje a imagem antes das palavras. Cada quadro de conceito precisa de um visual: um diagrama, gráfico ou modelo físico (átomos, uma rede cristalina, uma imagem de tanque e cano de um balanço de massa, uma alavanca para a regra da alavanca). Mostre o que os símbolos representam fisicamente, não apenas as equações. Redesenhe cada figura como TikZ/pgfplots original (nunca cole as imagens do material impresso). Construa diagramas passo a passo com sobreposições e use de 3 a 6 animações curtas onde o movimento é o ponto central (um caminho de resfriamento, uma linha de amarração varrendo, uma discordância deslizante). Padrões: references/visual-cookbook.md.

Como explicar (isso é o que torna o vídeo digno de ser assistido)

• Fale como um bom tutor, não como um livro didático. Linguagem cotidiana ("então basicamente", "aqui está o truque", "pense nisso como…"), frases curtas e por que antes de o quê. Antecipe a confusão ("isso parece ao contrário no início, e aqui está por que não é").
• Explique cada equação importante duas vezes:
  1. Matematicamente: de onde vem, passo a passo, e o que cada termo significa.
  2. Fisicamente / intuitivamente: o que significa no sistema real, com uma analogia ou um caso limite ("se c está exatamente em c′, a liga é toda líquida, e a fórmula dá exatamente isso"). Coloque ambos na tela: as linhas matemáticas, depois uma nota de uma linha "fisicamente:" ou uma imagem.
• Após cada derivação, faça uma verificação de sanidade rápida em voz alta: unidades, um caso limite ou um número do diagrama.
• Checkpoints: 3-5 a cada 10 minutos, colocados logo após o conceito que testam (§4).

3. Escreva WORK/lecture.tex

init já copiou assets/template.tex para WORK/lecture.tex; ele mostra todas as construções. Substitua seus quadros de exemplo pela aula. Regras importantes:

• \usepackage{lecturevideo} carrega o tema (papel marfim, tinta escura, um acento vermelho, ou a própria marca do usuário se configurada), a paleta (accent, ink, mute, blu, grn, gold), estilos de figura (eixo pd, dot, lab, note, tie, atom, atomA, atomB) e os comandos de narração. Não reestilize o tema dentro da aula.
• Narração: \say<n>{...}, um por página de sobreposição n, colocado no topo do quadro. \say<2-13>{...} narra um intervalo de animação. \wait<n>{2} mantém uma página em silêncio. Cada página precisa de um; o renderizador nomeia qualquer página que esteja faltando.
• O texto falado é inglês simples: números e símbolos como palavras ("quarenta e seis por cento", "T três", "setecentos e setenta e nove graus", "alfa mais beta"). Sem LaTeX e sem %, &, #, $ dentro de \say. Diga o que olhar ("observe o ponto", "note a linha de amarração"), depois por que isso importa. Expanda o texto do slide em vez de lê-lo palavra por palavra.
• Os slides carregam a explicação real. Um espectador que pausar, retroceder ou revisar o PDF deve ser capaz de acompanhar apenas pelos slides. Ao lado de cada visual, coloque 3-5 marcadores de até ~15 palavras cada (fato-chave, condição, consequência, significado físico). Para derivações, mostre cada etapa como sua própria linha com uma breve justificativa ao lado ("balanço de massa em B", "dividir por W"), revelada à medida que a narração a atinge, terminando com uma linha "fisicamente:" na cor de destaque. Se uma derivação precisar de mais de ~6 linhas, continue no próximo quadro (repita a última linha no topo) em vez de amontoar.
• Layout: visual de um lado (cerca de 55%), texto do outro (columns), ou o visual acima e 2-3 linhas abaixo. Acadêmico e limpo: uma ideia por quadro, a cor de destaque apenas para ênfase, resultados e marcadores de estado.
• Macros de figura que usam #1 vão no preâmbulo (um # no corpo do quadro quebra o beamer).
• Qualquer pacote LaTeX que a aula precisar (siunitx, chemfig, …) pode ser usado; quando o TinyTeX privado estiver em uso, pacotes faltantes são instalados automaticamente na primeira compilação.

4. Checkpoints no estilo de prova

\examq[5]{Checkpoint: regra da alavanca}
  {pergunta no slide}{pergunta falada}{resposta no slide}{resposta falada}

Isso cria 1 página de pergunta (narrada, depois "Você tem 5 segundos."), 5 páginas silenciosas de contagem regressiva de um segundo com um anel que encolhe e 1 página de resposta narrada.

Escreva perguntas como uma prova real sobre esta aula: números concretos fornecidos, uma tarefa clara, respondível em ~30 s por alguém que acompanhou o vídeo, com uma resposta curta e trabalhada. Misture tipos:

• Calcular: "Uma liga de 35% em peso de B a T₃ com c′ = 20, c″ = 85: qual fração é líquida?"
• Ler o diagrama: "Uma liga de 20% em peso de Ag está a 900 °C. Quais fases e aproximadamente quais composições?"
• Prever: "Uma liga de 5% em peso de Ag é resfriada lentamente de 800 °C a 500 °C. O que se forma e onde?"
• Identificar / classificar: "Líquido → α + β a uma temperatura: qual reação invariante é esta?"
• Encontrar o erro: "Um estudante usa c″ − c sobre a linha de amarração para a fração sólida. O que deu errado?"

Evite perguntas vagas ("o que é uma fase?"), curiosidades não ensinadas nas notas e perguntas de múltiplas partes. A resposta deve mostrar o raciocínio, não apenas o resultado. Pegue os números do diagrama ou equação que o vídeo acabou de mostrar, de modo que pergunta, figura e resposta concordem. Perguntas baseadas em um equívoco comum funcionam bem ("dobrar o espaçamento dos pinos dobra a tensão na fonte: verdadeiro ou falso?"). Mantenha a contagem regressiva de 5 segundos (o slide diz "pause se precisar de mais tempo"); use \examq[8] apenas se o usuário pedir pausas mais longas.

5. Verifique, depois renderize

lv check WORK/lecture.tex

Ele compila, imprime páginas, palavras narradas, uma duração estimada e avisos layout: (conteúdo muito alto ou linhas muito largas, com números de linha de origem) e escreve folhas de contato numeradas WORK/lecture_build/sheet-*.png. Olhe as folhas para colisões, rótulos cortados, marcadores fora da curva ou quadros vazios; corrija-os e execute novamente (barato). Se você não puder visualizar imagens, corrija todos os avisos layout: e mantenha as figuras simples. Se a estimativa errar a duração alvo em mais de ~10%, ajuste ou estenda a narração agora (não os checkpoints). Então:

lv render WORK/lecture.tex ["SAIDA/Titulo da aula.mp4"]

Narrador: voz neural do Microsoft Edge en-GB-SoniaNeural (grátis, precisa de internet) a +10%, 720p. Offline ou se o Edge falhar, ele cai automaticamente para a voz Kokoro incluída bf_emma. Opções: --tts edge|kokoro|say, --voice <id or profile>, --rate, --height. Quando o usuário nomear uma voz ou quiser a sua própria (incluindo uma voz clonada), leia references/voices.md.

As legendas vêm de graça. Cada renderização também escreve SAIDA.srt e SAIDA.vtt ao lado do MP4 e incorpora uma faixa de legenda selecionável, construída a partir do texto \say e cronometrada a partir do áudio sintetizado, para que não custem tokens e permaneçam sincronizadas após edições. Nunca transcreva o vídeo ou escreva legendas manualmente. Elas mostram a narração conforme escrita (antes das re-ortografias lexicon.tsv). --no-subs as desativa.

Correções de pronúncia vão em WORK/lexicon.tsv (escrita<TAB>falada), aplicadas apenas ao áudio. Re-renderizar após uma edição leva segundos, porque as linhas não alteradas vêm do cache de áudio.

6. Relate

Forneça o caminho do vídeo (e suas legendas .srt/.vtt), duração, contagem de páginas e checkpoints, quaisquer correções às notas, as fontes usadas para preencher lacunas, quais figuras são redesenho esquemático e o que foi deixado de fora (ofereça uma parte 2). Mantenha WORK para edições.

Configurações pessoais

Marca (logotipo, cores, tema beamer de uma instituição), voz padrão, pastas de trabalho e saída ficam fora da skill, na pasta de configuração do usuário, para que a skill permaneça portátil: references/customization.md. Nunca edite os próprios ativos da skill para as preferências de um usuário.

Por que é construído assim

• Um arquivo de origem mantém slides e narração alinhados; o LaTeX escreve o mapa de narração preciso por página (.narr) por si só