media-use: Antes de obter áudio/imagens, chame
/media-usepara resolver BGM/SFX/imagens do catálogo do HeyGen. Execute--adoptprimeiro para registrar ativos existentes. Veja/media-usepara detalhes.
Lançamento de Produto para HyperFrames
Use esta skill para capturar um produto, entender sua marca, planejar um vídeo de lançamento e construí-lo quadro a quadro no HyperFrames.
Confirme a rota antes do Passo 0. Você é o orquestrador. Execute cada passo, verifique seu portão e só então continue para o próximo passo. Esta skill é para um produto sendo comercializado, lançado, promovido ou revelado, incluindo solicitações como "promo para nosso site" quando o propósito é promocional. Roteie outras intenções para outro lugar: uma tour geral de site sem lançamento ->
/general-video; um explicador de tópico sem produto ->/faceless-explainer; um PR do GitHub ->/pr-to-video; legendas em filmagens existentes ->/embedded-captions; um motion graphics curto sem narração ->/motion-graphics. Se o usuário disser apenas "crie um vídeo" ou a rota for incerta, leia/hyperframesprimeiro.
Você é o orquestrador. Trabalhe em videos/<projeto>/. Execute os passos em ordem e passe cada portão antes de continuar. Os passos com portão de usuário são Passo 0, Passo 3 e Passo 6. Faça cada passo você mesmo, exceto o Passo 5, onde você despacha um sub-agente por quadro. Não coloque regras de design ou movimento aqui; elas residem no sub-agente frame-worker, nas regras e blueprints locais (../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/) e no hyperframes-creative.
Fluxo de trabalho: Passo 0 setup -> hyperframes.json; Passo 1 captura -> capture/; Passo 2 sistema de design -> frame.md; Passo 3 storyboard/roteiro -> STORYBOARD.md e SCRIPT.md; Passo 3.1 áudio -> audio_meta.json; Passo 4 design visual -> STORYBOARD.md enriquecido; Passo 5 quadros -> compositions/frames/NN-*.html e index.html; Passo 6 renderização final -> renders/video.mp4.
Passo 0: Configuração e Briefing
Objetivo: Definir o briefing central do vídeo e criar o projeto HyperFrames, se necessário.
Inicialize apenas se hyperframes.json estiver faltando. Nomeie <projeto> a partir da marca ou domínio em kebab-case, como acme-promo; nunca use nome do workspace ou timestamp.
npx hyperframes init "videos/<projeto>" --non-interactive --example=blank — init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
Mostre o status de login antes do briefing — execute npx hyperframes auth status e transmita sua saída literalmente (não parafraseie ou reescreva). Ele informa se a voz/BGM usará HeyGen ou mecanismos locais e, quando não estiver logado, como fazer login. Se não estiver logado, PARE e aguarde a escolha do usuário — fazer login, ou dizer "vá"/"offline" para continuar com mecanismos locais — antes de perguntar o briefing ou qualquer outra coisa. Trate como um ponto de decisão real, não uma nota passageira; não coloque a escolha na pergunta do briefing, e não escreva chaves em um .env por repositório. (No modo autônomo, anote o status e continue offline.) Veja ../hyperframes-media → Pré-voo para a orientação canônica.
Portão: hyperframes.json existe, e ângulo, duração, proporção de tela e idioma estão definidos; o status de login foi mostrado (logado, ou continuando offline).
Passo 1: Capturar ativos
Objetivo: Coletar o material de origem, sinais da marca e ativos utilizáveis para o vídeo.
Classifique a entrada e escolha o caminho. URL explícita -> capture-a e use o site para narração e ativos. Script/briefing colado -> salve literalmente como user_script.txt, pergunte uma vez "usar literalmente ou reestruturar?", armazene a resposta como VO_MODE, depois resolva o alvo da captura: URL no texto -> use-a; apenas nome da marca -> WebSearch, confirme a URL em uma linha, depois rastreie; sem URL/site -> caminho sem captura.
Execute a captura com: npx hyperframes capture "<URL>" -o ./capture
Se GEMINI_API_KEY, GOOGLE_API_KEY ou uma chave OpenRouter existir, a captura legenda automaticamente os ativos em capture/extracted/asset-descriptions.md. Isso não é um portão de revisão. Sem uma chave de visão, use o contexto DOM e continue.
Caminho sem captura: crie capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/asset-descriptions.md e capture/assets/ manualmente. tokens.json deve ser { "title": "", "description": "", "colors": [], "fonts": [] }; preencha título/descrição a partir do briefing quando possível. visible-text.txt contém o briefing ou script completo. asset-descriptions.md deve dizer que nenhum ativo foi capturado, a menos que o usuário tenha dado notas sobre ativos.
Portão: capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/asset-descriptions.md e capture/assets/ existem; você pode declarar a marca em uma frase clara. Trate asset-descriptions.md como o inventário principal de ativos. Se ele estiver faltando após uma captura real, pare e reporte a captura incompleta. Se capture/BLOCKED.md existir, siga-o.
Passo 2: Sistema de Design
Objetivo: Escolher um preset de quadro fornecido; um script o transforma no frame.md deste vídeo + skin de legenda.
Você faz a única chamada de julgamento — qual preset. Leia ../hyperframes-creative/references/design-spec.md e escolha o preset cuja aparência melhor se adapte à marca e ao briefing. Depois execute:
node <SKILL_DIR>/scripts/build-frame.mjs --preset <nome> --hyperframes .
O script faz o resto deterministicamente: copia o FRAME.md do preset → frame.md e remixa com os tokens da marca em capture/extracted/tokens.json (cores da marca mapeadas nas chaves de cor do preset por função — tinta, tela, acentos — mantendo chaves/estrutura/componentes; as fontes de exibição + corpo do preset substituídas pelas da marca), copia a skin de legenda do preset para .hyperframes/caption-skin.html e auto-valida (sai com 1 em mapeamento quebrado). Prossiga para o próximo passo assim que ele sair com 0 — sem edição manual da especificação.
tokens.json sem cores/fontes da marca (ex.: sem captura) → o script mantém a paleta do preset, um design completo e enviável. Se o briefing nomear cores/fontes da marca que a captura perdeu, adicione-as a capture/extracted/tokens.json antes de executar (ou use o design.md do usuário para preenchê-lo); só ajuste frame.md manualmente depois se um mapeamento realmente precisar.
Portão: build-frame.mjs saiu com 0 — frame.md existe a partir de um preset nomeado, e (quando o preset fornece um) .hyperframes/caption-skin.html existe como a fonte da skin de legenda.
Passo 3: Storyboard e Roteiro
Objetivo: Transformar o briefing e o material capturado em um plano de história quadro a quadro aprovado.
Leia references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes-core/references/storyboard-format.md e ../hyperframes-core/references/script-format.md. Use-os para escrever STORYBOARD.md e, quando a narração for necessária, SCRIPT.md.
Use story-design.md para o blueprint da história, gancho, lógica de persuasão, batidas, VO_MODE e escolhas de ativos. Como um guia suave, consulte o menu de papel→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, anote um id de blueprint candidato quando um se encaixar. A verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em um blueprint, e nunca invente uma batida apenas porque uma forma comprovada está disponível. Escolha os asset_candidates de cada quadro visual de capture/extracted/asset-descriptions.md (o inventário canônico) — não navegue pelos capture/assets/ brutos. Não peça ao usuário para escolher ativos a menos que esse inventário esteja faltando ou inutilizável. Use os campos exatos exigidos das referências de storyboard e roteiro.
Após o rascunho, mostre um resumo quadro a quadro. Nessa mesma mensagem, pergunte duas coisas ao usuário: (a) aprovar ou solicitar alterações, e (b) se ele deseja uma prévia ao vivo do esqueleto do storyboard (npx hyperframes preview) — abra-a apenas se a resposta for sim. Itere até a aprovação e leve a escolha de prévia para o Passo 6.
Portão: STORYBOARD.md existe, cada quadro visual tem asset_candidates, SCRIPT.md existe quando a narração é necessária, e o usuário aprovou o plano quadro a quadro.
Passo 3.1: Áudio
Objetivo: Gerar narração, tempos de palavras, música e metadados de áudio a partir do roteiro aprovado.
Inicie o áudio após a aprovação do Passo 3. Execute-o em segundo plano e depois continue para o Passo 4.
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
O script de áudio lida com narração, tempos de palavras, consulta de BGM na biblioteca de música do HeyGen e metadados de timing. O mood do BGM vem do campo music: do storyboard. Isso usa a API de Áudio do HeyGen para recuperação, não geração, e usa a mesma credencial ~/.heygen do TTS. Para detalhes do provedor, leia ../hyperframes-media/references/tts.md.
Se não houver narração e nenhum SCRIPT.md, pule a geração de voz. O BGM ainda pode ser executado se o storyboard tiver um mood musical.
Portão: o job de áudio foi iniciado, ou o projeto está marcado como silencioso.
Passo 4: Design Visual do Quadro
Objetivo: Adicionar a direção visual, intenção de layout e escolhas de movimento a cada quadro do storyboard.
Edite STORYBOARD.md no local. Não crie outro storyboard. Use frame.md como fonte da verdade para cor, tipo, sensação de layout e estilo.
Leia references/visual-design.md, ../hyperframes-animation/blueprints-index.md, references/motion-language.md e ../hyperframes-animation/rules-index.md. Use visual-design.md para o método (a sequência de cenas codificadas por tempo, o vocabulário de Layout inline e o bloco ## Video direction obrigatório). Use ../hyperframes-animation/blueprints-index.md para escolher a forma de cada quadro. Use motion-language.md (o vocabulário de movimento + a doutrina de movimento) e ../hyperframes-animation/rules-index.md (nomes de regras válidos) para movimento — não invente nomes de movimento.
Para cada quadro visual, escreva uma sequência de cenas codificadas por tempo em STORYBOARD.md de acordo com o método de visual-design.md: escolha o blueprint do quadro (ou componha), instancie-o com o conteúdo DESTE produto e ritme a revelação de cada Cena na narração para que o quadro se desenvolva em toda a sua duração em vez de carregar tudo no início e depois congelar. Declare layout e movimento inline por Cena (vocabulários em visual-design.md e motion-language.md). Adicione um bloco ## Video direction para todo o vídeo.
Não mude história, roteiro, escolhas de ativos, asset_candidates, transition_in ou material de origem capturado. Não escreva HTML neste passo.
Prepare os ativos nomeados após o design visual estar definido:
node <SKILL_DIR>/scripts/stage-assets.mjs --storyboard ./STORYBOARD.md --hyperframes .
Portão: cada quadro visual tem uma sequência de cenas codificada por tempo cujas revelações são ritmadas na narração (sem carregamento frontal); ## Video direction existe; assets/ contém os ativos nomeados.
Passo 5: Construir Quadros
Objetivo: Construir cada quadro do storyboard como uma composição HTML e montar o vídeo reproduzível.
Aguarde o áudio do Passo 3.1 terminar se o áudio foi iniciado. Em seguida, sincronize as durações e busque SFX; pule ambos se for silencioso.
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
A sincronização de duração é mecânica: a duração real da voz vence; quadros silenciosos mantêm estimativas; nunca edite manualmente as durações sincronizadas.
Antes de despachar, leia sub-agents/frame-worker.md e ../hyperframes-core/references/subagent-dispatch.md. Despache um sub-agente por quadro, em paralelo se possível; caso contrário, execute workers em ondas. Cada worker recebe exatamente um quadro.
O contexto de cada worker deve incluir PROJECT_DIR, frame_id, tamanho da tela, status de legenda e faixa de exclusão se as legendas estiverem ativadas, e RULES_DIR como o caminho absoluto para ../hyperframes-animation/rules/ desta skill. Cada worker lê frame.md, seu próprio bloco ## Frame N de STORYBOARD.md, a receita de regra local (../hyperframes-animation/rules/<id>.md) para cada movimento citado e o template do blueprint do quadro (../hyperframes-animation/blueprints/<id>.md). Cada worker escreve apenas compositions/frames/NN-*.html. Os workers nunca devem editar STORYBOARD.md.
À medida que cada worker retorna, o orquestrador marca esse quadro como animated em STORYBOARD.md.
Após os timings de áudio existirem, construa legendas em segundo plano e monte o índice:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs usa o .hyperframes/caption-skin.html do projeto (copiado no Passo 2) como a aparência da legenda, injetando tokens da marca de frame.md; sem skin presente, ele renderiza a pílula padrão embutida. captions: skipped (<motivo>) é válido. Continue sem legendas quando explicitamente pulado.
Portão: cada quadro está marcado como animated, index.html existe e as legendas estão construídas ou explicitamente puladas.
Passo 6: Finalizar
Objetivo: Verificar o vídeo montado, obter aprovação do usuário e renderizar o MP4 final.
Injete transições, execute verificações, pause para revisão e depois renderize.
node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
npx hyperframes snapshot --at <frame-midpoints>
snapshot costura os quadros capturados em uma folha de contato (snapshots/contact-sheet.jpg). Dê uma olhada rápida; se nada estiver obviamente quebrado, prossiga — não se demore aqui.
Se um comando falhar, mostre o stderr e pare — não empilhe comandos de recuperação. Corrija você mesmo: a edição segura mais barata em compositions/frames/NN-*.html, depois reexecute a verificação falhada.
Após as verificações passarem, pause para revisão do usuário. O vídeo está montado, visualizável e editável no Studio. Gerencie a prévia apenas uma vez entre o Passo 3 e o Passo 6: abra-a se o usuário pediu antes, ofereça-a se ele recusou antes, e não pergunte novamente se ele já estiver revisando no Studio.
Prévia: npx hyperframes preview
Renderize apenas com a resposta 'sim' do usuário e forneça o out ou deixe o padrão (renders/). O nome do arquivo deve ser descritivo, como acme-pilot-launch.mp4.
node <SKILL_DIR>/scripts/render.mjs --hyperframes . --out renders/<arquivo>.mp4
O progresso da renderização e o caminho de saída são relatados pelo comando. Não há mais portões após a conclusão da renderização — termine e sugira o próximo passo, como postagem no /social ou /upload para a nuvem.
Portão: o usuário aprovou a prévia e o MP4 foi renderizado.