jjietay/kaleidoscope

Vídeo Explicativo

Você cria um vídeo que ajuda o usuário a aprender um conceito. Você tem uma grande vantagem sobre uma ferramenta nova: você conhece esta conversa e este projeto. Use esse conhecimento.

O motor está em ~/.claude/skills/kaleidoscope/engine/. Neste arquivo, make significa:

node ~/.claude/skills/kaleidoscope/engine/make.mjs <comando> <diretório-do-projeto>

Etapa 0: pergunte primeiro (toda vez que a skill iniciar)

Se o usuário digitou /kaleidoscope ou pediu um vídeo em palavras, a primeira coisa que você faz é fazer as perguntas abaixo com AskUserQuestion, com opções clicáveis. Deixe de fora cada pergunta que a mensagem do usuário ou esta conversa já responder (por exemplo, "como um cinejornal" responde ao visual, e "com música lo-fi" responde à música). Coloque a opção recomendada primeiro e marque-a como "(Recomendado)". Faça todas as quatro perguntas em uma única chamada (a ferramenta aceita no máximo 4). Se o tópico em si não estiver claro e nenhuma pergunta for ignorada, pergunte sobre o tópico primeiro, em sua própria chamada.

Pergunta	Cabeçalho	Opções (primeira = padrão)
Qual visual o vídeo deve usar?	Visual	Argila 3D: um visual de argila suave, com o mascote silencioso fazendo o trabalho · 2D Clássico, misto: um estilo 2D diferente para cada parte · 2D Clássico, um estilo: o usuário nomeia (cinejornal, quadro branco, ...)
Para quem é o vídeo e quanto tempo?	Espectador	Revisão de exame, padrão: a notação da aula, números trabalhados, armadilhas de prova, 5 a 6 min · Revisão de exame, aprofundado: o mesmo, 8 a 9 min, cada passo da derivação · Iniciante, curto: intuição primeiro, menos símbolos, 2 a 4 min · (Outro: o usuário nomeia um espectador e uma duração, por exemplo "refrescamento para especialista, curto")
Quando devo verificar com você?	Ponto de verificação	Único disparo: volte com o vídeo finalizado · Após o storyboard: mostre o plano e aguarde aprovação · Após o primeiro visual: mostre os primeiros quadros e aguarde
Qual música?	Música	Calma (current): pad suave, sem batida · Lo-fi (lofi): batida leve, mais energia · Nenhuma

Coloque uma opção recomendada primeiro quando a conversa sugerir uma (um exame na próxima semana: Revisão de exame, aprofundado). Se a mensagem responder apenas metade da pergunta do Espectador (por exemplo, "para o meu exame"), mantenha a pergunta e ofereça apenas as opções que concordam com essa metade. Os espectadores são revisão de exame, iniciante e refrescamento para especialista (rápido e denso); as durações são curta (2 a 4 min), padrão (5 a 6 min) e aprofundada (8 a 9 min). Escreva as respostas em video.json na etapa 4: "_look" ("clay" ou "classic"), "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } e "_render": { "music": "current" | "lofi" | false }. Cada etapa posterior, e uma reconstrução, lê-os lá e não pergunta novamente. Se o usuário descartar as perguntas, use a primeira opção de cada.

Único disparo, a menos que o usuário tenha escolhido um ponto de verificação

Após a etapa 0, faça cada etapa abaixo sem parar e volte apenas com o vídeo finalizado e verificado. Não pergunte "devo continuar?", não mostre rascunhos, não espere entre as etapas. Cada verificação abaixo é sua para executar e agir. As únicas paradas são o ponto de verificação que o usuário escolheu: "Após o storyboard" para após a etapa 7 (mostre o storyboard e o veredito do agente de roteiro, então aguarde), e "Após o primeiro visual" para no primeiro make look da etapa 9 (mostre suas imagens, então aguarde).

O visual que o usuário deseja (leia antes da etapa 6)

Argila para coisas que agem, Manim para gráficos, e o mascote está em todos os vídeos. Leia styles/clay.md. O usuário escolheu o visual de argila em vez da mistura de estilos antiga para consistência entre os vídeos. Os estilos 2D são um visual clássico opcional; veja a seção abaixo.

• Não force um gráfico em argila (o usuário pediu). Quando uma imagem 2D do Manim ajuda o espectador a entender mais do que a argila (uma curva, uma distribuição, um contorno, uma projeção ou outra geometria em um plano), faça dessa parte uma parte Manim, no fundo escuro do Manim (styles/math-manim.md). Nunca construa um modelo de argila que copie uma curva matemática: o usuário mandou removê-los. Objetos que agem, e o trabalho físico do mascote, permanecem em argila. Um vídeo pode ir de uma parte em argila para uma parte Manim e voltar, com a mesma cor para a mesma coisa.

• Um visual, muitas partes. O vídeo é dividido em partes de cerca de 15 a 40 s (gancho, cada ideia, seu caso, encerramento). Cada parte tem seu próprio fundo simples, câmera e cenário. Uma ao lado da outra, duas partes nunca compartilham um fundo.

• O mascote faz o trabalho. Ele é silencioso, sem sincronia labial, e o narrador é uma voz sobreposta. Ele anda, puxa, empurra, carrega e desliga coisas com suas próprias mãos, então uma força no roteiro é algo que o espectador o vê fazer. O usuário pediu isso depois de um vídeo onde ele apenas ficou parado. Ele permanece inexpressivo por padrão, e make check AVISA quando ele fica em um só lugar.

• As coisas devem se conectar. Uma mola alcança sua parede, um pino toca seu mapa, uma mão toca o que segura. O usuário encontrou uma mola que errava sua parede depois que todas as verificações passaram. make bake mede cada junção em models.js (JOINS), então adicione novas junções lá e procure por contato nos stills.

• Apenas nossos próprios modelos. Use o kit em styles/library/clay. Nunca baixe um modelo. Se um vídeo precisar de um novo objeto, adicione-o ao kit no mesmo visual.

• Cada parte é uma única tomada contínua. Dentro de uma parte não há cortes e nem novos slides: objetos chegam, se movem e se juntam enquanto a voz fala, e a câmera se move lentamente. Uma parte termina no estado em que a próxima parte começa, ou com um wipe no fundo da próxima parte.

• A imagem explica; o texto apenas nomeia. O texto permanece plano e nítido, em HTML sobre o 3D. Por quadro: um kicker (caixa alta pequena, a parte e uma fonte), um título de no máximo 8 palavras, alguns rótulos de 1 a 4 palavras cada com linhas finas de líder, e no máximo uma linha de legenda na parte inferior. Nunca uma coluna de frases, nunca uma lista de marcadores, nunca uma legenda do que as cores significam. No máximo cerca de 15 palavras na tela.

• Fórmulas encenam a voz (o usuário pediu isso). Uma fórmula fixa não é melhor do que ler anotações. Construa cada uma com eqn(): termos chegam quando são ditos, movem-se quando a voz os move, explodem e se desfazem quando diz cancelar, e quicam apenas quando nomeia algo importante. make look dá uma falha para uma fórmula que fica parada, e para uma frase "cancela" sem nenhum cancelamento na tela. Veja styles/clay.md.

• Movimento físico. As coisas se movem como objetos: um braço alcança, uma bola cai e quica, um bloco cai e se acomoda, um pulso viaja. Nenhuma acumulação de caixas estáticas.

• O mesmo objeto mantém sua cor em todos os vídeos (o robô é sempre laranja, o mapa sempre amarelo).

Se um storyboard quebrar um destes, mude o storyboard antes de escrever código.

Regras rígidas

• Faça o pensamento aqui, na conversa principal. Você escreve o roteiro, o storyboard e as cenas você mesmo, porque o contexto está aqui. Nunca entregue esses passos a um subagente: um subagente começa sem contexto. O agente de roteiro na etapa 7 é a única exceção, e ele começa frio de propósito.
• Nunca apresse a explicação central. O usuário aprende com esses vídeos. Siga as regras de ritmo em reference/script.md e corrija cada AVISO de ritmo.
• Nunca invente um fato. Cada número, fórmula e afirmação vem de uma fonte que você verificou: o código do usuário, uma folha de dados, uma especificação, um artigo, a documentação. Liste-os em storyboard.md. Relate qualquer coisa que você não pôde verificar.
• "Seu caso" é opcional. Adicione-o apenas quando esta conversa ou projeto realmente contiver um exemplo correspondente (um bug que o usuário encontrou, uma correção, um número medido). Nunca invente um.
• Sem sobreposições. Nenhum visual pode cobrir outro: texto sobre texto, texto sobre um gráfico, ou um gráfico que esconde outro gráfico. Cada rótulo, fórmula, seta e objeto recebe seu próprio espaço. check AVISA sobre textos sobrepostos, e review escreve cada sobreposição medida em overlaps.md. Aglomeração é julgamento do usuário, então procure por ela nos quadros em tamanho real. O passe de ID ajuda: make look adiciona uma imagem das lacunas mais apertadas, e AVISA para texto mais próximo que 12 px de outra coisa, texto sobre um desenho, baixo contraste de texto e um modelo que outros escondem. Corrija cada sobreposição antes de make final.
• As legendas têm uma linha. Cada cue tem no máximo 42 caracteres e dois cues nunca aparecem ao mesmo tempo, então um player nunca mostra duas linhas. O motor faz isso; verify relata um cue que quebra a regra. Não altere SUB_MAX em make.mjs para fazer um cue caber.
• O loop fechado (o usuário pediu isso, e o motor o impõe). Após cada edição: make look, leia cada imagem que ele lista, corrija o que você vê, e olhe novamente. Só então construa. Nunca edite e construa às cegas, porque uma construção é longa e um look leva segundos. Cada imagem tem um DÍGITO DE VERIFICAÇÃO no canto superior direito, e as portas abrem apenas com os dígitos de todas as imagens, em ordem:
  1. Edite. Se você mudou script.md, execute make voice. Se o vídeo tiver partes Manim e você mudou manim_scenes.py ou a voz, execute make manim: make look desenha os quadros Manim, não os cria.
  2. make look <dir>: ele mede cada cena alterada em cada quadro e desenha seus quadros próximos e suas partes móveis. Leia todos eles. Então make look <dir> --ok <digits>. make build para sem isso.
  3. make build <dir>. Ele para em qualquer colisão.
  4. Leia cada strip em build/review/moving.md. Então make look <dir> --moving-ok <digits>.
  5. make final <dir>. Ele para se a fonte mudou após o look ou a construção, ou se uma colisão ou sobreposição estiver aberta. Execute cada etapa como seu próprio comando, pare na primeira falha e confirme que uma edição foi aplicada.
• Todo leitor verifica quadros próximos e partes móveis. Qualquer agente ou sessão que julgar um vídeo lê os quadros próximos de cada parte editada, e todos os quadros de cada coisa que se move: o mascote e objetos, durante todo o seu movimento. Uma amostra do vídeo não conta: uma mão atravessou uma mesa entre os quadros amostrados.
• Uma nova falha ganha uma proteção. Quando o usuário encontrar uma falha, primeiro adicione-a a reference/faults.md e a engine/test/selftest.mjs, e confirme que o teste falha nela. Então corrija o vídeo. Não apenas corrija o vídeo. Execute make selftest após cada mudança em uma verificação.

O que o usuário pediu (mantenha isso)

Cada um foi pedido ou escolhido de ouvido. O motor faz a maioria deles sozinho.

Tópico	O quê	Automático?
Voz	Voz embutida do Chatterbox, desacelerada para cerca de 160 palavras por minuto por engine/tts/slow-reference.wav; cada parágrafo lido de uma vez para que o tom continue	sim
Pausas	cada ponto final exatamente 0,6 s, cada vírgula no máximo 0,3 s, definido a partir da pontuação do roteiro	sim; voice AVISA se uma pausa não pôde ser colocada
Más tomadas	uma parte cujas palavras diferem do roteiro (verificação Whisper) é regravada com uma nova semente, até 3 vezes; a melhor tomada é mantida	sim; AVISA se ainda estiver errado
Pontos rápidos	uma cláusula mais de 1,3 vezes o ritmo usual do vídeo (palavras de símbolo contam em dobro) é regravada; o usuário achou "lambda v é v, escalado por lambda" muito rápido	sim; AVISA "rápido": dê a ela sua própria frase curta e um [pause]
Números negativos	leia "negativo", nunca "menos"	voice para com um ERRO
Palavras repetidas	"um um" recebe uma vírgula ("um, um"), ou a voz escorrega	sim
Escrita	parágrafos conectados; [pause] apenas onde uma ideia termina ou uma animação é reproduzida. Rejeitado: uma pausa após cada frase, frases entrecortadas, uma voz rápida, uma voz esticada (abafada), Kokoro	você, veja reference/script.md
Música	audível, constante, cerca de 13 dB abaixo da voz (musicVolume 0,37; o usuário aumentou 3 dB de 0,26), ducking suave; duas faixas aprovadas, current (padrão) e lofi. Rejeitado: bombeamento alto-baixo, música muito baixa para ouvir, 4 outras faixas	sim; você escolhe a faixa, veja SOUND.md
Efeitos sonoros	o kit em engine/sfx.mjs, aprovado de ouvido; o whoosh de entrada 4 dB abaixo dos outros acentos (o usuário achou um pouco alto). Ligado para novos vídeos (_render.sfx: true), desligado para os antigos	você adiciona s.sfx nos cues; o motor os mistura
Áudio	48 kHz estéreo	sim; verify verifica
Legendas	suaves, nunca queimadas; o mpv do usuário as mostra pequenas (sub-scale=0.7)	sim
Uma linha de legenda	uma linha por cue, no máximo 42 caracteres, sem dois cues ao mesmo tempo. O usuário viu duas linhas no vídeo 1 do conjunto ROS 2	sim; verify relata um cue que quebra a regra
Sem sobreposições	nenhum texto ou gráfico cobre outro	check AVISA para textos, overlaps.md e sua lista de verificação de quadros para o resto
Visual	um visual 3D de argila com o mascote silencioso, e nossos próprios modelos; partes Manim no fundo escuro para curvas e gráficos (o usuário pediu: não force um gráfico em argila). Rejeitado: modelos baixados, um vídeo escuro inteiro, colunas de texto, legendas de cores, slides de acúmulo	make check ERRO para uma cena que não é nem argila nem Manim, ou um vídeo sem mascote; o resto é você, veja "O visual que o usuário deseja"
Matemática	os cinco passos da fórmula (necessidade, imagem, fórmula, significado, teste). Manim para uma curva, um gráfico ou uma fórmula que muda passo a passo: manim() em 2D, ou manim({ threeD: true }) para uma imagem 3D, não canvas desenhado à mão	make check AVISA em uma fórmula sozinha; o resto é você, veja reference/script.md e styles/math-manim.md
Quiz	nenhum no storyboard	você
Assistir	mpv <dir>/out/<slug>.mp4	coloque no relatório

Configurações da máquina

Execute make config antes da etapa 1. Ele imprime as configurações desta máquina, que o instalador ou /setup-kaleidoscope escreveu.

A linha voice nomeia a voz: Chatterbox (natural, melhor em uma GPU NVIDIA ou Apple silicon) ou Kokoro (pequena e rápida em uma CPU, a cerca de 150 palavras por minuto). Um projeto pode escolher a sua própria em video.json: "_tts": {"engine": "kokoro"}. Sem uma GPU, o Chrome desenha os quadros com SwiftShader e o ffmpeg codifica com libx264.