Lecture Video Explainer

O que Lecture Video Explainer faz?

Objetivo: os alunos devem conseguir entender uma aula sem assisti-la e revisá-la rapidamente antes da prova. O vídeo é, portanto, uma ferramenta de aprendizado, não uma vitrine: fiel à aula, explicado de forma simples, memorável e sempre legível.

Três princípios guiam cada decisão:

1. Não invente nada. Toda afirmação, número, definição e gráfico tem respaldo no material da aula. Simplificar é bem-vindo; acrescentar fatos, não. Quem faz a prova depois de assistir precisa confiar que o conteúdo estava exatamente assim na aula.
2. Tudo legível, nada cortado. Nenhum texto parcialmente visível, sem estouro de borda, sem fontes minúsculas. Uma única frase cortada destrói a confiança em todo o vídeo.
3. Voz fluente, visuais calmos. O narrador não faz pausas longas. Onde há muito para ver, a imagem segura brevemente antes de continuar – como uma boa apresentação.

A entrega é o vídeo finalizado, baixável como um único MP4 diretamente no Claude. O usuário nunca executa código, scripts ou comandos e nunca precisa colar chave de API – tudo técnico acontece do seu lado, com as ferramentas que este ambiente oferece. Sem player, sem arquivos extras, a menos que o usuário peça explicitamente (legendas como arquivos, transcrição, tabela de sumário).

Fale com o usuário no idioma em que ele escreve. O idioma do vídeo é uma escolha separada (Fase 1, passo 1).

Existem dois modos, escolhidos na primeira pergunta: narrado (voz de IA via OpenRouter, o padrão) e apenas visual (sem voz – tudo explicado na tela, veja "Modo apenas visual" abaixo). Onde este arquivo fala sobre narração, TTS ou áudio, isso se aplica apenas ao modo narrado.

Fluxo de trabalho

Siga as fases em ordem. A Fase 1 é uma parada obrigatória: nenhum dinheiro é gasto (TTS) até que o usuário confirme modo, idioma, modelo e duração.

Fase 0 – Ler os materiais

0. Veja o que este ambiente oferece, em silêncio: o conector MCP do OpenRouter (para a voz), uma saída de vídeo/animação integrada com exportação ou download MP4 (ex.: no Claude Design) e/ou execução de código com ffmpeg + Chromium (para scripts/render.py). A Fase 7 escolhe o caminho de saída a partir disso. Nunca faça o usuário instalar ou executar nada.
1. Extraia o PDF com scripts/extract_pdf.py:

   python3 scripts/extract_pdf.py <pdf> <workdir> [--images]
   

   Isso produz pages.json (texto, contagem de palavras, contagem de imagens por página), uma prévia PNG de cada página e – com --images – as imagens incorporadas. Se o pymupdf estiver faltando: pip install pymupdf --break-system-packages.
2. Observe as prévias das páginas (não apenas o texto): diagramas, tabelas e fluxogramas muitas vezes existem apenas como imagens. Páginas escaneadas (saída "SCANNED/sem texto"): execute novamente com --ocr (Tesseract, pacote de idioma dos materiais, ex.: --ocr-lang deu+eng). Se o Tesseract ou o pacote de idioma estiver faltando, olhe as imagens de prévia e leia o texto você mesmo. Sempre revise o texto OCR em relação à imagem antes de usar termos técnicos ou números no roteiro.
3. Determine a partir dos materiais: nome do curso, tópico desta unidade, professor/ministrante, idioma dos materiais, se há um slide de resumo e quais slides não têm conteúdo (título, agenda, referências, "Dúvidas?"). Qualquer coisa que não esteja nos materiais não é adivinhada – pergunte na Fase 1.
4. Perguntas abertas nos slides: pages.json lista, por página, questions – linhas que perguntam algo ao público ("O que você acha: …?", "Quais as vantagens de …?", "Discussão: …", "Pergunta para você", "Por que poderia …?"). Todas são respondidas no vídeo (veja "Perguntas abertas" na Fase 2). Leia os slides você também: perguntas dentro de gráficos ou balões de fala nem sempre são capturadas.
5. Aula ou exercício? pages.json tem exercise_guess (palavras como "Übung", "Aufgabe", "Übungsblatt", "Exercício", "Tarefa", "Atribuição", tarefas numeradas com a) b) c)). Confirme lendo: uma folha de exercícios pede que o aluno faça algo. Se for um exercício (ou uma aula com slides de exercícios), o vídeo resolve os exercícios – veja "Modo de exercício" abaixo. Verifique também se uma folha de solução ou slides de solução vieram junto.

A Fase 0 é executada silenciosamente: antes das primeiras perguntas (Fase 1, passo 1) você não pergunta nada mais ao usuário e não resume os materiais. A extração existe apenas para que a opção "mesmo idioma dos slides" possa nomear o idioma detectado.

Fase 1 – Perguntar ao usuário (obrigatório, antes de qualquer geração)

Passo 1 – Tipo de vídeo, narração e idioma (sempre a primeira mensagem)

A primeira mensagem contém exatamente essas três perguntas e nada mais (como três perguntas tocáveis se tal ferramenta estiver disponível), no idioma do usuário, o tipo de vídeo sempre primeiro. Exemplo para um usuário que fala português:

1. Que tipo de vídeo deve ser?

• Resumo curto – apenas o essencial: conceitos-chave, relações centrais, relevantes para a prova; ideal para revisão rápida
• Resumo abrangente – aborda todos os tópicos do material, com explicações e exemplos; substitui a aula

2. O vídeo deve ser narrado?

• Sim, com narrador (voz de IA) – explica como na aula; custa alguns centavos
• Não, apenas visual – explicações em texto e gráfico na tela, sem áudio, gratuito

3. Em qual idioma deve ser o vídeo?

• Mesmo dos slides (Português) ← idioma detectado entre parênteses
• Português
• Inglês
• Outro idioma (texto livre)

O tipo de vídeo vem primeiro porque decide o que entra no vídeo e quais durações fazem sentido:

• Resumo curto: apenas o núcleo – termos e definições-chave, relações centrais, tudo marcado como relevante para a prova, mais o slide de resumo. Exemplos, derivações e tópicos secundários são deixados de fora. Cada capítulo da aula pode ser tocado em uma ou duas frases, mas a profundidade vai apenas ao núcleo.
• Resumo abrangente: todos os tópicos do material são cobertos – cada página de conteúdo vira pelo menos uma cena (verificado na Fase 6 com scripts/coverage.py), na ordem da aula, com as explicações e exemplos que a aula dá. Nada é pulado, apenas condensado.
• Para um exercício: curto = para cada tarefa a abordagem em uma ou duas frases mais o resultado; abrangente = o caminho completo da solução passo a passo.

A narração vem em seguida porque muda tudo que vem depois: com "apenas visual" não há pergunta de modelo, nenhum custo, e o vídeo é construído de forma diferente.

Mantenha "mesmo idioma dos slides" mesmo que o idioma detectado seja português ou inglês – é o padrão. Para materiais com idiomas mistos, nomeie o dominante ("mesmo dos slides (principalmente Inglês)").

O idioma escolhido se aplica a tudo: narração, texto na tela, introdução, resumo, rótulos como "veja só", instruções de entrega TTS. Ele também determina quais modelos TTS se qualificam e como o orçamento de palavras e o custo são calculados – é por isso que vem primeiro.

Se o idioma do vídeo for diferente do idioma dos slides, aplique as regras de tradução em references/didactics-and-script.md (os termos técnicos da aula permanecem visíveis, porque a prova os usa). Para "outro idioma" no modo narrado: primeiro verifique brevemente se algum modelo TTS o suporta bem; se não, diga abertamente e ofereça alternativas (incluindo apenas visual).

Passo 2 – Duração, modelo, dados-chave, sumário, quiz (uma mensagem)

Apenas após as respostas do passo 1. No modo apenas visual, pule b) (modelo) e não cite custos; não há passo 4 (voz) então.

Se os materiais forem um exercício, diga em uma linha no topo desta mensagem ("Isso é uma folha de exercícios com 4 tarefas – resolvo todas passo a passo no vídeo.") – sem pergunta extra; sugestões de duração então contam tarefas, não páginas (≈ 45–90 s por tarefa dependendo do tamanho).

a) Duração do vídeo. Sugira durações que se encaixam no tipo de vídeo do passo 1, derivadas do número de páginas de conteúdo (n) – estimate.py lengths --content-pages n --type short|comprehensive:

Tipo de vídeo	Opções (regra de ouro)	Exemplo, 30 páginas
Resumo curto	muito curto n × 4 s · curto n × 6 s (padrão)	~2 / ~3 min
Resumo abrangente	compacto n × 10 s · padrão n × 14 s (padrão) · detalhado n × 18 s	~5 / ~7 / ~9 min

Arredonde para meios minutos. Para "abrangente", avise em uma frase se o usuário escolher uma duração abaixo de n × 8 s: todos os tópicos ainda serão cobertos, mas muito brevemente. O usuário decide; uma duração personalizada é sempre permitida.

b) Modelo TTS incluindo preço para exatamente este vídeo (modo narrado apenas). O procedimento e a fórmula de custo estão em references/tts-models.md – leia antes de perguntar. Versão curta:

• Obtenha os modelos TTS atuais ao vivo via OpenRouter MCP (list-models com output_modalities: "speech", ordenados por preço). Preços e modelos mudam – nunca responda de memória.
• Filtre para modelos que suportam o idioma do vídeo escolhido.
• Ofereça 3–4 modelos, o melhor barato primeiro (de preferência uma variante Google Gemini Flash TTS), cada um com o preço estimado para a duração escolhida – calcule com scripts/estimate.py.
• Se a duração ainda não foi decidida: dê preços para todas as três opções de duração.
• A escolha é vinculante. Quando o usuário escolher um modelo OpenRouter, aquele modelo exato (mesmo ID de modelo, via OpenRouter MCP) DEVE ser usado para cada arquivo de áudio deste vídeo – veja "Escolha vinculante do modelo" na Fase 4.

c) Dados-chave faltantes. Apenas se não encontrado na Fase 0: nome do professor, nome da disciplina. Ofereça "sem nome" como opção em vez de adivinhar.

d) Opcional: mostrar imagens/gráficos dos slides diretamente (padrão: sim, onde explicam algo).

e) Sumário no início do vídeo? Sim / Não. Uma frase de explicação: logo após a introdução, um breve índice mostra cada capítulo com seu intervalo de tempo ("0:18–1:30 Junção Interna") e números dos slides, para que os alunos vejam a estrutura e possam pular para o que precisam. Custa cerca de 10 segundos. O MP4 também tem marcações de capítulo, para que players possam navegar entre os capítulos de qualquer forma.

f) Perguntas de autoavaliação no final? Sim / Não. Uma frase de explicação: perguntas para autoavaliação com uma pausa curta para pensar, seguidas da resposta – ajuda a memória mais do que reassistir.

Passo 3 – A aparência (+ número de perguntas)

Uma mensagem com duas perguntas sobre a aparência – e, apenas se as perguntas de autoavaliação foram escolhidas no passo 2 f), uma terceira sobre o número delas (como perguntas tocáveis se tal ferramenta estiver disponível; os padrões são nomeados primeiro):

Claro ou escuro?

• Claro (Padrão) · Escuro

Qual estilo?

• Moderno (Padrão) – acentos coloridos, gradientes suaves, cartões com sombra, cartões de título de capítulo
• Sóbrio – calmo, muito branco/preto, apenas uma cor de acento
• Como os slides – cores dos slides da aula (ex.: azul institucional), para combinar com a aula
• Temático: … – uma proposta concreta derivada do conteúdo, ex.: "Visual de banco de dados: azul/turquesa com grade de tabela sutil", "Sustentabilidade: tons de verde com motivo de folha", "Finanças: azul escuro/dourado com linhas de gráfico"

Quantas perguntas de autoavaliação? (apenas se escolhido)

• 3 · 5 · 8 · número próprio – cada uma com duração e custo extras (veja abaixo)

Escreva a opção "temática" como uma sugestão concreta para esta aula, não como um rótulo genérico. Pule "Como os slides" se scripts/palette.py não encontrar cores distintivas (slides pretos/brancos simples). Como cada resposta é construída: references/visual-rules.md, "Aparência".

Número de perguntas: opções 3 / 5 / 8 / personalizado. Para cada opção, dê a duração extra e o custo extra (estimate.py quiz --questions N --prompt … --completion …; para o total incluindo sumário: estimate.py cost … --quiz N --toc), ex.: "5 perguntas · +1:45 min · +$0,02". As perguntas vêm por cima da duração escolhida da parte de explicação; informe o novo total uma vez. Se o material tiver menos pontos-chave significativos do que o número de perguntas solicitado, ofereça menos e diga isso brevemente.

Passo 4 – A voz (modo narrado apenas)

Após o modelo ser escolhido, faça três perguntas curtas em uma mensagem (três perguntas tocáveis se tal ferramenta estiver disponível); os padrões são pré-selecionados e nomeados primeiro:

Como deve ser a voz?

• Feminina (Padrão) · Masculina

Qual caráter?

• Motivadora & amigável (Padrão) · Calma & objetiva · Firme & clara · Descontraída & relaxada

Qual velocidade?

• Lenta · Normal · Rápida (Padrão) · Muito rápida

Padrão quando o usuário pula ou diz "tanto faz": uma boa voz feminina, rápida, motivadora e explicativa. Mapeie as respostas para uma voz concreta do modelo escolhido e para instruções de entrega/velocidade com references/tts-models.md ("Escolha da voz"); nomeie a voz que você escolheu em uma linha curta ("Voz: Laomedeia – feminina, motivadora, rápida"). O ritmo muda o orçamento de palavras: passe para estimate.py --pace. Após o teste de introdução (Fase 4), o usuário ainda pode dizer "outra voz" ou "mais devagar" – então refaça apenas a introdução.

Fase 2 – Roteiro

Leia references/didactics-and-script.md. Depois escreva o roteiro como script.json (esquema lá), cena por cena. Estrutura necessária:

1. Introdução (≈ 8–12 s): "Este vídeo é sobre … da disciplina … com o Prof. …" + uma visão geral do que vem a seguir em 3–5 pontos (organizador prévio). Sumário (apenas se escolhido, ≈ 10 s): uma cena diretamente após a introdução com <ol class="toc" data-toc>. O arquivo de cena preenche automaticamente cada capítulo com seu intervalo de tempo e slides a partir do tempo final – nunca digite os tempos manualmente, eles mudam a cada regeneração de áudio. A narração nomeia os capítulos em uma ou duas frases ("Primeiro …, depois …, e no final um resumo e uma autoavaliação") e não lê os tempos. Marque a cena data-dense com data-hold ≈ 3 s para que o sumário possa ser lido. Quando um sumário é escolhido, a agenda da própria introdução pode ser mais curta (uma frase) para que nada seja dito duas vezes.
2. Parte principal: capítulos na ordem da aula. Explicação

...

[truncado para tradução]