explicador

O que explicador faz?

Um arquivo de especificação lista as cenas; os scripts capturam o material, narram, montam uma subcomposição HyperFrames por cena e verificam tudo antes de enviar.

1. entender     leia o código / docs / app sobre o qual há dúvida
2. capturar     scripts/capture.py      capturas de tela, caixas de elementos, gravações, ocultação
3. especificar  você escreve explainer.json (cenas + narração + afirmações com fontes)
4. verificar fatos scripts/verify.py facts (portão: nada é narrado até passar)
5. construir    scripts/build_explainer.py (voz, legendas, cenas; sem personagem por padrão)
6. verificar    scripts/verify.py all   (assets, build, render, áudio) - loop até limpo
7. renderizar   scripts/render.py

Caminhos são relativos à raiz deste pacote: a pasta que contém .claude-plugin/, dois níveis acima deste arquivo (resolva symlinks primeiro). Requer as skills públicas do HyperFrames (hyperframes, hyperframes-cli; hyperframes-registry e media-use para extras). Leia hyperframes uma vez antes de editar composições geradas manualmente.

0. Pré-voo (sempre primeiro)

Execute python3 scripts/setup.py doctor (adicione --json para analisar). Ele lista cada dependência, para que serve e o comando exato de instalação para esta máquina; sai com código 1 quando um item obrigatório está faltando.

• Obrigatório faltando (ffmpeg, Node.js 18+, as skills HyperFrames e a chave ElevenLabs ou say quando essa voz está configurada): informe ao usuário em uma linha para que cada um serve e proponha o comando impresso. Execute apenas após o usuário dizer sim. Nunca digite ou peça uma chave de API: peça ao usuário para exportar ELEVENLABS_API_KEY no shell dele.
• Opcional faltando: ofereça uma vez e diga o que cada um desbloqueia. Playwright fornece capturas web com caixas de zoom de elementos e capturas de página inteira, tesseract (OCR) fornece a verificação de segredos em capturas de tela, e ASR (mlx-whisper / openai-whisper) fornece a verificação de áudio e marcações de tempo exatas das palavras. Pule-os se o usuário recusar; as verificações correspondentes se tornam etapas manuais de review.
• Skills HyperFrames (hyperframes, hyperframes-cli, hyperframes-registry, media-use): se faltarem, recomende npx hyperframes skills. Leia hyperframes (e hyperframes-cli para problemas de renderização) antes de construir ou editar qualquer composição.

Configuração (primeira execução ou quando o usuário quiser mudar algo)

python3 scripts/setup.py show imprime a configuração ativa. Se não houver nenhuma, entreviste o usuário (uma pergunta curta de cada vez, ofereça o padrão) e escreva-a:

Pergunta	Flag	Opções
Quais partes?	--features	explainer sozinho (nenhum arquivo de personagem necessário), ou character,explainer para permitir um apresentador
Idioma da narração	--language	Código ISO (en, es, ...): escolhe uma voz say clara e informa o ASR o que esperar
Voz da narração	--narration-voice	voice (o provedor configurado), say (grátis, macOS), none (apenas legendas)
Provedor de voz	--voice	elevenlabs (a ELEVENLABS_API_KEY do ambiente + --voice-id), say, none
Limites de crédito	--max-chars, --max-seconds, --daily-credit-cap	os números do usuário
Renderização	--render	local, cloud, preview
Tamanho	--size	1080x1920 (padrão), 1920x1080, 1080x1080

python3 scripts/setup.py init --features explainer --voice say --render local --yes

init executa o doctor primeiro e oferece as mesmas instalações. Se uma configuração existir, pergunta antes de sobrescrever (passe --force ao executar de forma não interativa). setup.py voices --lang <code> lista vozes do macOS para um idioma e as vozes ElevenLabs do usuário; --say-voice "<nome>" escolhe uma. Nunca peça, imprima ou escreva chaves de API.

1. Entenda, depois escreva o script

• Obtenha os fatos da fonte primeiro: leia o código, PR, doc ou aplicativo. Um explicador errado é pior do que nenhum. Mostre a forma da coisa antes dos detalhes, percorra um caso real (nomes reais, valores reais) e mantenha cada cena em uma única ideia.
• Forma (≤ styles.explainer.max_seconds): 3-5 cenas de cerca de 6-12 s cada e um título de encerramento. TTS lê cerca de 2,4 palavras por segundo: mantenha a narração de uma cena com menos de ~25 palavras.

Escolha um estilo para este vídeo

O pacote fornece apenas padrões neutros. Escolha um estilo por vídeo com base no tópico, no público e na marca ou preferências do usuário, e pergunte quando isso importa (uma marca, um canal público, uma série). Não repita a aparência do vídeo anterior por hábito. Coloque-o no bloco style da especificação:

Chave	Valores
palette	background, panel, ink, muted, accent, highlight (cores CSS; mantenha o contraste do texto ≥ 4.5:1)
typography	font, mono (fontes incluídas no HyperFrames), title_scale (0.6-1.6)
layout	align (left, center), radius (0-60), background_style (solid, gradient)
motion	motion (calm, normal, lively): durações e easing de cada movimento
captions	caption_style (box, outline, plain, none), caption_position (bottom, top)

Um kit brand na configuração (mesmas chaves) substitui sua escolha chave por chave. O conjunto do apresentador segue o fundo do vídeo, a menos que seu bloco tenha seu próprio style (veja talking-clip).

2. Capture o material

python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit"   # precisa de Playwright
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12          # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48   # ou --blur
python3 scripts/capture.py list

• url usa Playwright quando instalado (necessário para --box e --full-page), senão Chrome headless. Sem Playwright, forneça caixas de foco como retângulos em pixels [x, y, w, h] lidos do PNG (o dobro dos pixels CSS na escala padrão). Se o Playwright estiver em um virtualenv, execute os scripts com esse interpretador (./venv/bin/python scripts/capture.py ...). --box registra a caixa de um elemento em pixels de imagem para que uma cena possa ampliar diretamente para ele. O padrão --scale 2 mantém o texto nítido quando ampliado.
• Capture a menor região que conta a história; uma área de trabalho inteira reduzida a um quadro de telefone fica ilegível. Use caixas de foco para ampliar.
• Um site inteiro como projeto em vez de capturas únicas: npx hyperframes capture <url> (hyperframes-cli).

3. Escreva a especificação

examples/explainer/explainer.json é um exemplo completo e funcional. Coloque a especificação na raiz do material: arquivos de código e capturas referenciados devem estar dentro da pasta da especificação. Tipos de cena:

tipo	necessita	o que mostra
screen	capture, opcional focus: [{"box": "#sel" ou [x,y,w,h], "label": "...", "at": s}]	a captura de tela, depois um movimento de câmera para cada caixa com um destaque e um rótulo
recording	capture (um vídeo), opcional focus	a gravação de tela, sem áudio, mesma câmera e rótulos
code	file, lines: "a-b" (≤ 24, linhas com ≤ ~49 caracteres na vertical), highlight: [{"lines": [a, b], "at": s}]	o código em um cartão, linhas aparecendo, faixas nas linhas principais
diagram	nodes: [{"id","label","sub"?,"highlight"?}], edges: [[a, b]], opcional flow: [ids]	caixas e setas se construindo, um token viajando ao longo de flow
title	text, opcional sub, dur	um cartão de encerramento ou seção

Movimento, em qualquer cena (opcional; cores e temporização vêm do estilo, então varie-os por vídeo como o resto da aparência):

Chave	O que
callouts: [{"type": "circle" ou "arrow", "box": [x,y,w,h] ou "#sel", "at": s, "note": "..."}]	loop ou seta desenhada à mão que aparece; pixels de imagem em cenas de tela/gravação, pixels do quadro em outros lugares
kinetic: [{"text", "at", "dur", "y"?, "from"?}]	palavras aparecendo com impacto para ênfase; use com moderação (uma ou duas por vídeo)
counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?}	uma contagem que termina exatamente no valor
nível superior transition: "wipe" ou "fade"	uma transição em cada corte (padrão none)

Eles seguem os itens do registry count-up, caption-kinetic-slam, hw-callout-circle e hw-arrow (veja /hyperframes-registry). style.hand_font: "Caveat" baixa essa fonte de caligrafia com npx hyperframes add. Não faça todos os vídeos usarem todos os recursos; escolha o que a história precisa.

Toda cena com narration deve conter claims: cada declaração técnica que faz, com uma source (path:linhas relativo à especificação, capture:<nome>, https://..., doc:<nome>) e status: "supported" depois que você a verificou com essa fonte. "claims": [] significa que a narração não faz nenhuma afirmação técnica. Afirmações não suportadas são corrigidas ou cortadas, nunca narradas.

Nenhum personagem por padrão. Um explicador é narração, legendas e visuais. Adicione o personagem como apresentador apenas quando o usuário pedir, ou quando você julgar que agrega valor (uma série com um apresentador, um onboarding amigável) e você diz isso ao usuário com o motivo. Em seguida, adicione um bloco presenter (intro / outro, cada um {"text", "plan"?, "mood"?, "style"?, "claims"}; planos seguem o formato talking-clip) e construa com --presenter. Também precisa de features.character. As cenas do apresentador recebem legendas também (a menos que a especificação defina "captions": false). examples/explainer/explainer-with-presenter.json é o exemplo.

4-5. Portão de fatos, depois construir

python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]

--estimate imprime duração e créditos ElevenLabs; informe o usuário antes de gastar, depois construa com --confirm. O builder também executa o portão de fatos e para se falhar. As legendas mostram as palavras do próprio script (caixa, pontuação, numerais) temporizadas a partir do alinhamento do ElevenLabs, ASR ou uma estimativa.

6. Verificar (loop obrigatório)

python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4

Estágio	Passa quando	Se falhar
facts	toda afirmação narrada tem uma fonte existente e status supported	verifique a fonte; corrija ou corte a afirmação
assets	capturas e código são legíveis no tamanho de saída; OCR (tesseract) / varredura de texto não encontra e-mails, chaves, tokens ou números de cartão	adicione caixas de foco ou recapture uma área menor; capture.py redact; substitua segredos no código por placeholders
build	npx hyperframes check --json não tem erros ou avisos (exceto verify.ignore_rules)	corrija a especificação ou a composição gerada
render	você olhou para a folha de contato (início, cada mudança de cena, meio da cena, fim): sem estouro, sobreposição, corte ou texto ilegível; visuais correspondem à narração	corrija, reconstrua, re-renderize
audio	ASR do áudio renderizado corresponde ao script (verify.min_asr_similarity) e a duração está dentro do limite	regenerar a voz ou encurtar

Como conduzir o loop:

1. Execute verify.py all. Cada execução é uma iteração (contada em <projeto>/.verify/state.json).
2. render sempre retorna como review primeiro: abra as folhas de contato que lista, verifique cada quadro, então registre o que viu: python3 scripts/verify.py mark render pass --project out/explainer --note "<o que você verificou>" (ou fail, então corrija). A marca está vinculada a esses arquivos exatos; qualquer reconstrução a invalida.
3. Sem OCR ou ASR instalados, assets / audio também se tornam review: verifique com os olhos ou ouvidos e informe no relatório.
4. Corrija o que falhou, reconstrua ou re-renderize e execute verify.py all novamente. Código de saída 0 = enviar.
5. Quando a contagem atingir verify.max_iterations (padrão 3), sai com código 2: pare e informe ao usuário o que ainda falha. Não envie silenciosamente. Exclua .verify/state.json para iniciar uma contagem nova após uma grande mudança.

VERIFY.md mostra números: imagens OCR escaneadas e acertos, similaridade ASR com palavras ouvidas e esperadas, duração em relação ao limite. Cite-os ao relatar. As cenas são alongadas automaticamente para que a última legenda permaneça legível; se um aviso line_unread persistir, dê a essa cena mais min_dur.

Mantenha o HOME normal do usuário ao executar os scripts: um HOME temporário faz com que npx, Playwright e whisper baixem tudo novamente e quebra a autenticação gh/npx.

Incompatibilidades de áudio em numerais, siglas ou palavras estrangeiras: defina language na configuração e escreva essas palavras na narração da maneira como devem soar ("quinze", "A P I"). VERIFY.md no projeto é o relatório de checklist; inclua seu resumo ao entregar o vídeo.

7. Renderizar

python3 scripts/render.py out/explainer --out out/explainer.mp4 usa render.backend (local, cloud ou preview); render.max_mb re-codifica para caber em um limite de upload. Nunca faça commit de arquivos mp4 ou wav.