Communitygithub.com

leocosta/octopus

Transforme um aplicativo em execução em um vídeo promocional dinâmico e de alta fidelidade, dirigindo o produto real (headless Chrome) contra um ambiente de demonstração/sandbox, capturando imagens limpas e compondo um corte de motion design.

O que é octopus?

Esta skill gera vídeos promocionais de alto nível para produtos de software, indo muito além de simples gravações de tela. Ela automatiza um processo de produção completo: inicia o aplicativo real em um navegador headless (Chrome), navega por um roteiro de cenas (beats) pré-definido em um ambiente de demonstração, captura screenshots nítidos de cada tela e, em seguida, compõe um vídeo com motion design profissional sobre essas imagens. O resultado é um vídeo dinâmico que inclui tipografia cinética, zooms suaves, destaques com spotlight, molduras de celular para telas mobile, cortes rítmicos e uma trilha sonora. A skill é agnóstica ao aplicativo, lendo configurações de um arquivo `promo.config.mjs` e uma lista de cenas (`beats.json`) específicas do projeto. Uma de suas funcionalidades mais poderosas é a extração automática do sistema de design do aplicativo alvo (como cores primárias e fontes), garantindo que os overlays e animações combinem perfeitamente com a identidade visual da marca. O resultado final é exportado em dois formatos: um mestre 16:9 (widescreen) e uma versão vertical 9:16, otimizada para plataformas como Instagram Reels e TikTok. Ideal para equipes de produto e marketing que precisam de vídeos de demonstração de alta qualidade e facilmente reproduzíveis.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Protocolo de Promo Motion

Visão Geral

Esta skill renderiza um vídeo promocional dinâmico de nível profissional de um produto real, não uma gravação de tela nem uma maquete. Ela controla o aplicativo real em um navegador headless contra um ambiente de demonstração, captura imagens nítidas de cada tela e compõe uma edição de motion design sobre elas: tipografia cinética, close-ups cinematográficos, destaques spotlight que acompanham o zoom, molduras de telefone para telas mobile, cortes de cena rítmicos e uma trilha sonora. A saída é um mestre 16:9 e um corte vertical 9:16.

É a contraparte de renderização de launch-feature: launch-feature escreve um video-script.md (o roteiro/momentos em prosa); motion-promo transforma uma lista de momentos no vídeo finalizado e com trilha sonora. Quando ambos são executados, encadeie-os — script de launch-feature → momentos de motion-promo.

Por que HyperFrames (HTML→MP4) e não gravação de tela: determinístico, reexecutável, controlável pela marca e evita os modos de falha da captura de navegação ao vivo (consulte Regras). O aplicativo é usado apenas para produzir imagens + tokens de design; todo o movimento é criado.

Quando Usar

  • Uma página de destino / de vendas precisa de uma demonstração do produto ou de um vídeo herói.
  • Anunciar um recurso e você quer o vídeo renderizado, não apenas o script.
  • Você tem um locatário de demonstração/sandbox com dados minimamente realistas para mostrar.

Não usar para: tutoriais internos onde a fidelidade não importa (uma captura de tela bruta é mais barata) ou aplicativos sem um ambiente de demonstração executável.

Pré-requisitos e segredos

Nenhuma chave de API / segredo é necessária. A renderização do HyperFrames é sem chave (HTML local→MP4), e as fontes (Google Fonts) + a música padrão (incompetech) são URLs públicas. A única credencial é o login de demonstração do aplicativo alvo, que reside no promo.config.mjs do repositório alvo — nunca nesta skill. A autenticação é uma receita conectável: authInject() retorna valores a serem injetados (token no localStorage, cookie, chave de API, seleção de locatário em várias etapas), ou authFlow(page) DIRIGE uma interface de login interativa (Azure AD / Entra, Okta, Google SSO) e o mecanismo captura o estado da sessão (localStorage + sessionStorage + cookies, incluindo HttpOnly). As credenciais SSO vêm do ambiente, não do arquivo. Headless não pode passar por MFA interativa — use uma conta de demonstração isenta de MFA (exceção de Acesso Condicional) ou uma senha de aplicativo.

Dependências do sistema (você as instala — a skill não pode): Node 20+, Chrome do sistema (google-chrome/Chromium), ffmpeg + ffprobe. Saída de rede para fontes/música.

Dependências automáticas/sob demanda: hyperframes é obtido sob demanda via npx (sem pré-instalação). puppeteer-core é uma dependência npm scaffolding — ele usa o Chrome do sistema e não baixa um Chromium.

Configuração: scaffolding dos templates/ em video/<slug>/ (inclui hyperframes.json; meta.json é gerado pelo compose-gen), renomeie gitignore → .gitignore, depois npm install e npm run preflight (verifica Chrome, ffmpeg/ffprobe e puppeteer-core; falha ruidosamente se algum estiver faltando). Execute o pipeline passo a passo ou npm run build.

  • Uma demonstração/sandbox executável do aplicativo alvo.

Entradas

Tudo específico do projeto reside no repositório alvo, nunca nesta skill:

  1. promo.config.mjs — o contrato (consulte templates/promo.config.example.mjs). URL do app / como servir, receita de autenticação, conta/locatário de demonstração, caminhos de saída e preferência de música. Os tokens de design são extraídos automaticamente (etapa 2), mas podem ser substituídos aqui.
  2. beats.json — a lista ordenada de tomadas (consulte templates/beats.schema.json). Cada batida = uma tela (rota ou imagem capturada) + destino de destaque opcional + texto de chamada + viewport (desktop/mobile).

Faça scaffolding de ambos em video/<slug>/ no repositório alvo a partir de templates/.

Protocolo

Trabalhe dentro de video/<slug>/ no repositório alvo. Cada etapa tem uma verificação.

0. Cure os dados de demonstração (faça isso primeiro — isso faz ou quebra o vídeo)

Os dados de demonstração/sandbox geralmente estão desatualizados ou zerados para o período atual (faturas não pagas do mês corrente, funis vazios), o que aparece como "R$ 0 de receita" ao lado de "no piloto automático" — ativamente fora da mensagem. Antes de capturar, escreva uma semente idempotente relativa à data atual que forneça números saudáveis para cada momento (consulte Regras → Dados de demonstração zerados). Verifique consultando as métricas que cada momento mostrará.

1. Sirva o aplicativo contra a API de demonstração, em uma origem com CORS permitido

Construa/sirva o aplicativo apontando para a API de demonstração. A origem de serviço deve estar na lista de permissões CORS da API ou cada busca de dados será bloqueada e as telas renderizarão vazias (consulte Regras → Origem CORS). Investigue a lista de permissões da API e sirva em uma porta permitida. Verifique: uma rota profunda retorna 200 e uma requisição autenticada /api/... dessa origem retorna 2xx.

2. Extraia o sistema de design do aplicativo alvo

Execute templates/engine/extract-design.mjs contra o aplicativo autenticado e servido. Ele amostra estilos computados (fundo da página, cor primária/destaque de botões/links, famílias de fontes de título e mono, raio) → design.tokens.json. Esses alimentam a composição como variáveis CSS para que as sobreposições cinéticas, destaque e fontes correspondam automaticamente à marca do aplicativo. Revise + substitua em promo.config se um token amostrado estiver errado.

3. Capture imagens limpas por momento

Execute templates/engine/capture.mjs. Ele autentica (via a receita authInject da configuração), navega para a rota de cada momento em seu viewport, aguarda o carregamento de dados reais (não apenas network-idle — consulte Regras) e tira screenshots para assets/<beat>.png. Verifique se cada imagem mostra conteúdo carregado (tamanho > ~10 KB, verifique se o elemento alvo está presente).

4. Defina os momentos + gere a composição

Preencha beats.json (rota/imagem, destaque {x,y,w,h,label} no espaço de pixels da imagem — ou {selector,label,padding?}, medido automaticamente pelo capture.mjs e preferido em relação a coordenadas ajustadas manualmente, chamada {kicker,headline,sub}, viewport, durações). Execute templates/engine/compose-gen.mjs → index.html a partir de templates/composition.html, injetando tokens + momentos. Mantenha impactante: 3–5 s por momento, cortes secos, uma ideia por momento.

5. Obtenha uma faixa de música gratuita

Execute templates/engine/fetch-music.mjs → assets/music.mp3. A fonte padrão é CC-BY (incompetech); CC-BY requer atribuição (registre-a para a descrição do LP). Prefira uma faixa fornecida pelo projeto/CC0 quando disponível.

6. Renderize

npx hyperframes render → MP4 silencioso. Execute hyperframes lint/inspect primeiro; trate o estouro decorativo/de animação de saída fora da tela como ruído, o recorte de texto real como uma correção.

7. Revise os quadros + corrija o alinhamento do destaque

Extraia quadros no início e no final de cada push-in e examine-os. O #1 defeito: o destaque spotlight se desvia do alvo durante o zoom — porque a caixa de destaque deve ser um filho do container escalado (consulte Regras → Rastreamento de destaque). Verifique também: sem telas vazias/loading, telas mobile posicionadas corretamente dentro da moldura do telefone, texto legível.

8. Multiplexe a música

Execute templates/engine/mux.mjs → MP4 final com trilha sonora (loudnorm, fade in/out, -shortest). Verifique se a saída possui um stream de áudio e corresponde à duração do vídeo.

9. Derive o corte 9:16

mux.mjs --reframe produz um corte 1080×1920. Não corte centralizado (corta chamadas ancoradas na parte inferior) — use uma letterbox desfocada que preserve todo o quadro; os momentos mobile já estão centralizados.

Regras (conquistadas com esforço — não as reaprenda)

  • Rastreamento de destaque. Um retângulo spotlight/destaque sobre uma tela que faz push-in DEVE ser um filho do mesmo elemento que recebe a transformação scale, no espaço de coordenadas de pixels da imagem. Como irmão, ele permanece fixo enquanto a imagem dá zoom e se desvia do alvo ao longo do plano.
  • Dados de demonstração zerados. O período atual geralmente não foi pago / está vazio. Cure-o com uma semente que seja idempotente (ids determinísticos, delete-then-insert) e relativa a current_date para que se auto-corrija a cada período.
  • Origem CORS. Uma compilação servida localmente chamando uma API de demonstração implantada é de origem cruzada. Sirva em uma origem que a API permite (investigue) — nunca desative a segurança do navegador para contornar isso.
  • Aguarde dados reais. networkidle2 pode resolver antes da requisição de dados do aplicativo chegar → você captura um spinner. Aguarde adicionalmente por uma resposta /api/... bem-sucedida (ou pelo seletor de conteúdo alvo) antes de tirar o screenshot.
  • HyperFrames em vez de captura ao vivo. A transmissão CDP para de emitir quadros em uma página visualmente estática e roda abaixo do fps nominal; a criação em HTML (GSAP) evita ambos. Se você alguma vez precisar gravar ao vivo, agite o cursor e codifique no fps efetivo.
  • Licenciamento de música. CC-BY (incompetech/Kevin MacLeod) precisa de atribuição na descrição do LP; CC0 (Pixabay etc.) não precisa. Nunca envie um clipe raspado sem licença em uma página publicada.
  • Concatenar com o filtro, não com o demuxer se os segmentos tiverem fps variáveis — o demuxer descarta quadros silenciosamente.

Extração do sistema de design (branding agnóstico)

A composição é neutra em relação à marca; extract-design.mjs preenche suas variáveis CSS a partir do próprio aplicativo alvo: --bg (fundo do body), --accent (cor primária/link), --fg (cor do título), --font-hero/--font-mono (famílias de fontes computadas), --radius. Isso é o que faz uma única skill produzir vídeos promocionais alinhados à marca para qualquer aplicativo sem selecionar tokens manualmente. Sempre revise os tokens amostrados — uma cor de baixo contraste ou ad-hoc ocasionalmente amostra errado; substitua em promo.config.design.

Erros

  • O aplicativo não autentica em headless → a receita authInject da configuração está errada; verifique se os tokens caem no localStorage/cookies antes da primeira navegação.
  • Telas renderizam vazias → Origem CORS (etapa 1) ou aguardar dados (Regra) perdido.
  • Erros de renderização fora da tela → recorte de texto real precisa de fonte menor / quebra de linha; estouro decorativo/de saída é ruído.
  • Destaque desalinhado → não é filho do container escalado (Regra).

Composição com o papel do profissional de marketing

Use o papel de profissional de marketing para o texto: chamadas, manchetes e o enquadramento de valor por momento devem seguir a voz do projeto (voice.md / marketer-hooks.md de launch-feature, quando presente). Mantenha o texto na tela em uma chamada + uma manchete curta + uma sub-linha por momento.

Habilidades Relacionadas