Rajesh-Royal/under-the-hood

Under the hood (Por debaixo dos panos)

Transforma um tópico (ou o código do usuário) em um vídeo explicativo narrado e animado. O visual é acolhedor e desenhado à mão:

• fundo "papel" creme com grade de pontos e arte em linha nanquim
• azul para requisições, laranja para respostas, verde para criptografado ou sucesso
• um contador de etapas no topo e legendas grandes na parte inferior
• pacotes que voam entre caixas, e movimentos de câmera entre "mundos"

O resultado de referência está em ${CLAUDE_SKILL_DIR}/assets/example-cookie/, que mostra o que acontece quando você digita "cookie" no Google. Abra seu scenes.js sempre que precisar de um padrão para algo complexo.

Tudo é orientado a código. Uma página canvas renderiza quadros deterministicamente, clipes de narração definem a duração de cada cena, e a música e os efeitos sonoros são sintetizados a partir da mesma linha do tempo. Uma alteração no script ressincroniza tudo, e um vídeo de 60 segundos é renderizado em cerca de 30 segundos.

Tópico solicitado: $ARGUMENTS

Onde as coisas ficam

• Scripts: ${CLAUDE_SKILL_DIR}/scripts/ (chame de SCRIPTS).
• Runtime: UTH_HOME (padrão ~/.local/share/under-the-hood) contém o módulo Node, o venv do TTS e as vozes salvas. doctor.sh exibe os caminhos exatos, incluindo PY (o Python do TTS).
• Projetos: ./explainers/<slug>/ no diretório de trabalho atual, a menos que o usuário especifique outro local. Se o diretório de trabalho for a pasta home, pergunte onde colocar, em vez de poluir ~.

Um diretório de projeto se parece com:

index.html  engine.js  scenes.js  script.json  timeline.js
narration/  (clipes de voz: <id>.wav, <id>_take2.wav, além de arquivos de pré-visualização)
audio/      (stems e mix.wav)
.shots/     (capturas de tela, uma nova pasta por execução)
<slug>.mp4

Fluxo de trabalho

0. Verifique a configuração (uma linha quando estiver pronto)

bash ${CLAUDE_SKILL_DIR}/scripts/doctor.sh          # adicione --no-tts se o vídeo não tiver narração

Se imprimir READY, anote PY e VOICES e prossiga. Se imprimir linhas MISSING, carregue a skill under-the-hood-setup e siga-a, depois execute o doctor novamente.

1. Briefing curto

Se $ARGUMENTS estiver vazio, pergunte pelo tópico. Depois, pergunte apenas o que você não pode decidir razoavelmente, em uma mensagem, com padrões sensatos:

• Ângulo, apenas quando o tópico for amplo. "Como a internet funciona" precisa de um foco, "o que acontece quando você faz git push" não precisa.

• Voz: sempre ofereça isso, porque os usuários não sabem que a própria voz é uma opção. Apresente assim:

  1. voz embutida (padrão, funciona imediatamente)
  2. uma voz salva, se VOICES listar alguma
  3. sua própria voz: grave cerca de 20 a 30 segundos no seu celular e envie o arquivo. Sua voz permanece na sua máquina.
  4. sem narração (apenas música e efeitos sonoros)

  Se escolherem a própria voz, leia ${CLAUDE_SKILL_DIR}/references/voice.md e forneça as dicas de gravação e o parágrafo de amostra antes de qualquer outra coisa. Eles podem gravar enquanto você escreve o storyboard.

• Duração: padrão de 30 a 60 segundos, 16:9.

Não transforme isso em um questionário. No máximo duas ou três perguntas curtas.

2. Entenda o tópico e acerte os fatos

Se o usuário forneceu código, leia-o e trace o fluxo real. Os espectadores técnicos apontarão erros. Portanto:

• Acertar a ordem dos eventos. Exemplo: em uma página já carregada, o DNS e o handshake TLS já ocorreram, então coloque-os no primeiro contato ou rotule como "primeira visita".
• Prefira o que os sistemas modernos realmente fazem. Exemplo: o Chrome fala com o Google via QUIC e TLS 1.3, não um handshake TCP de três vias de livro.
• Escreva "simplificado" em uma legenda secundária quando simplificar.
• Use valores ilustrativos (IPs de exemplo, domínios .example, pontuações inventadas) e evite precisão falsa, como contagens exatas de milissegundos.
• Não recrie logotipos ou UIs pixel a pixel de produtos reais. Representações em linha se encaixam melhor no estilo.

3. Storyboard e roteiro, depois obtenha aprovação antes de construir

Planeje de 4 a 8 etapas numeradas, aproximadamente 30 a 60 segundos, mais uma cena title no início e uma cena end no final. Para cada cena, escreva:

• Narração (script.json): {"id", "text", "gap"}. gap é a pausa após a fala, de 0,25 a 0,45 segundos.
• Legenda (cap): 8 palavras ou menos, legível quando sem som. Sublegenda (sub): uma linha curta.
• Batida visual: o que aparece e se move, e qual som está associado.

Leia ${CLAUDE_SKILL_DIR}/references/narration.md antes de escrever a narração. Narração no estilo de artigo soa como IA lendo um artigo. Escreva como uma pessoa explicaria a um amigo.

Mostre ao usuário o roteiro e o storyboard como uma tabela curta e aguarde aprovação. Mudar palavras agora é gratuito. Após a geração de voz, custa uma nova execução.

Sem travessões ou ponto e vírgula na narração ou texto na tela. O TTS os lê de forma estranha, e frases curtas soam mais naturais.

4. Estrutura inicial

bash SCRIPTS/new_project.sh ./explainers/<slug> "<Título da página>"

Isso copia engine.js, um scenes.js inicial (um pequeno exemplo funcional "hit send") e script.json. Ele se recusa a sobrescrever uma pasta não vazia. Substitua o conteúdo inicial pelo storyboard real.

5. Construa scenes.js

Leia ${CLAUDE_SKILL_DIR}/references/engine-api.md primeiro. Ele cobre o modelo de tempo, todos os helpers, as zonas de layout, os nomes de som e a configuração de inicialização. Ideias-chave:

• defineScenes([...]) com durações de design. Anime em tempo de design com prog(t, S.id + a, S.id + b). O mecanismo estica cada cena para caber no clipe de voz, então nunca ajuste manualmente para comprimentos de clipe.
• Mantenha o mundo dentro de y 150 a 800. O contador fica acima disso e as legendas abaixo.
• Coisas que devem persistir (um navegador, um servidor) aparecem em uma cena e permanecem desenhadas após ela.
• Para um segundo "local", como dentro de um data center, desenhe em x + 1920 e mova a câmera com camera(t). Comece a revelar seu conteúdo durante a movimentação para que a tela nunca fique vazia no meio do movimento.
• Cada evento visível recebe um som em sfx(add). Chaves recebem key, pacotes voadores recebem whoosh*, chegadas recebem thunk ou pop, sucesso recebe chime ou success. Isso é uma grande parte do motivo pelo qual o resultado parece finalizado.

6. Pré-visualização sem voz, verifique os quadros

node SCRIPTS/shots.js <projeto>            # meio de cada cena, salvo em uma nova pasta .shots/<time>/

Olhe para cada captura de tela. Reduza antes de ler (sips -Z 960 no macOS, ffmpeg -i in.png -vf scale=960:-1 out.png em outros sistemas). Verifique:

• texto que sobrepõe ou sai das bordas
• quadros vazios durante movimentos de câmera
• elementos desenhados sobre coisas que deveriam ficar atrás

Corrija e refaça as capturas. Se a página falhar ao iniciar, o script imprime os erros da página.

7. Voz

Voz embutida (sem --voice):

$PY SCRIPTS/narrate.py --script <projeto>/script.json --out <projeto>/narration --takes 2

Uma voz salva: adicione --voice <UTH_HOME>/voices/<nome>.wav.

Uma nova voz a partir de uma gravação: siga ${CLAUDE_SKILL_DIR}/references/voice.md. Ele cobre prep_voice.sh, uma linha de teste rápida e consentimento. Apenas clone a voz do próprio usuário ou uma voz que ele confirme ter consentimento para usar.

Depois, peça ao usuário para ouvir: <projeto>/narration/narration-preview_take1.wav (use open no macOS, xdg-open no Linux).

• A primeira execução baixa cerca de 1 GB de pesos de modelo. Depois disso, roda aproximadamente em tempo real no Apple Silicon ou GPU, mais lento em CPU.
• Você não pode ouvir áudio. Diga isso ao usuário e peça que ele julgue as tomadas ouvindo. Eles podem misturar tomadas linha por linha. Refazer uma única linha com --only <id>.
• Turbo suporta tags como [chuckle], [laugh], [sigh], [gasp] e [surprised]. Use no máximo uma ou duas por vídeo.

Sem narração: pule esta etapa e o build_timeline.py. As cenas mantêm suas durações de design, e o vídeo recebe apenas música e efeitos sonoros.

8. Linha do tempo, renderização, verificação

python3 SCRIPTS/build_timeline.py <projeto> [--pick dns=2,enter=2]
node SCRIPTS/render.js <projeto> [--music-db -12] [--sfx-db 1] [--silent] [--audio-only]

render.js constrói as faixas de voz, música e efeitos sonoros e as mixa, fazendo duck da música sob a voz e normalizando para -16 LUFS. Ele renderiza para <slug>.partial.mp4 e só renomeia para <slug>.mp4 depois que o ffprobe confirma a duração total.

Antes de dizer ao usuário que está pronto, verifique o arquivo real:

• ffprobe mostra a duração esperada, além de streams de vídeo e áudio
• ffmpeg -ss <hora final> -frames:v 1 mostra a cena correta
• a intensidade sonora está em torno de -16 LUFS

Em seguida, abra o MP4 e a prévia index.html. A prévia reproduz a mixagem em sincronia, com capítulos e busca.

Relate claramente o que foi verificado, o que você não pôde verificar (como o áudio soa) e quais partes estão simplificadas.

Regras de trabalho

• Sem exclusões globais. Não execute rm com curingas ou rm -rf em pastas de projeto. Novas saídas vão para pastas novas, e arquivos são sobrescritos por nome.
• Um comando interrompido pode ter sido executado parcialmente. Se o usuário interromper um comando de várias etapas, verifique o que mudou no disco antes de prosseguir e informe sobre quaisquer efeitos parciais. Um conjunto de clipes meio trocado pode deixar um vídeo parcial curto que parece finalizado.
• Não mude automaticamente com base em dicas de preferência. Se o usuário disser "eu gosto da take 2" enquanto ainda decide, confirme antes de renderizar novamente.
• Ofereça, não construa: uma versão vertical 9:16, corte para 30 segundos ou mais polimento. Mencione-os em uma linha cada.

Solução de problemas

• 'NoneType' object is not callable em PerthImplicitWatermarker: execute uv pip install --python $PY "setuptools<81". A biblioteca de marca d'água do Chatterbox precisa de pkg_resources.
• A primeira execução do TTS é lenta: isso é aquecimento e download do modelo. Execuções posteriores são mais rápidas.
• Música muito alta ou baixa: --music-db (padrão -12). Efeitos: --sfx-db (padrão 1). Use --audio-only para iterar rapidamente na mixagem.
• Chrome não encontrado: defina CHROME_PATH ou carregue a skill under-the-hood-setup.
• O áudio offline do Chrome não é bit idêntico de uma execução para outra, então as faixas diferem ligeiramente entre renderizações. O tempo é exato e os quadros são pixel idênticos.