Instalação de plugins: Antes dos comandos de configuração ou atualização, siga as regras de instalação de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar:
npx hyperframes skills update music-to-video. Uma operação rápida e sem efeitos quando tudo está atualizado; caso contrário, atualiza esta skill, além das skills de domínio principal das quais ela depende, antes que você as utilize.
music-to-video — um fluxo de trabalho de vídeo baseado em música e sincronizado com a batida
Use esta skill para transformar uma faixa musical em um vídeo HyperFrames sincronizado com a batida. Você analisa a faixa uma vez, define os quadros, preenche um plano por quadro e constrói cada quadro como uma composição. A entrada é uma faixa musical mais imagens ou vídeos opcionais do usuário — não há narração e nem captura de site. Tipografia e modelos são o piso (um vídeo completo não precisa de nenhum ativo); qualquer mídia fornecida pelo usuário é cortada na mesma grade de batidas.
Você é o orquestrador. Trabalhe em videos/<projeto>/. Execute as etapas em ordem e passe por cada Portão antes de prosseguir. Duas etapas precisam do usuário: Etapa 3 (aprovação do plano) e Etapa 6 (aprovação da renderização) — ambas são portões de checkpoint conforme ../hyperframes/references/brief-contract.md (leia-o antes da Etapa 0): no modo autônomo, publique o resumo como um aviso e prossiga em vez de esperar. Faça cada etapa você mesmo, exceto a Etapa 4, onde você despacha um subagente por quadro. Mantenha as regras de design e movimento fora deste arquivo — elas estão em references/ e no subagente frame-worker.
SKILL_DIR = diretório desta skill. PROJECT_DIR = videos/<nome-do-projeto>/.
Fluxo de trabalho: Etapa 0 configuração → hyperframes.json + assets/bgm.mp3; Etapa 1 análise → audiomap.json; Etapa 2 esqueleto → STORYBOARD.md (quadros, grupos TBD); Etapa 3 plano → STORYBOARD.md completo + frame.md; Etapa 4 construção → compositions/frames/NN-*.html; Etapa 5 montagem → index.html; Etapa 6 renderização → renders/videos.mp4.
Duas ideias que moldam tudo
- Um analisador, e você confia nele.
analyze-beatgrid.pyé o único analisador de batidas — nunca meça batidas novamente com outra ferramenta ou de ouvido. Sua energia / densidade / rolls / onsets / silêncios são sempre confiáveis. Seubpmebeats_secsão confiáveis apenas quando a música é genuinamente rítmica; em músicas calmas, a grade é um metrônomo que o rastreador impôs, então marque o ritmo por frases e energia e nunca corte bruscamente nela. Decidir em qual caso você está é opacingde cada quadro (Etapa 2). - Um quadro = um arquivo; grupos vivem dentro. A Etapa 2 corta a faixa em quadros, e cada quadro se torna um arquivo de composição
compositions/frames/NN-<frame_id>.html, construído por um frame-worker. Um quadro pode subdividir em grupos (cada um um modelo ou uma combinação de primitivas de movimento). Densidade extra vai dentro de um grupo, então a contagem de quadros rastreia tratamentos distintos, não batidas — uma faixa rápida não aumenta o número de subagentes.
Etapa 0: Configuração, BGM e entradas
Objetivo: Estabelecer a fonte de música, criar o projeto HyperFrames e anotar qualquer mídia fornecida pelo usuário.
O briefing começa na camada de intenção. Regra de abertura, em ordem: (1) BRIEF.md existe → leia-o e não pergunte nada que ele responda — seu flow/storyboard deriva o modo (brief contract § 1). (2) Sem BRIEF.md mas o projeto existe → retome do que está no disco; nunca reinterrogue. (3) Uma solicitação de criação nova que chegou aqui diretamente → leia /hyperframes e execute sua camada de intenção (references/intent-interview.md): ela confirma os itens obrigatórios desta rota (a fonte de música, destino → aspecto — ../hyperframes/references/routes/music-to-video.md) e anuncia o que fica adiado — marca e gênero são escolhidos na Etapa 3 por design. Escreva BRIEF.md imediatamente após a inicialização (nunca antes — init recusa um diretório não vazio) e registre as respostas baseadas em preferência (brief-format.md). Solicitações de edição pulam tudo isso.
A música é a espinha dorsal — estabeleça uma faixa antes de qualquer outra coisa. Esta skill é ajustada para BGM rápido e de alta energia: uma grade de batidas forte impulsiona os cortes (faixas calmas funcionam, mas marque o ritmo por frase em vez de batida). Se o usuário forneceu áudio — um arquivo de música ou um vídeo para extrair áudio — use-o. Caso contrário, escolha o humor da solicitação e gere uma faixa através de /media-use (references/bgm.md). Antes da primeira ação do provedor autenticado, execute npx hyperframes auth status e retransmita sua saída literalmente. Se desconectado, aplique uma ramificação:
- Colaborativo: aguarde o login ou uma escolha explícita para continuar offline com o provedor local.
- Autônomo: informe o status e continue através do provedor local disponível.
Se nenhum provedor offline puder satisfazer a capacidade musical necessária, exiba o bloqueador. Nunca escreva chaves em um .env por repositório. A propriedade de autenticação e fallbacks offline estão em /media-use references/setup-providers.md § Providers. A faixa resultante vai para assets/bgm.mp3. Prepare imagens ou vídeos fornecidos para que os quadros possam usá-los na grade de batidas; caso contrário, a tipografia carrega o vídeo.
Vídeos de letra: para letras sincronizadas com os vocais, obtenha o tempo de palavra/linha transcrevendo a faixa via /media-use, ou peça ao usuário o texto da letra e coloque as linhas na grade de batidas.
Inicialize apenas se hyperframes.json estiver ausente. Nomeie <projeto> a partir do briefing em kebab-case, como midnight-drive-loop — nunca um timestamp. init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
npx hyperframes init "videos/<projeto>" --non-interactive --example=blank --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<musica-do-usuario>" "$PROJECT_DIR/assets/bgm.mp3" # extraia de um vídeo primeiro, se necessário
# apenas se o usuário forneceu imagens/vídeos:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
A marca (fonte + paleta) é escolhida na Etapa 3, não aqui. Não escolha um gênero ou tipo de faixa antecipadamente — os ativos são apenas um ingrediente opcional, e o gênero emerge das escolhas por quadro.
Portão: hyperframes.json + assets/bgm.mp3 existem; aspecto / duração / fps e (se houver) o inventário de ativos são anotados.
Etapa 1: Analisar a música
Objetivo: Produzir a única análise de tempo canônica na qual todo o vídeo é construído.
analyze-beatgrid.py é o único analisador de batidas — nunca meça batidas novamente com outra ferramenta ou de ouvido. Ele lê a faixa uma vez e escreve audiomap.json: fases de energia (nível / densidade / sensação), onsets + onset_rate, rolls, silêncios, hard_stops, key_moments, frases, tempo / grade e audio.duration_sec. É determinístico — o mesmo arquivo sempre dá o mesmo mapa. A maioria dos campos é confiável em qualquer música; bpm e beats_sec são confiáveis apenas quando a música é genuinamente rítmica, e julgar isso é a decisão que você toma na Etapa 2.
Pré-requisitos: Python 3 com librosa, numpy e soundfile disponíveis. Se a importação falhar, instale-os no ambiente Python ativo antes de executar o analisador:
python3 -m pip install librosa numpy soundfile
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
Portão: audiomap.json existe; audio.duration_sec é conhecido.
Etapa 2: Esqueleto do quadro (apenas estrutura)
Objetivo: Ler a música e definir os quadros — o esqueleto de STORYBOARD.md.
Leia references/frame-skeleton.md. Transforme audiomap.json no esqueleto de STORYBOARD.md você mesmo — não há JSON intermediário. Corte a faixa em quadros em mudanças musicais reais (hard_stops, SURGE / DROP key_moments, as bordas de um roll, um trecho sem onsets, um grande salto de energia), ajustando cada limite a um âncora do audiomap. Para cada quadro, defina span_sec, pacing (o veredito da chamada de confiança da Etapa 1 — beat_cut quando a grade é real, phrase_flow quando é um metrônomo imposto em música calma), mood e uma linha de feel (a situação musical simples que a Etapa 3 corresponde a um modelo). Apenas classifique e organize aqui: deixe cada ### Groups do quadro como TBD (Step 3) e o style do frontmatter em branco — sem modelos, texto, cor ou fontes. Espere ~1–6 quadros.
Portão: os quadros cobrem a faixa (primeiro em 0, último em duration_s); cada um carrega span_sec + pacing + mood + feel; todo ### Groups é TBD; nenhum conteúdo em lugar nenhum.
Etapa 3: Preencher o plano (com portão do usuário)
Objetivo: Transformar o esqueleto em um STORYBOARD.md completo e aprovado.
Leia references/planning.md, storyboard-format.md, template-catalog.md, motion-primitive-catalog.md e montage.md (apenas se o usuário forneceu ativos). Editando o mesmo arquivo no lugar, faça duas coisas:
- Escolha a marca. Escolha um preset de
../hyperframes-creative/frame-presets/usando a tabela em../hyperframes-creative/references/design-spec.md(corresponda ao humor da faixa; apenas suas fontes e cores importam — modelos possuem composição). Copie-o paraframe.mdsem modificações e preencha ostyledo frontmatter (fonte + uma paleta de ≤4–6 amostras) a partir dele. - Preencha cada quadro. Decida seus grupos e dê a cada um um tratamento: um modelo correspondente do catálogo (com parâmetros vinculados e âncoras reais do audiomap), uma composição livre do catálogo de primitivas ou um tratamento de ativo que obedeça a
pacing. Antes de compor livremente um look nomeado, pesquise no catálogo ativo por ele: para cada look, efeito, tratamento ou transição que o usuário pediu — "CRT scanlines", "glitch", "film grain", "shimmer sweep" — executenpx hyperframes catalog --query "<o look, em inglês simples>" --jsone leia os principais resultados.template-catalog.mdemotion-primitive-catalog.mdlistam apenas os materiais locais desta skill; a pesquisa classifica todo o registro hospedado (~400 blocos e componentes) e não precisa de nada instalado — nenhum projeto, nenhumaddanterior, nenhuma conta. Componha livremente um look apenas após uma pesquisa por ele não retornar nada que se encaixe. Escreva o texto. Você é dono do O QUÊ (modelo / primitivas + conteúdo + âncoras); o frame-worker é dono do COMO — nunca escreva tweens de milissegundos no storyboard.
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
Corrija cada ✗ (erros graves: incompatibilidade de duração, quadros não cobrindo a faixa, um src ausente); avisos são de melhor esforço. Em seguida, apresente o resumo quadro a quadro no chat como uma proposta (../hyperframes/references/review-loop.md § 1) e itere nas respostas do usuário até que ele aprove; para storyboard: yes, também escreva-o como storyboard.html (../hyperframes-creative/references/storyboard-recipe.md § 3) para que ele abra. No modo autônomo, este é um portão de checkpoint: publique o resumo como um aviso e prossiga (a passagem do validate-plan.mjs é um portão de qualidade e ainda bloqueia).
Portão: frame.md é uma cópia exata do preset; validate-plan.mjs sai com 0; o usuário aprovou o plano (autônomo: o resumo foi publicado como um aviso).
Etapa 4: Construir quadros a partir do plano
Objetivo: Construir cada quadro como um arquivo de composição independente.
Crie compositions/frames/. Leia sub-agents/frame-worker.md e ../hyperframes/references/subagent-dispatch.md. Despache um frame-worker por quadro, em paralelo quando possível (caso contrário, em ondas). Cada worker recebe exatamente um quadro e este contexto:
PROJECT_DIR: <caminho absoluto>
frame_id: <NN-frame_id> # = o stem do arquivo do quadro, ex.: 02-f2; o id da composição
Seu bloco: o bloco `## Frame N — <frame_id>` em PROJECT_DIR/STORYBOARD.md
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materiais: para cada grupo, <SKILL_DIR>/references/templates/<id>/index.html (modelos) e
<SKILL_DIR>/references/motion-primitives/<id>/ (livre); ativos preparados/ (grupos de ativos)
Contratos: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <L>×<A> Pacing: <beat_cut|phrase_flow>
Escrever em: PROJECT_DIR/compositions/frames/<frame_id>.html
O worker bifurca os materiais citados, converte cada âncora para segundos locais do quadro (local_t = track_t − span_sec[0]), agrupa seus grupos com cortes de 0ms e escreve um arquivo de quadro seguro para busca. O worker nunca executa o CLI hyperframes — esses comandos operam no projeto montado, que ainda não existe, então eles relatariam os arquivos errados. O worker apenas escreve no contrato e para; você verifica após a montagem (Etapa 6). À medida que cada worker retorna, você pode confirmar que seu arquivo caiu no disco.
Portão: cada quadro tem seu compositions/frames/NN-*.html no disco.
Etapa 5: Montar
Objetivo: Conectar os quadros construídos + BGM no index.html reproduzível.
assemble-index.mjs é determinístico — sem subagente, sem julgamento. Ele referencia cada arquivo de quadro em seu data-start cumulativo, monta assets/bgm.mp3 na faixa 11 e faz cortes duros quadro → quadro (os quadros cobrem a faixa sem lacunas, então não há injetor de transição).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Corrija qualquer ✗ que ele reportar — um arquivo de quadro ausente ou em branco significa que aquele worker escreveu um arquivo parcial; redespache-o (Etapa 4) e monte novamente.
Portão: index.html existe; duração total == audiomap.audio.duration_sec.
Etapa 6: Verificar e renderizar
Objetivo: Verificar o vídeo montado, obter aprovação do usuário e renderizar o MP4 final.
Execute o CLI no projeto montado — essa é a unidade correta (os workers por quadro não podiam executá-lo). check executa lint estrutural e o tempo de execução do navegador headless, layout, áudio e verificações de saída do compositor.
cd "$PROJECT_DIR" && npx hyperframes check
Corrija quaisquer falhas. Em seguida, presente um resumo da verificação no chat e ofereça a renderização (../hyperframes/references/review-loop.md § 2). Quando o usuário aprovar (ou no modo autônomo, após publicar o resumo como aviso):
cd "$PROJECT_DIR" && npx hyperframes render
A saída vai para renders/video.mp4. Verifique se o arquivo existe e sua duração corresponde a audiomap.audio.duration_sec. Forneça o caminho absoluto e as instruções de reprodução.
Portão: renders/video.mp4 existe; duração corresponde; o usuário aprovou (autônomo: o resumo foi postado como aviso).