clip-builder

Criador de clipes (Clip builder)

Construa um vídeo curto a partir de três partes: uma página HTML que renderiza a imagem (a cena), uma lista de linhas de roteiro em clip.json (as marcações) e uma ferramenta de linha de comando que captura a página quadro a quadro e codifica um MP4.

A página da cena define draw(s), que coloca a página no estado correspondente ao segundo s, calculado apenas a partir de s. A captura chama essa função para cada quadro (segundo 0, depois 1/30 e assim por diante) e tira uma captura de tela. Como resultado, a saída não depende da velocidade da máquina, qualquer quadro pode ser renderizado isoladamente para revisão, e uma alteração em uma parte do clipe pode ser recapturada usando --from e --to.

A CLI é scripts/clip.mjs no diretório deste skill. Neste documento, clip significa node "<dir do skill>/scripts/clip.mjs", onde <dir do skill> é o caminho absoluto do diretório que contém este arquivo. (O Claude Code substitui esse caminho aqui: ${CLAUDE_SKILL_DIR}. Em outros agentes, use o diretório de onde este arquivo foi lido.) Execute os comandos a partir do diretório do projeto do clipe, que contém clip.json. clip help lista todos os comandos e opções.

Requisitos

Node 20 ou superior, ffmpeg e Playwright com Chromium. clip doctor verifica esses itens e imprime comandos de instalação para o que estiver faltando. Instale o Playwright no diretório onde os clipes são construídos (npm install --save-dev playwright, depois npx playwright install chromium), não no diretório deste skill. Narração e música gerada são opcionais. São as únicas etapas que custam dinheiro ou precisam de uma chave de API.

Comandos em sandbox (padrão no Codex): clip stills, clip capture e clip serve iniciam um servidor HTTP em 127.0.0.1, e os dois primeiros também iniciam o Chromium. Uma sandbox de comandos bloqueia ambos. O comando então sai com status 1 e uma mensagem que nomeia a sandbox. Solicite aprovação para executar esses três comandos fora da sandbox e informe o motivo. Não substitua por outro método de captura. Os outros comandos não precisam de servidor nem navegador e funcionam dentro da sandbox; tts --generate e music --generate também precisam de acesso à rede.

Briefing

Estabeleça o seguinte antes de começar. Pergunte apenas o que estiver faltando. Para tudo que o usuário não especificou, use o padrão e informe em uma linha.

• Propósito e público: promoção, demonstração de produto, tutorial para equipe, aula. Isso define o ritmo. Clipes promocionais são rápidos; clipes de treinamento deixam tempo para acompanhar cada etapa.
• Duração. Padrão: 20 a 45 segundos para promoção ou demonstração, 60 a 120 para treinamento.
• Destino, que determina os quadros. Padrão: wide 1920×1080, mais tall 1080×1350 para feeds sociais. Veja references/delivery.md.
• Abordagem visual: novos gráficos ou uma tela de aplicativo. Para um aplicativo: quais telas e se o código-fonte ou sistema de design está disponível como fonte para cores, tipografia e espaçamento.
• Áudio. Padrão: silencioso com legendas. Isso é gratuito e a maioria dos vídeos em feeds é reproduzida sem áudio. Narração e música são opcionais.
• Roteiro. Use o roteiro do usuário se ele tiver um. Caso contrário, elabore um e obtenha sua aprovação antes de construir a cena.

Fluxo de trabalho

1. Verifique as ferramentas: clip doctor.
2. Crie o projeto: clip init <dir> --template graphics ou --template app-ui. Isso escreve clip.json, um diretório scene/ com um exemplo funcional e audio/. Ambos os templates renderizam sem alterações.
3. Escreva as marcações em clip.json, uma por batida. Uma batida é um segmento do clipe com uma linha e um estado visual. Escreva o roteiro primeiro: a cena tem seu tempo ajustado a ele, e qualquer mudança na redação após a gravação é outra requisição paga. references/narration.md cobre a escrita para fala.
4. Construa a cena: edite scene/index.html e scene/scene.js. Leia references/scenes.md primeiro. Ele lista as restrições que mantêm uma cena determinística: sem Math.random(), sem relógios ou temporizadores, sem animações CSS, todo estado calculado a partir de s. Para uma tela de aplicativo, leia também references/app-ui.md.
5. Revise os stills: clip stills escreve quadros em segundos selecionados e uma folha de contato em out/review/. Abra a folha de contato como imagem e inspecione-a. Verifique se o texto é legível, nada se sobrepõe e cada batida está na tela enquanto sua legenda é exibida. Repita para cada tamanho de quadro (--frame tall). Faça a maior parte da iteração nesta etapa: stills são rápidos e não custam nada. clip serve fornece uma prévia ao vivo para o usuário.
6. Capture um rascunho: clip capture --draft renderiza em dois terços do tamanho para verificar movimento e ritmo. Dê ao usuário o caminho do arquivo e peça para ele assistir.
7. Adicione som, se solicitado. Narração: references/narration.md. Música e mixagem: references/sound.md. Execute clip tts sem flags primeiro; ele lista as requisições planejadas e contagens de caracteres. Obtenha a aprovação do usuário, depois execute clip tts --generate. Após qualquer nova gravação, execute clip timing, que posiciona as marcações e legendas e, se configurado, ajusta a duração da cena à narração. Depois revise os stills novamente.
8. Capture o final: clip capture --final para cada quadro, depois clip mix se houver som, depois clip web <arquivo> para uma cópia menor para upload.
9. Verifique e relate: revise stills do final, leia o volume no relatório da mixagem e execute clip scan out. Relate o que foi produzido, os caminhos dos arquivos, o que foi verificado e o que não foi.

Um clipe silencioso pula a etapa 7. Suas legendas vêm dos valores at e until de cada marcação, e clip timing as escreve para a página.

Regras de segurança

Um trabalho de clipe envolve dinheiro do usuário, chaves de API e identidade publicada.

• Requisições pagas exigem aprovação explícita do usuário. O provedor cobra por narração e música. A CLI não envia nada sem --generate; passe essa flag apenas após o usuário aprovar aquela tomada específica. Aprovação para uma tomada não cobre a próxima. Mostre a saída do dry-run (linhas e contagens de caracteres) ao pedir. Se uma requisição for interrompida, seu recibo fica como attempted. Não tente novamente até que o usuário tenha verificado o histórico de uso do provedor, pois a requisição pode ter sido faturada.
• Chaves de API vêm apenas do ambiente. A CLI lê ELEVENLABS_API_KEY ou OPENAI_API_KEY e nenhuma outra fonte. Passe uma chave inline para um único comando a partir do cofre de segredos do usuário (references/keys-and-paid-calls.md tem os comandos). Não peça ao usuário para colar uma chave na conversa, não imprima uma (echo, env, cat) e não escreva uma em um arquivo. Para confirmar se uma chave está definida, verifique seu comprimento; clip doctor faz isso.
• Entregue arquivos; não publique. Postar ou fazer upload de um clipe é ação do usuário, a menos que ele solicite essa ação específica.
• Use apenas material que o usuário tenha o direito de usar. Música, fontes, logotipos e filmagens precisam de licença ou propriedade do usuário. Mostre apenas um aplicativo que o usuário possua ou tenha permissão para mostrar, e não estilize um mock-up como produto de outra empresa. Os termos de ambos os provedores cobrem uso comercial e divulgação de vozes geradas; aponte o usuário para eles antes de um clipe narrado ser publicado.
• Mantenha dados privados fora da imagem e dos arquivos. Use nomes e números fictícios em telas de aplicativos. Figuras e citações apresentadas como reais devem ser reais, e exemplos devem ser identificáveis como exemplos. Execute clip scan em qualquer coisa antes de ser compartilhada. Ele verifica chaves de API, nome de usuário local e caminhos, endereços de e-mail, a lista de termos privados do usuário e metadados incorporados em arquivos de mídia.

Diretrizes editoriais

• Cubra um tópico por clipe. Divida um roteiro que cubra dois.
• Comece a narração ou a primeira legenda nos primeiros segundos.
• Use uma marcação por batida e mantenha o visual de uma batida na tela enquanto sua linha é falada.
• Sempre inclua legendas. A maioria dos vídeos em feeds é reproduzida sem áudio.
• Revise quadros verticais (tall) no tamanho de um telefone. A unidade da cena é maior em quadros verticais por esse motivo.
• Use movimento para marcar uma mudança de estado ou para direcionar a atenção. Evite movimento contínuo.
• Mantenha o cartão de encerramento por pelo menos 2,5 segundos.
• Para treinamento: mostre a ação, depois seu resultado, em um ritmo que o espectador possa acompanhar enquanto a executa. Numere os passos na tela e informe no início o que o espectador será capaz de fazer.

Comandos

Comando	Função
clip doctor	Verifica Node, ffmpeg e Playwright, e relata quais chaves estão definidas (apenas comprimento)
clip init <dir> --template graphics|app-ui	Cria um projeto a partir de um exemplo funcional
clip serve	Fornece uma prévia ao vivo; ?t=5 na URL pausa em 5 s
clip stills [--at 2,5,9] [--frame tall] [--final]	Renderiza stills de revisão e uma folha de contato
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	Renderiza todos os quadros e codifica um MP4
clip capture --mode clock --url … --seconds N [--actions file.mjs]	Captura um aplicativo em execução (experimental; veja references/app-ui.md)
clip tts [--generate]	Lista a narração ainda a gravar; com --generate, grava (pago)
clip music [--generate]	O mesmo para uma trilha sonora gerada (pago)
clip timing	Calcula tempos de marcações e legendas; escreve scene/timing.json e um .srt
clip mix	Constrói a trilha sonora com volume padronizado e a multiplexa em cada vídeo capturado
clip web <vídeo>	Escreve uma cópia menor para upload
clip scan <dir> [--terms-file words.txt]	Relata dados privados antes de os arquivos serem compartilhados
clip strip <arquivo de mídia>	Escreve uma cópia com todos os metadados incorporados removidos

A saída vai para out/, nomeada <nome>-<tomada>-<quadro>.mp4, com os sufixos -draft, -part (um intervalo capturado com --from/--to), -sound e -web adicionados conforme aplicável. Para manter uma versão anterior ao lado de uma nova, incremente "take" em clip.json (a, b, c, …).

Arquivos de referência

Leia o arquivo que a etapa atual precisa.

Arquivo	Leia quando
references/scenes.md	Escrevendo ou alterando uma cena: o contrato da página, a biblioteca auxiliar, unidades, quadros verticais, fontes e as restrições que mantêm uma captura determinística
references/app-ui.md	O clipe mostra uma tela de aplicativo: reconstruindo a partir de tokens de design, o ponteiro, digitação, movimentos de câmera e captura de um aplicativo em execução
references/narration.md	Escrevendo linhas, escolhendo um provedor e voz, pronúncia, regravando uma linha, ajustando a cena à narração, legendas
references/sound.md	Música e mixagem: níveis, ducking, ajustando uma faixa ao clipe, volume, corrigindo uma mixagem
references/keys-and-paid-calls.md	Antes de qualquer requisição paga: passando uma chave com segurança, o que é enviado, recibos, requisições interrompidas
references/project-file.md	Qualquer campo de clip.json
references/delivery.md	Tamanhos de quadro, renderização final, verificações antes da entrega, o que relatar
references/cookbook.md	A solicitação corresponde a um trabalho comum. Doze receitas prontas: um clipe silencioso, uma tela de aplicativo a partir de tokens de design, várias proporções de tela, um clipe de treinamento passo a passo, um gráfico de barras a partir de JSON, narração com cada provedor, regravando uma linha, música de fundo, fonte e logotipo personalizados, um aplicativo em execução, verificações finais. Também trechos de draw()

Solução de problemas

Sintoma	Causa provável
"Isto parece uma sandbox de comandos", listen EPERM ou o navegador falha ao iniciar	A sandbox do agente está bloqueando o servidor HTTP ou o navegador. Execute stills, capture e serve fora dela, com a aprovação do usuário
"A página nunca definiu window.ready"	Um erro de script na cena (a mensagem lista os erros da página), ou a página não chama clip() do kit
Duas capturas da mesma cena diferem	Algum estado na cena não é calculado a partir de s: Math.random(), Date, uma animação ou transição CSS, um <video>, um temporizador
O texto renderiza em uma fonte diferente em outra máquina	A cena usa fontes do sistema. Coloque arquivos de fonte no diretório da cena (references/scenes.md)
A imagem está adiantada ou atrasada em relação à narração	clip timing não foi executado após uma nova gravação, ou o vídeo foi capturado antes dele. clip mix se recusa a executar no primeiro caso e avisa no segundo
attempted na lista do tts	Uma requisição anterior não foi concluída. Verifique o histórico de uso do provedor antes de usar --retry-attempted
O nível da música sobe e desce entre as palavras	Defina "mix": { "master": "limit" } (references/sound.md)