mohamed-stifi/explainer-short

Explainer Short (ideia → vídeo finalizado)

Você produz UM vídeo finalizado por solicitação seguindo as 7 etapas abaixo em ordem, uma vez. Cada etapa tem um comando, uma saída e uma condição de parada. Não invente etapas extras.

Caminhos: SKILL = a pasta que contém este arquivo. STUDIO = o workspace de vídeo (padrão: ./explainer-studio no projeto atual; reutilize-o se existir). SLUG = id em kebab-case do vídeo, ex. how-https-works.

Limites rígidos (mantém a execução curta e barata)

• Faça no máximo uma pergunta ao usuário, e apenas se não houver tópico algum. Caso contrário, decida você mesmo (duração, formato, marca) usando os padrões abaixo e indique suas escolhas na resposta final.
• check.sh → corrigir → check.sh no máximo 2 rodadas de correção. Depois renderize e liste qualquer problema restante na resposta.
• Regere a voz no máximo 2 vezes (apenas por causa de duração ou palavra mal pronunciada).
• Não edite src/kit/ (exceto para adicionar um ícone). Não instale outros pacotes ou ferramentas.
• Leia template/src/videos/example/ uma vez (é a implementação de referência). Não leia o código fonte do kit; references/kit-api.md o documenta.

"Short", "reel", "explainer short" = o FORMATO vertical, não o modo de duração. Use o modo de duração "short" apenas se o usuário pedir um vídeo rápido/muito curto/menos de um minuto ou der segundos.

Padrões: duração 95–120 s (300–370 palavras; "short" = 55–70 s, "full" = a duração de referência 160–175 s — veja references/script-guide.md), voz am_michael velocidade 1.18, marca = o nome/canal do usuário se conhecido, senão "YourBrand". As regras de estilo vêm da medição de 23 vídeos de referência; a evidência está em references/style-evidence/ (apenas humanos — você não precisa ler).

Etapa 1 — Configuração (uma vez por máquina, ~3 min na primeira vez, ~2 s depois)

bash SKILL/scripts/setup.sh STUDIO

Condição de parada: última linha READY: …. Se imprimir MISSING TOOLS, diga ao usuário exatamente o que instalar e pare. (Defina KOKORO_MODELS=<dir> primeiro se os arquivos do modelo de voz já existirem em algum lugar, para pular um download de 340 MB.)

Etapa 2 — Planejamento (sem código ainda)

Leia references/script-guide.md. Em seguida, escreva STUDIO/src/videos/SLUG/plan.md (≤ 25 linhas, após a Etapa 3 criar a pasta):

1. Título em um dos formatos (Como X funciona · X vs Y · Entrevista: … · Design de sistema: como faz X).
2. Exemplo prático: uma pessoa nomeada + um produto/entrada/valor concreto usado do início ao fim.
3. Batidas (seções) com ids, 6–9 delas, cada uma = uma ideia.
4. Estágios: leia references/visual-guide.md, depois escreva uma linha por seção: seção → adicionado / movido / foco (spotlight ids) / sai (veja "Estágios de planejamento" lá). Escolha 3–4 acentos e vincule cada um a uma coisa.

Etapa 3 — Roteiro

bash SKILL/scripts/new_video.sh STUDIO SLUG

Escreva STUDIO/src/videos/SLUG/script.json (formato: veja o script.json do exemplo). Regras que quebram coisas:

• sections[].id único, simples (hook, scenario, mechanism, …). A última seção é o CTA.
• Escreva números/símbolos como você quer que eles sejam mostrados e mapeie para como são falados em pronounce ("429": "four twenty nine", "API": "A P I", "SQL": "sequel", "k8s": "kubernetes").
• Frases ≤ 18 palavras. Apenas . ! ? terminam frases (cada frase é sintetizada separadamente). Faça uma auto-verificação contra a lista de regras no final de script-guide.md antes de prosseguir.

Etapa 4 — Voz

bash SKILL/scripts/voice.sh STUDIO SLUG

Imprime o início/fim de cada seção e Done: <sec>s, <words> palavras, <wpm> ppm. Condição de parada: duração dentro da meta ±15 %. Muito longo → corte frases (não a velocidade) e execute novamente.

Etapa 5 — Visuais

Leia references/kit-api.md e o exemplo (STUDIO/src/videos/example/Video.tsx + stages/*.tsx). Escreva STUDIO/src/videos/SLUG/Video.tsx + um arquivo por estágio em stages/. Inegociável:

• O at de cada elemento vem de cue(seção, palavra) ou sec(seção).from — nunca segundos fixos.
• Um canvas contínuo: as coisas persistem, se movem, escurecem e são reutilizadas. Sem limpezas de tela cheia, exceto entre estágios.
• Algo muda visivelmente a cada ~3 s de narração (novo elemento, destaque, mudança de estado, movimento).
• Foco = plano de Spotlight no <Canvas focus> (escurece o resto) — o principal recurso do estilo.
• Sem legendas. Legendas (Takeaway) ≤ 7 palavras, 2–6 por vídeo.
• Mantenha o conteúdo na zona segura (x 60–1020, y 280–1480; título ≈150; legenda logo abaixo do diagrama).
• Preencha a largura: painéis principais com 960 de largura (ou 2 × 465). Nada menor que 26 px.

Etapa 6 — Verificação (máximo 2 rodadas de correção)

check.sh e render.sh iniciam um servidor local + Chrome headless. Em um agente com sandbox, execute ambos os comandos fora do sandbox. Se seu ambiente não puder fazer isso de forma alguma (No available ports found, Chrome não inicia, chamadas sem sandbox recusadas): pare após a Etapa 5 e diga ao usuário para executar check.sh e depois render.sh ele mesmo (dê ambos os comandos completos). Não tente soluções alternativas.

bash SKILL/scripts/check.sh STUDIO SLUG          # 3º argumento opcional: "12.5,30,41" = segundos extras para inspecionar

Ele verifica cada cue() em relação ao timing da voz (instantâneo), verifica tipos, renderiza ~3 quadros por seção + cartão final e escreve out/SLUG/check/sheet.jpg (+ NN.jpg quadros individuais). Olhe a imagem da folha (e 2–3 quadros individuais em tamanho real). Corrija apenas o que falhar:

Verificação	Falha quando
sobreposição	textos/caixas colidem ou são cortados pela borda da tela
escala	o diagrama usa < 80 % da largura ou deixa y 900–1400 vazio em uma seção movimentada; texto que você precisa apertar os olhos para ver em um quadro de 540 px de largura
legibilidade	qualquer rótulo menor que ~28 px, ou texto sobre uma área movimentada
sincronia	um elemento aparece antes de sua palavra, ou um quadro mostra um canvas vazio/desatualizado enquanto a narração fala sobre algo
continuidade	um estágio parece não relacionado ao anterior (tudo substituído) quando a história continua
foco	a coisa que está sendo falada não está destacada (Foco / âmbar / escurecer outros)
densidade	um quadro com > 9 elementos visíveis, ou > 2 linhas de texto de legenda

Erros de tipo / cue not found imprimem a correção (a lista de palavras válidas). Corrija e execute novamente.

Etapa 7 — Renderizar + entregar

bash SKILL/scripts/render.sh STUDIO SLUG

(Se o Chrome headless for bloqueado por um sandbox, execute este comando novamente fora do sandbox.) Em seguida, escreva STUDIO/out/SLUG/upload.md: título (= o título do vídeo, ≤ 60 caracteres, 1 emoji no final permitido), descrição de 2 frases, 5 hashtags e uma lista "Fatos para verificar" (cada número/afirmação que você afirmou de memória).

Resposta final (curta): o caminho do MP4, duração, os caminhos do SRT/capa/upload.md, as escolhas que você fez (formato, duração, exemplo prático) e qualquer problema conhecido restante. Em seguida, pare.

Solução de problemas

Sintoma	Correção
cue not found: "x" #1 in section "y". Words: …	use uma palavra da lista impressa, ou a seção correta
uma palavra é mal pronunciada	adicione-a a pronounce e execute novamente a etapa 4
Cannot find module './timing.json'	etapa 4 não executada para este SLUG
composição SLUG não encontrada	execute voice.sh (ela registra o vídeo)
Chrome / SIGABRT / ENOTFOUND remotion.media / No available ports found	sandbox bloqueia o navegador/porta: execute o comando sem sandbox (veja Etapa 6)
failed to canonicalize path …/voice/.venv/bin/python3 ou outros erros de uv/venv	delete STUDIO/voice/.venv e execute setup.sh novamente
um quadro mostra texto transbordando de um painel	dê ao <El> um h maior, menos linhas ou fonte menor (≥ 26 px)
vídeo muito longo/curto	edite o roteiro (~3.1 palavras por segundo na velocidade 1.18), execute novamente a etapa 4