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 sem efeito quando tudo está atualizado; caso contrário, ela atualiza esta skill e as skills principais das quais ela depende antes que você as utilize.
music-to-video — um fluxo de trabalho de vídeo sincronizado com batida baseado em música
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 (frames), 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 a base (um vídeo completo não precisa de nenhum ativo); qualquer mídia que o usuário fornecer é cortada na mesma grade de batidas.
Você é o orquestrador. Trabalhe em videos/<projeto>/. Execute as etapas em ordem e passe por cada Portão (Gate) antes de prosseguir. Duas etapas precisam do usuário: Etapa 3 (aprovação do plano) e Etapa 6 (aprovação da renderização) — ambos são portões de verificação de acordo com ../hyperframes/references/brief-contract.md (leia antes da Etapa 0): no modo autônomo, publique o resumo da Etapa 3 como um aviso e prossiga; a aprovação da renderização da Etapa 6 ainda é solicitada, como a única pergunta mantida. Faça você mesmo cada etapa, 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 compilação → compositions/frames/NN-*.html; Etapa 5 montagem → index.html; Etapa 6 renderização → renders/video.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 / rolagens / inícios / silêncios são sempre confiáveis. Seusbpmebeats_secsão confiáveis apenas quando a música é genuinamente rítmica; em música calma a grade é um metrônomo que o rastreador impôs, então marque o ritmo por frases e energia em vez disso e nunca corte bruscamente nela. Decidir em qual caso você está é apacingde cada quadro (Etapa 2). - Um quadro = um arquivo; grupos vivem dentro. A Etapa 2 divide a faixa em quadros (frames), e cada quadro se torna um arquivo de composição
compositions/frames/NN-<id_do_quadro>.html, construído por um frame-worker. Um quadro pode subdividir-se 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 derivam 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 requisitos 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 a partir da solicitação e gere uma faixa através de /media-use (audio/references/bgm.md). Antes da primeira ação autenticada do provedor, execute npx hyperframes auth status e retransmita sua saída literalmente. Se desconectado, aplique um ramo:
- 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, apresente 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 § Provedores. A faixa resultante vai para assets/bgm.mp3. Organize 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 com letra: para letras sincronizadas com os vocais, obtenha o tempo das palavras/linhas 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 faltando. 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 lhe deu 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 um tipo de faixa antecipadamente — 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 temporização 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), inícios + onset_rate, rolagens, 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 dos quadros (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. Divida a faixa em quadros (frames) nas mudanças musicais reais (hard_stops, SURGE / DROP key_moments, as bordas de uma rolagem, um trecho sem inícios, um grande salto de energia), encaixando cada limite em 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 feel de uma linha (a situação musical simples que a Etapa 3 combina com um modelo). Apenas classifique e defina aqui: deixe cada ### Groups do quadro como TBD (Etapa 3) e o style do frontmatter em branco — sem modelos, cópia, 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 algum.
Etapa 3: Preencher o plano (com aprovação do usuário)
Objetivo: Transformar o esqueleto em um STORYBOARD.md aprovado e completo.
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. Selecione um preset de
../hyperframes-creative/frame-presets/usando a tabela em../hyperframes-creative/references/design-spec.md(combine com o humor da faixa; apenas suas fontes e cores importam — os modelos são donos da composição). Copie-o emframe.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 obedece a
pacing. Antes de compor livremente um visual nomeado, pesquise no catálogo ativo por ele: para cada visual, efeito, tratamento ou transição que o usuário pediu — "linhas de varredura CRT", "glitch", "grão de filme", "varredura brilhante" — executenpx hyperframes catalog --query "<o visual, 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 — sem projeto, semaddanterior, sem conta. Componha livremente um visual apenas depois que uma pesquisa por ele não retornar nada que se encaixe. Escreva a cópia. Você é dono do QUE (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, uma src faltando); avisos são melhor esforço. Em seguida, apresente o resumo quadro a quadro no chat como uma proposta (../hyperframes/references/review-loop.md § 1) e itere sobre as respostas do usuário até que ele aprove; para storyboard: yes, também escreva como storyboard.html (../hyperframes-creative/references/storyboard-recipe.md § 3) para ele abrir. No modo autônomo, este é um portão de verificação: 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 literal do preset; validate-plan.mjs sai com código 0; o usuário aprovou o plano (autônomo: o resumo foi postado como um aviso).
Etapa 4: Construir quadros a partir do plano
Objetivo: Construir cada quadro como um arquivo de composição autônomo.
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 trabalhador recebe exatamente um quadro e este contexto:
PROJECT_DIR: <caminho absoluto>
frame_id: <NN-id_do_quadro> # = o nome do arquivo do quadro, ex. 02-f2; o id da composição
Seu bloco: o bloco `## Quadro N — <id_do_quadro>` 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 organizados/ (grupos de ativos)
Contratos: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Tela: <l>×<a> Ritmo: <beat_cut|phrase_flow>
Escrever em: PROJECT_DIR/compositions/frames/<id_do_quadro>.html
O trabalhador bifurca os materiais citados, converte cada âncora em segundos locais do quadro (local_t = track_t − span_sec[0]), cerca seus grupos com cortes de 0ms e escreve um arquivo de quadro seguro para busca. O trabalhador nunca executa o CLI hyperframes — esses comandos operam no projeto montado, que ainda não existe, então eles reportariam os arquivos errados. O trabalhador apenas escreve no contrato e para; você verifica após a montagem (Etapa 6). À medida que cada trabalhador retorna, você pode confirmar que seu arquivo está 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 secos 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 faltando ou em branco significa que aquele trabalhador 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 trabalhadores por quadro não puderam executá-lo). check executa verificações de integridade: nenhum arquivo de quadro solto, tempos de início corretos, todas as referências de ativos resolvidas, a animação de áudio é válida. Então renderize:
cd "$PROJECT_DIR"
npx hyperframes render --output renders/video.mp4
Mostre o resumo da renderização: duração, resolução, taxa de quadros. Peça aprovação do usuário (portão de verificação). No modo autônomo, este portão é a única pergunta mantida: pergunte ao usuário se pode renderizar; se não houver resposta em 30s, cancele e informe o status.
Portão: renders/video.mp4 existe; o usuário aprovou a saída.
Referências desta skill
references/frame-skeleton.md— regras e intuição para o esqueletoreferences/planning.md— como escolher modelos, primitivas e marcareferences/storyboard-format.md— a estrutura YAML + markdownreferences/template-catalog.md— modelos disponíveis locaisreferences/motion-primitive-catalog.md— primitivas de movimento disponíveis locaisreferences/montage.md— tratamento de ativos do usuáriosub-agents/frame-worker.md— contrato e contexto do trabalhador de quadro
Resumo do fluxo de trabalho
| Etapa | Ação | Saída | Portão? |
|---|---|---|---|
| 0 | Configurar projeto, BGM, ativos | hyperframes.json, assets/bgm.mp3, public/ | sim |
| 1 | Analisar música | audiomap.json | sim |
| 2 | Esqueleto dos quadros | STORYBOARD.md (TBDs) | sim |
| 3 | Plano completo + marca | STORYBOARD.md completo, frame.md | usuário (autônomo: aviso) |
| 4 | Compilar quadros | compositions/frames/NN-*.html | sim |
| 5 | Montar | index.html | sim |
| 6 | Verificar, renderizar | renders/video.mp4 | usuário (pergunta mantida) |