facundoexposito/plano-para-video

Plano para vídeo

Transforma um plano escrito em um vídeo explicativo narrado (cerca de 60 a 90 s para uma postagem social, 2 a 2,5 min para um plano real com várias decisões): o gancho, o problema, a proposta, o mecanismo, depois um quadro por decisão em aberto (pergunta mais 2 a 4 opções) e um pedido de encerramento.

Esta skill não reimplementa o HyperFrames. Ela decide o briefing, a estrutura narrativa e a configuração, depois executa o workflow /faceless-explainer instalado passo a passo, adicionando correções nos pontos onde o pipeline padrão tende a quebrar. Leia /hyperframes e /faceless-explainer conforme eles instruem; este arquivo diz a você o que responder e o que corrigir.

Primeira execução em uma máquina: leia references/setup.md e execute seu preflight. Ele instala as skills do HyperFrames e uma voz local se estiverem faltando.

Configuração

Resolva estes uma vez no início e reutilize-os em cada comando. Pergunte ao usuário apenas se um valor não puder ser encontrado.

Nome	Como resolver	Padrão
VIDEOS_DIR	$PLAN_TO_VIDEO_DIR se definido	./videos no diretório de trabalho atual (convenção do faceless-explainer)
FE_DIR	a pasta que contém o faceless-explainer/SKILL.md instalado	veja references/setup.md para a busca
MEDIA_DIR	a pasta que contém o media-use/SKILL.md instalado	mesma busca
HYPERFRAMES_PYTHON	variável de ambiente se definida, senão o venv de references/setup.md	~/.hyperframes-venv/bin/python
VOICE	a solicitação do usuário, senão a voz lembrada, senão	Kokoro am_michael (offline)

1. Briefing (confirme brevemente, não interrogue)

Leia a fonte primeiro (o documento do plano, a nota de pesquisa, o chat). Depois proponha estes padrões em uma mensagem curta e pergunte apenas o que a fonte não pode responder. Um "sim" rápido é melhor que um questionário.

Campo	Padrão	Por que
angle	listicle (um dos valores da rota: conceito, como-fazer, lista, narrativa)	um plano é "por que importa, como funciona, N decisões"
storyboard arc	concept-explainer with listicle	texto livre em STORYBOARD.md, não uma enumeração de briefing
aspect	1920x1080	assistido em um laptop ou em uma chamada; cartões de opção precisam de largura
length	2 a 2,5 min para um plano real com várias decisões; cerca de 60 a 90 s para uma postagem social. Teto rígido de 180 s	o ponto ideal do faceless-explainer é de 30 a 90 s; um plano com muitas decisões é mais longo. Cerca de 10 s por decisão mais introdução e encerramento
language / voice	o idioma da fonte; Kokoro am_michael para inglês	local e gratuito. Vozes Kokoro que não sejam em inglês precisam de espeak-ng
flow / storyboard	automation / no (autônomo)	ofereça a revisão do storyboard quando o plano for de alto risco
look	a própria marca do projeto quando o vídeo for sobre um repositório, senão um preset adequado	o vídeo deve parecer com a coisa que explica
music	none	MusicGen local precisa de torch; música do HeyGen precisa de login
project	$VIDEOS_DIR/<kebab-topic>/	uma pasta por vídeo

Pergunte, no máximo: quem vai assistir (define o quão técnico o texto fica) e se uma opção recomendada deve ser marcada em cada decisão (a borda de destaque "lean").

Regra de opção recomendada: marque a opção que a fonte recomenda. Quando nenhuma opção única vence, não marque nada; quando a decisão é "suportar várias", marque cada opção que faz parte dessa resposta. Quando a fonte não diz, recomende os padrões próprios desta skill (os valores na tabela acima) em vez de inventar uma preferência.

BRIEF.md é escrito no Passo 0, após npx hyperframes init (init recusa uma pasta não vazia), no formato que /hyperframes references/brief-format.md descreve, com o que o usuário disse e o que você inferiu mantidos separados.

2. Estrutura narrativa

Arco padrão, adapte à fonte:

1. Gancho com um número real da fonte ("N de M itens são X"). Cada figura deve rastrear uma linha da fonte; nunca invente estatísticas, preços ou contagens. Se a fonte não tiver número, abra com a dor concreta.
2. O problema em 2 ou 3 causas nomeadas, com exemplos reais da fonte.
3. A tese ou proposta até o quadro 3 (valor antes da evidência).
4. O mecanismo em um quadro de diagrama.
5. Um cartão de sinalização ("Cinco decisões antes de construirmos") como uma pequena pausa.
6. Um quadro por pergunta ou etapa em aberto, todos no mesmo estágio de perguntas (references/question-stage.md). Cada quadro mostra a pergunta e suas 2 a 4 opções; as opções entram conforme a voz as nomeia.
7. Um pedido de encerramento que retoma o cartão de sinalização ("Responda estas cinco e o passo um sai esta semana").

Escreva a narração como frases curtas de referência (6 a 25 palavras por quadro) para que cada opção tenha uma palavra para revelar. Se uma decisão já estiver respondida na fonte, mostre a resposta escolhida no destaque em vez de perguntar.

3. Execute o workflow, com estas correções

Siga /faceless-explainer Passos 0 a 6 em ordem. Em cada passo aplique a correção correspondente de references/gotchas.md. As que prejudicam quando puladas:

• Passo 0: init dentro do pai de $VIDEOS_DIR para que o projeto caia em $VIDEOS_DIR/<tema>, depois escreva BRIEF.md. Deslogado do HeyGen está ok: a voz roda no Kokoro localmente.
• Passo 2 design: para um repositório, coloque suas cores e fontes em capture/extracted/tokens.json e coloque os arquivos .woff2 reais em assets/fonts/ antes de build-frame.mjs (ele então escreve o bloco @font-face sozinho). Obtenha fontes dos próprios arquivos do site da marca, um download do Google Fonts ou um pacote de fontes em node_modules. Se a marca for escura e o preset for claro, inverta os papéis em frame.md, substitua glifos do preset que a fonte incorporada pode não ter e troque um destaque do preset que pertence a outra marca pelo do usuário (references/gotchas.md, Passo 2).
• Passo 3.1 áudio: passe HYPERFRAMES_PYTHON em todo comando de áudio, a menos que o padrão python3 já importe kokoro_onnx.
• Temporizações: deixe o áudio terminar e execute audio.mjs sync-durations antes de escrever as janelas de Cena do Passo 4, então marque cada revelação a partir das temporizações reais das palavras em audio_meta.json. (faceless-explainer executa sync-durations no Passo 5; movê-lo para antes é intencional.)
• Espaço de respiro: sync-durations define cada quadro para sua duração exata de voz, então o último quadro e o cartão de sinalização terminam abruptamente. Imediatamente após sync, edite - duration: em STORYBOARD.md: quadro final +2 a 3 s, cartão de sinalização e outros quadros de respiro +1 s. Faça antes de construir pacotes para que os trabalhadores animem contra as janelas preenchidas.
• Palavras das legendas: as legendas vêm de uma transcrição do áudio, não de SCRIPT.md, então nomes de produtos são mal interpretados. Antes de construir as legendas, compare a lista de palavras em audio_meta.json (voices[].words[].text) contra SCRIPT.md e corrija palavras mal interpretadas no local, mantendo suas temporizações.
• Antes do despacho do Passo 5: dê a cada trabalhador os nomes exatos dos arquivos de fonte colocados no Passo 2. Os pacotes omitem o bloco ## Video direction do storyboard e as temporizações completas das palavras, então cole ambos no contexto de despacho de cada trabalhador. Dê aos quadros de estágio de perguntas a especificação compartilhada textualmente. Proíba emoji.
• Passo 5: um trabalhador por quadro, em paralelo quando seu agente suportar subagentes (um modelo mais rápido é ok para trabalhadores), cada um com _role.md, seu pacote e o contexto de despacho.
• Após trabalhadores: normalize caminhos de ativos, corrija avisos de lint que são bugs reais de busca, execute check, instantâneo, olhe para a folha de contato.

4. Portões de qualidade (todos antes da renderização)

• npx hyperframes lint com 0 erros. Avisos studio_missing_editable_id são cosméticos; gsap_repeated_fromto_without_baseline é um bug real, corrija-o (references/gotchas.md, Passo 6).
• npx hyperframes check passa.
• npx hyperframes snapshot --at <ponto médio de cada quadro> e realmente olhe para a folha de contato: texto escuro em fundo escuro, fontes faltando (fallback serifada), cartões cortados e tofu de emoji aparecem todos lá.
• Se o usuário tiver um estilo próprio (por exemplo "sem travessões"), verifique cada string: as linhas - voiceover:, as linhas de SCRIPT.md, o texto em compositions/frames/*.html, e os cabeçalhos também. Escreva cabeçalhos com dois pontos (## Frame 1: Hook, ## Line 1: Hook (Frame 1)); os parsers de storyboard e script aceitam, então nenhum travessão é necessário.

5. Revisão, renderização, entrega

O Passo 6 do faceless-explainer mantém uma pergunta mesmo no modo autônomo: abra npx hyperframes preview --background e pergunte "renderizar agora, ou o que muda?". Pule essa pergunta quando o usuário pediu uma renderização única. Então:

npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4 (--skill apenas marca telemetria de renderização anônima; high é um alias de delivery)

Abra o MP4 apenas se o usuário quiser (open no macOS, xdg-open no Linux, start no Windows). Relate: o caminho do MP4, sua duração real (ffprobe -v error -show_entries format=duration -of csv=p=0 renders/video.mp4), a lista de quadros com ids (compositions/frames/NN-*.html) para que quadros individuais possam ser revisados, o caminho da folha de contato e qualquer coisa pulada (sem música, uma palavra mal pronunciada, um fato deixado de fora porque a fonte não o tinha).

Arquivos de referência

• references/setup.md: instalação em máquina nova e preflight (skills HyperFrames, venv Kokoro, ffmpeg, Chrome).
• references/question-stage.md: a especificação de layout compartilhada para quadros de decisão e etapa. Cole-a no contexto de despacho de cada um desses trabalhadores.
• references/gotchas.md: correções de ambiente e pipeline, por passo do workflow, com comandos.