anniebellb/aula-de-dados-narrada

Aula de dados narrada

Constrói uma aula como o exemplo de referência ("com quem passamos o dia, por idade"): um vídeo narrado que se desenrola em um gráfico ao vivo, e uma aba Explorar onde os alunos podem interagir com os dados. Uma aula = uma pasta com index.html, lesson.json, data.json, video.json (storyboard), áudio da narração e, opcionalmente, uma faixa musical.

Leia primeiro: references/design-rules.md (regras de estilo, movimento e ênfase aprovadas; siga-as exatamente) e references/user-guidance.md (como trabalhar com o usuário).

Os caminhos abaixo são relativos à pasta desta skill (${CLAUDE_SKILL_DIR}).

Com quem você está trabalhando

Presuma que o usuário não é técnico. Fale de forma clara, um passo de cada vez, e diga exatamente o que clicar quando algo exigir ação dele (baixar um arquivo, fazer login no ElevenLabs, aprovar um roteiro). Nunca peça para editar código ou JSON. Use os guias em references/user-guidance.md.

O fluxo de trabalho (com checkpoints e auto-verificações)

Execute a auto-verificação ao final de cada etapa. Não prossiga se houver uma FALHA.

1. Obter os dados

• Aceite um link, um arquivo ou um PDF. Se um link for bloqueado (sites frequentemente bloqueiam downloads automatizados), oriente o usuário a baixá-lo no navegador e compartilhar o arquivo.
• Perfil deles: python3 scripts/profile_data.py <arquivo-ou-url>.

2. Os dados se encaixam? (avise o usuário, sempre)

Leia os vereditos do profile e references/chart-chooser.md, depois informe ao usuário em linguagem clara:

• Encaixa: "Funciona como ___ porque ___." Nomeie a pergunta de aprendizado que ele responde.
• Encaixa parcialmente: o que funciona, o que está faltando e a compensação.
• Não encaixa: diga claramente, explique por que e descreva quais dados funcionariam. Não force.

✋ Ponto de verificação 1: tipo de gráfico e ângulo da história

Proponha o tipo de gráfico, a pergunta principal de aprendizado e 4–6 pontos da história (as coisas que o narrador destacará), cada um vinculado a um número que você calculará. Aguarde a aprovação do usuário.

3. Modelar os dados

• Inicie a pasta da aula: python3 scripts/new_lesson.py --chart <tipo> --out <pasta>.
• Escreva um script pequeno e reexecutável (na pasta da aula) que transforme a fonte em data.json no formato do gráfico (references/data-formats.md) e escreva facts.json: cada número que o narrador dirá, calculado a partir dos dados fonte, com como será falado.
• Auto-verificação: python3 scripts/check_lesson.py <pasta>; também verifique 2–3 valores manualmente contra a fonte (abra o arquivo bruto e encontre-os). Relate o que você verificou.

4. Escrever a história

• Escreva video.json (cenas, beats, dicas) seguindo references/storyboard.md e o arco da história em design-rules §1 (gancho introdutório → como ler o gráfico → pontos da história → resumo → reflexão → "sua vez").
• Escreva o roteiro da narração no estilo ElevenLabs (references/narration.md) em narration/script.txt. Cada afirmação deve corresponder a facts.json; evite exageros (design-rules §8).
• Preencha lesson.json: título, chamada, rótulo principal, descrições dos grupos, notas, fontes.

✋ Ponto de verificação 2: aprovar o roteiro

Mostre o roteiro como texto simples. Ofereça opções quando o usuário solicitar; não aplique alterações que ele não aprovou.

5. Visualização (antes de qualquer gravação)

• Pré-visualização silenciosa: python3 scripts/estimate_timing.py <pasta>/video.json --out <pasta>/narration/narration.words.json e depois python3 scripts/time_storyboard.py <pasta>/video.json <pasta>/narration/narration.words.json.
• Sirva e abra: python3 scripts/devserver.py 8123 (a partir da pasta acima da aula), depois http://localhost:8123/<aula>/.
• Auto-verificação (navegador): siga references/self-checks.md: capturas de tela em cada batida, nada sobreposto, nenhum erro no console, cada item nomeado destacado em sua palavra.

6. Narração e música (precisa da conta ElevenLabs do usuário)

• Oriente o usuário a fazer login (user-guidance.md → ElevenLabs). Configurações: voz Quentin – Narrador e Educador, Eleven v4, Estabilidade ≈ 80%, Inglês; o roteiro inteiro em uma única tomada. Salve como narration/narration.mp3.
• Sem ElevenLabs? Ofereça o placeholder gratuito: python3 scripts/placeholder_voice.py <pasta> (Mac).
• Temporize as palavras: python3 scripts/align_narration.py <pasta>/narration/narration.mp3 --out <pasta>/narration/narration.words.json, depois time_storyboard.py novamente. Busque ≥ 99% das palavras correspondentes.
• Música (opcional, ElevenLabs Music, instrumental, calma, ~2 min): prepare com prep_music.py; se o vídeo for maior que a faixa, estenda-a com find_loop.py + extend_music.py (nunca deixe que termine ou entre em loop sob o narrador).
• Auto-verificação: check_lesson.py (durações de áudio, fatos) + uma reprodução completa no navegador.

✋ Ponto de verificação 3: revisão conjunta

Oriente o usuário pela aula finalizada: o que observar, como testar a aba Explorar. Faça as alterações solicitadas, reexecutando as auto-verificações após cada uma.

7. Publicar (opcional)

Oriente-os sobre GitHub Pages ou qualquer host estático (user-guidance.md → Publicação). A pasta da aula é autocontida.

Regras de auto-verificação (sempre)

• Execute scripts/check_lesson.py após as etapas 3, 4, 5, 6 e após cada revisão.
• Verifique no navegador após qualquer alteração visual: tire capturas de tela nos momentos narrados e confira-as com o storyboard. Diga o que você verificou.
• Recalcule cada número narrado a partir dos dados fonte; nunca digite um número de memória.
• Se algo falhar, corrija e verifique novamente antes de informar ao usuário que está concluído.

Arquivos de referência

Arquivo	Use para
references/design-rules.md	Estilo, movimento, ênfase, narração, sincronia, música, honestidade dos dados
references/chart-chooser.md	Qual gráfico para qual pergunta; critérios de adequação
references/data-formats.md	Os quatro formatos de data.json
references/storyboard.md	video.json: cenas, beats, dicas por tipo de gráfico, facts.json
references/narration.md	Estilo do roteiro, configurações ElevenLabs, temporização, música
references/self-checks.md	O que verificar em cada etapa
references/user-guidance.md	Guias em linguagem clara para o usuário
references/chart-interface.md	Adicionar um novo tipo de gráfico