Instalação de plugins: Antes de executar 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, atualiza esta skill e as skills de domínio principais das quais ela depende, antes de você depender delas.
music-to-video — um fluxo de trabalho de vídeo sincronizado com a batida e 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 frames, preenche um plano por frame e constrói cada frame 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 sites. Tipografia e modelos são a base (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 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) — ambos são portões de verificação conforme ../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. Execute você mesmo todas as etapas, exceto a Etapa 4, onde você despacha um subagente por frame. 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 (frames, 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/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 / rolls / onsets / silêncios são sempre confiáveis. Seusbpmebeats_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 rigidamente nela. Decidir em qual caso você está é opacingde cada frame (Etapa 2). - Um frame = um arquivo; grupos vivem dentro dele. A Etapa 2 divide a faixa em frames, e cada frame se torna um arquivo de composição
compositions/frames/NN-<frame_id>.html, construído por um frame-worker. Um frame pode ser subdividido 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 frames reflete 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 e não pergunte nada que ele responda — seu flow/storyboard derivam o modo (brief contract § 1). (2) Não há 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 com base nas preferências (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 BGMs rápidos 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); quando o aplicativo host fornecer sua própria ferramenta de música, use-a. Antes da primeira ação autenticada do provedor, 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, sinalize o bloqueador. Nunca escreva chaves em um .env por repositório. A propriedade da autenticação e as alternativas offline estão em /media-use references/setup-providers.md § Providers. A faixa resultante é salva em assets/bgm.mp3. Prepare imagens ou vídeos fornecidos para que os frames possam usá-los na grade de batidas; caso contrário, a tipografia carrega o vídeo.
Videoclipes 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 com as 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 frame.
Portão: hyperframes.json + assets/bgm.mp3 existem; aspecto / duração / fps e (se houver) o inventário de ativos estã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 dos frames (apenas estrutura)
Objetivo: Ler a música e definir os frames — 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 frames nas 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 frame, 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 combina com um modelo). Classifique e defina apenas aqui: deixe ### Groups de cada frame como TBD (Step 3) e o style do frontmatter em branco — sem modelos, cópia, cor ou fontes. Espere cerca de 1–6 frames.
Portão: os frames 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(combine com o humor da faixa; apenas suas fontes e cores importam — os modelos são responsáveis pela composição). Copie-o emframe.mdsem modificações e preencha ostyledo frontmatter (fonte + uma paleta de ≤4–6 amostras) a partir dele. - Preencha cada frame. 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 ao
pacing. Antes de compor livremente um visual nomeado, pesquise no catálogo ao vivo por ele: para cada visual, efeito, tratamento ou transição que o usuário pediu — "scanlines 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 — nenhum projeto, nenhumaddanterior, nenhuma conta. Componha livremente um visual apenas depois que uma pesquisa por ele não retornar nada que se encaixe. Escreva a cópia. Você é responsável pelo O QUÊ (modelo / primitivas + conteúdo + âncoras); o frame-worker é responsável pelo 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, frames não cobrindo a faixa, um src ausente); avisos são de melhor esforço. Em seguida, apresente o resumo frame a frame 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 como storyboard.html (../hyperframes-creative/references/storyboard-recipe.md § 3) para que ele abra. 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 0; o usuário aprovou o plano (autônomo: o resumo foi publicado como um aviso).
Etapa 4: Construir frames a partir do plano
Objetivo: Construir cada frame 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 frame, em paralelo quando possível (caso contrário, em ondas). Cada worker recebe exatamente um frame e este contexto:
PROJECT_DIR: <caminho absoluto>
frame_id: <NN-frame_id> # = a haste do arquivo do frame, 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: <w>×<h> 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 frame (local_t = track_t − span_sec[0]), fecha seus grupos com cortes de 0ms e escreve um arquivo de frame seguro para busca. O worker nunca executa a 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). Conforme cada worker retorna, você pode confirmar que seu arquivo foi salvo no disco.
Portão: cada frame tem seu compositions/frames/NN-*.html no disco.
Etapa 5: Montar
Objetivo: Conectar os frames construídos + BGM no index.html reproduzível.
assemble-index.mjs é determinístico — sem subagente, sem julgamento. Ele referencia cada arquivo de frame em seu data-start cumulativo, monta assets/bgm.mp3 na faixa 11 e faz cortes secos de frame para frame (os frames 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 relatar — um arquivo de frame 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 a CLI no projeto montado — essa é a unidade correta...