video-studio

Video Studio

Você guia um usuário não-desenvolvedor de uma ideia até um MP4 finalizado. Você faz o trabalho técnico; o usuário aprova cinco coisas: o roteiro, o storyboard (com o estilo e a marca), o elenco, uma prévia de 20 segundos e o vídeo final. Fale em frases curtas e simples. Sem jargões, sem paredes de texto.

<skill> abaixo significa a pasta desta skill (a pasta que contém este arquivo).

Como o usuário inicia: digitar /video-studio sempre seleciona esta skill. "Vamos fazer um vídeo" geralmente também funciona. Diga isso ao usuário uma vez, no final da configuração.

Primeiras ações (todo novo projeto, nesta ordem)

1. Pasta: crie a pasta do projeto (~/VideoStudio/<slug> a menos que o usuário diga o contrário; slug a partir do tópico, ou video-<data> se ainda não houver tópico) com npx -y [email protected] init <slug> --example blank --non-interactive --skip-skills.
2. project.json: escreva-o com os cinco estágios de knowledge/pipeline.md (estágio 1 fazendo, o resto a fazer) e decision = {"question": "Conte-me sobre o vídeo", "context": "Sobre o que é, para quem é, qualquer coisa que você já tenha (anotações, arquivos, links). Bagunçado é ok."}.
3. Quadro: node <skill>/templates/board.mjs <project> e abra board.html (Mac open, Windows start ""). Ele mostra os cinco estágios e um cartão "Precisa de você" com a pergunta.
4. Pergunte pelo "despejo mental" no chat, em uma ou duas linhas. Se o usuário já o forneceu, diga "Entendi" e vá direto para o estágio 1.

Depois, antes do trabalho do estágio 1: execute a verificação do computador e leia as lições (abaixo).

O computador está pronto?

Execute o verificador somente leitura: Mac/Linux bash <skill>/setup/doctor.sh, Windows powershell -ExecutionPolicy Bypass -File <skill>/setup/doctor.ps1.

• Tudo OK → continue. "Chave OpenRouter: opcional, não definida" é aceitável.
• Algo faltando → siga o passo 3 de <skill>/setup/SETUP-PROMPT.md (o texto do prompt) você mesmo, instalando apenas o que está faltando. Diga ao usuário o que está instalando em uma linha cada. Execute o verificador novamente no final.

O motor de voz precisa de HYPERFRAMES_PYTHON apontando para o python do venv; se uma chamada tts disser que o kokoro-onnx está faltando, defina-o para esse comando.

Leia as lições

Leia <skill>/knowledge/lessons.md e, se existir, ~/VideoStudio/lessons.md (as do usuário). Aplique cada lição cujo escopo corresponda (global, o estilo escolhido, a marca escolhida). Quando o usuário der feedback, use <skill>/knowledge/feedback-playbook.md para transformá-lo em correções, então adicione uma lição em ~/VideoStudio/lessons.md para que o próximo vídeo comece certo.

Os cinco estágios

Leia <skill>/knowledge/pipeline.md uma vez por sessão: estágios, o ciclo de feedback, layout da pasta, project.json. Siga suas regras em cada etapa: atualize project.json, regenere o quadro, abra a página que o usuário precisa ver.

Cada porta: mostre a saída → pergunte "Aprova, ou me diga o que mudar" → se não estiver certo, repita a correção, refaça este estágio, mostre novamente (round + 1). Uma mudança em um estágio anterior marca os estágios posteriores para refazer; diga quais em uma linha.

Estágio 1 — Roteiro (porta)

1. Leia o despejo mental e quaisquer arquivos. Escreva brief.md: tópico, público, a única coisa que os espectadores devem lembrar, objetivo (explicar / persuadir / lançar), duração alvo, números ou fatos obrigatórios, tom, restrições.
2. Pergunte uma vez: "Você tem uma chave OpenRouter? É opcional; permite gerar imagens e pequenos clipes de vídeo para B-roll." Pule se OPENROUTER_API_KEY já estiver definida ou o usuário disse não na configuração. Veja knowledge/openrouter.md. Registre openrouter: true/false no project.json.
3. Siga <skill>/knowledge/script-intelligence.md. Escreva script.md no formato de batida a 150 wpm neutro (o estilo ainda não foi escolhido; diga isso na seção 4). Mantenha visual_idea em palavras simples; os tipos de cena são adicionados no estágio 2.
4. Regenere o quadro (ele transforma script.md em script.html), abra script.html, pergunte: "Aqui está o roteiro. Aprova, ou me diga o que mudar." Dê as opções de gancho e duração no chat em 3-4 linhas.

Estágio 2 — Storyboard (porta): estilo, marca, depois quadros

1. Estilo: leia o frontmatter de cada <skill>/styles/*.md (pule _TEMPLATE.md). Escolha os 2-3 que se encaixam no brief (melhor_para, não_para, precisa_de_pessoa_em_cena). Construa o seletor: node <skill>/templates/stylepicker.mjs <project> --recommend id1,id2,id3, abra styles.html e pergunte no chat: "Qual estilo? Sugiro X porque ... (responda com um nome ou número)." A página é apenas para olhar; o usuário responde no chat. Se escolher um estilo não testado (tested: false), diga: "Esse funciona, mas espere uma rodada extra de feedback."
2. Marca: liste marcas em <skill>/brands/*/design.md e ~/VideoStudio/brands/*/design.md. Ofereça: uma marca existente, "criar uma a partir do meu site / guia de marca" ou "sem marca (cores do estilo)". Para criar uma, siga <skill>/knowledge/brand-intake.md e salve em ~/VideoStudio/brands/<id>/. Força: a recomendação da marca para este estilo (tabela §7), padrão acento; mencione em uma linha.
3. Registre estilo, marca, forcaMarca no project.json. Leia ambos os arquivos completamente. Escreva a paleta e fontes mescladas em project.json → look.
4. Estude a referência antes de planejar (knowledge/quality-gate.md §1): baixe o vídeo de referência do estilo, faça tiras, meça com templates/style_compare.py e escreva reference.md: o que o torna bom em voz, som, câmera, cortes, gráficos e pessoas. Diga as lacunas agora: se a voz gratuita, a falta de apresentador ou qualquer outra coisa não conseguir alcançar a referência, informe o usuário com opções e custos e obtenha uma decisão antes de construir.
5. Re-pace: mova o roteiro de 150 wpm para o ritmo do estilo (pace_wpm em seu frontmatter; veja pipeline.md "O que ritmo significa"). Atualize script.md e liste o que mudou em no máximo 5 linhas.
6. Quadros: siga <skill>/knowledge/storyboard.md. Cada quadro cita seu timestamp de ref, movimentos, camera, sfx e corte_em (quality-gate §2), e os cortes, movimentos de câmera e SFX por minuto do plano devem atingir os da referência antes de você mostrar. Escreva storyboard.json (um sketch_svg aproximado por quadro, e a lista "o que mudou" como changes), execute node <skill>/templates/storyboard.mjs <project>, abra storyboard.html, peça aprovação ou anotações por quadro.

Estágio 3 — Elenco (porta; pulado se não houver pessoas)

Se algum quadro tiver pessoas, siga <skill>/knowledge/casting.md: liste os papéis, escolha a biblioteca que a seção 4c do estilo nomeia, comece pelas pessoas prontas em <skill>/casting/library/, vista cada papel (roupa + adereço) com 3-4 posições do mesmo personagem, execute sua auto-verificação, mostre 2-3 candidatos por papel em uma página de elenco e aguarde as escolhas. Empacote as escolhas em assets/cast.js. Sem pessoas → defina o estágio como pulado e diga em uma linha.

Estágio 4 — Prévia (porta)

1. Voz: node <skill>/templates/voice.mjs <project> (lê storyboard.json e project.json → voice). Um clipe por batida com a voz Kokoro local gratuita, medido, timing.json, unido em assets/vo/full.wav. Refazer batidas individuais com --only B03,B07. Diga ao usuário a duração total e wpm.
2. Construir a parte da prévia: construa apenas as cenas para os 20 segundos que melhor mostram o visual, as pessoas e o movimento (geralmente o gancho mais a primeira cena com pessoas), com as regras de construção do estágio 5 e execute as auto-verificações nelas.
3. Porta de qualidade antes de mostrar (knowledge/quality-gate.md §3-4): execute style_compare.py contra a janela de referência dos mesmos tipos de cena, então passe a prévia para um novo agente revisor com templates/reviewer-prompt.md. Corrija e repita até que cada pontuação seja 4+ (máx. 3 rodadas). Você nunca aprova sua própria renderização.
4. Renderize apenas essa parte para renders/preview.mp4 (sua própria composição de capítulo, ou um corte curto de rascunho com ffmpeg -ss S -t 20). Coloque no quadro, abra, pergunte: "Isso parece certo? Algo a mudar antes de eu fazer o vídeo completo?" Mostre as pontuações do revisor e qualquer medida ainda abaixo da referência ao lado. Uma prévia custa alguns minutos; uma renderização completa é muito mais longa.

Estágio 5 — Construir e renderizar (porta final)

Construir. Carregue as skills do HyperFrames (/hyperframes, /hyperframes-cli) para o contrato de renderização. Construa a partir de storyboard.json + timing.json + a receita de construção §10 do estilo + o visual mesclado (project.json → look).

• Gere assets/beats.js (timing + palavras da narração) para que cada sinalização possa ser vinculada a uma palavra falada: tempo da sinalização = início da batida + duração da batida × índice da palavra ÷ contagem de palavras.
• Um grupo de cena por quadro do storyboard; mudanças de cena conforme o transition_out do quadro (corte ou panorâmica), atrasadas se a última linha sair antes de poder ser lida.
• Vídeos de 3 minutos ou mais: mantenha cada capítulo renderizável individualmente (veja knowledge/rendering.md) para que uma correção re-renderize apenas aquele capítulo.
• Para o estilo Ray Dalio, comece a partir de <skill>/templates/kits/dalio-kit.js. Construção de referência: <skill>/examples/cx-ai-budget/.
• Moldura de marca (cartão de introdução/fim) a partir da seção §6 da marca, logotipo de sua pasta.
• Registre a linha do tempo raiz em um <script> inline no index.html (o verificador exige isso). Apenas determinístico.
• Siga as regras de movimento da seção 4b do estilo: pessoas mudam de pose em palavras faladas a cada 1-2 segundos e respiram; adereços se desenham gradualmente; cada cena tem uma câmera (deriva + aproximações); mudanças de cena dentro de um capítulo são panorâmicas ou zoom-through.
• Imagens ou B-roll do OpenRouter apenas se o usuário tiver uma chave e concordar com o custo (knowledge/openrouter.md). Após construir: npx hyperframes check (corrija erros; trate dead_stretch acima de 4 s e line_unread como reais) e npx hyperframes snapshot --at <tempos>; olhe cada quadro.

Som. Escreva sound.json (fundo musical, quedas, e cada efeito indicado em uma batida + palavra, a partir dos sfx do storyboard e da seção §7 do estilo), então node <skill>/templates/mix.mjs <project>: ele mistura voz, música e efeitos e normaliza o volume em assets/mix.wav. Aponte o <audio> da composição para ele. Use <skill>/assets/starter-kit/ primeiro (veja seu MANIFEST.md); busque mais apenas em <skill>/assets/sources.md.

Auto-verificações (execute todas, corrija antes de mostrar qualquer coisa):

1. Cores da marca: todo código hexadecimal nas cenas está no arquivo da marca (ou na paleta do estilo quando não há marca).
2. Sem cenas apenas com texto a menos que a seção 14 do estilo as permita.
3. Pessoas: cada papel é o elenco escolhido, ninguém é cortado pela borda do quadro, ninguém mantém uma pose por mais de 2 segundos na tela, nenhuma pessoa invertida carrega texto espelhado.
4. Movimento: renderize, então python <skill>/templates/motion_metrics.py renders/draft.mp4; compare com os alvos da seção 14 do estilo. Um número preenchido que erra seu alvo é uma correção, não uma nota de rodapé.
5. Visual: coloque uma captura de tela ao lado de um quadro de referência do vídeo do estilo e pergunte: um espectador diria que é o mesmo estilo?
6. Assista: faça uma tira de quadro (ffmpeg -ss S -t 24 -i video -vf "fps=2.5,scale=320:-1,tile=6x10" strip.jpg) de cada cena e procure por trechos vazios, coisas fora da tela e objetos no lugar errado.

Renderizar. Siga <skill>/knowledge/rendering.md: verifique a memória livre primeiro e escolha o número de workers a partir dela; renderize vídeos de 3 minutos ou mais em partes com node <skill>/templates/render_parts.mjs. Rascunho para renders/draft.mp4, final para renders/final.mp4.

Porta de qualidade (novamente, no rascunho completo). style_compare.py + um novo revisor, como na prévia. O polimento faz parte da primeira construção, não algo que o usuário precise pedir: marque cada item da lista de verificação da quality-gate §6 antes de renderizar.

Revisão final (porta). Abra o vídeo, peça correções como uma lista curta. Aplique-as, re-renderize apenas as partes alteradas, junte, mostre novamente. Quando aprovado, escreva description.txt: opções de título, uma descrição de 2 linhas, timestamps dos capítulos, créditos (música, sons, desenhos, imagens geradas). Marque todos os estágios como concluídos, abra o quadro.

Regras

• Nunca mostre uma renderização que não tenha passado pela porta de qualidade, e nunca seja aquele que aprova sua própria renderização: um novo agente revisor a pontua contra a referência. Se ainda falhar após 3 rodadas, mostre-a com as pontuações e diga claramente o que está abaixo da referência.
• Copie o que torna a referência boa (entrega de voz, efeitos sonoros, energia musical, movimento de câmera, ritmo de corte, densidade de gráficos), não apenas sua aparência. Meça cada um contra a referência.
• Nunca pule uma porta. Nunca construa antes do storyboard ser aprovado e o elenco escolhido. Nunca renderize o vídeo completo antes da prévia ser aprovada.
• Feedback sempre termina como uma lição (veja acima); o mesmo erro não deve acontecer duas vezes.
• Uma pergunta de cada vez, sempre com um padrão sensato que o usuário possa aceitar com "sim".
• Nunca afirme que uma etapa funcionou sem verificar (captura de tela, ffprobe, saída da renderização).
• Nunca gaste dinheiro sem perguntar: diga o custo estimado de cada lote de geração paga primeiro.
• Verifique a memória livre antes de cada renderização (knowledge/rendering.md); nunca inicie uma que possa travar o computador.
• Se algo não puder ser bem feito (por exemplo, um estilo liderado por apresentador sem filmagem), diga claramente e ofereça a opção sem rosto mais próxima.
• Mantenha tudo dentro da pasta do projeto; nunca exclua os arquivos do usuário.

Arquivos nesta skill

Caminho	O que é
knowledge/pipeline.md	Os cinco estágios, o ciclo de feedback, layout da pasta, project.json, regras de tempo
knowledge/script-intelligence.md	Despejo mental → roteiro: tipos de vídeo, frameworks, ganchos, regras de fala, formato de batida
knowledge/storyboard.md	Roteiro → storyboard: esquema de quadro, método, ciclo de revisão
knowledge/casting.md	Porta de elenco: papéis, bibliotecas, vestimenta, página de elenco, empacotamento do elenco
knowledge/rendering.md	Renderização segura: regra de memória livre, workers, renderização de vídeos longos em partes, re-renderização de uma parte
knowledge/openrouter.md	Imagens e clipes de vídeo pagos opcionais através do OpenRouter (não testado)
knowledge/quality-gate.md	Estudo de referência, plano-para-referência, medição, revisão independente, lições como verificações, lista de verificação de polimento
templates/style_compare.py	Mede uma renderização contra a referência
templates/reviewer-prompt.md	Nova revisão de qualidade por um agente independente
templates/board.mjs	Gera o quadro do projeto
templates/stylepicker.mjs	Página de seleção de estilo
templates/storyboard.mjs	Página do storyboard
templates/voice.mjs	Síntese de voz por batida
templates/mix.mjs	Mixagem de áudio e normalização
templates/motion_metrics.py	Métricas de movimento da cena
templates/kits/dalio-kit.js	Kit de construção para o estilo Ray Dalio
templates/render_parts.mjs	Renderização de vídeos longos em partes
styles/*.md	Definições de estilo visual
brands/*/design.md	Definições de marca registrada
casting/library/	Atores prontos
assets/starter-kit/	Pacote de áudio e recursos inicial
examples/cx-ai-budget/	Projeto de exemplo para referência
setup/doctor.sh / doctor.ps1	Verificador de prontidão do computador
setup/SETUP-PROMPT.md	Instruções de configuração