Instalações de plugins: Antes dos comandos de configuração ou atualização, siga as regras de execução de plugins quando esta habilidade estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
Primeiro, mantenha esta habilidade 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 habilidade mais as habilidades do domínio principal das quais ela depende, antes de você confiar nelas.
music-to-video — um fluxo de trabalho de vídeo sincronizado com a batida, baseado em música
Use esta habilidade 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 de música 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) — ambos são portões de verificação por ../hyperframes/references/brief-contract.md (leia-o 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 = este diretório de habilidade. 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 → completa STORYBOARD.md + 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 remeça batidas com outra ferramenta ou de ouvido. Sua energia / densidade / rolagens / ataques / silêncios são sempre confiáveis. Seubpmebeats_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 e nunca corte duro 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-<id_do_quadro>.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 explode 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 deriva o modo (contrato de briefing § 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 permanece 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 habilidade é ajustada para BGM rápido e de alta energia: uma grade de batidas forte impulsiona os cortes (faixas calmas funcionam, mas marque o ritmo pela frase em vez da 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 (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 uma ramificação:
- Colaborativo: aguarde o login ou uma escolha explícita de 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, exponha o bloqueador. Nunca escreva chaves em um .env por repositório. Propriedade de autenticação e fallbacks offline vivem em /media-use references/setup-providers.md § Provedores. A faixa resultante termina em 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 líricos: 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 habilidades instaladas em relação às últimas 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 um 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 remeça batidas com outra ferramenta ou de ouvido. Ele lê a faixa uma vez e escreve audiomap.json: fases de energia (nível / densidade / sensação), ataques + 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 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 nas mudanças musicais reais (hard_stops, SURGE / DROP key_moments, as bordas de uma rolagem, um trecho sem ataques, um grande salto de energia), encaixando cada limite em uma â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 um feel de uma linha (a situação musical simples que a Etapa 3 corresponde a um modelo). Apenas classifique e defina aqui: deixe cada ### Grupos 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; cada ### Grupos é 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 visual nomeado, pesquise o catálogo ao vivo por ele: para cada visual, efeito, tratamento ou transição que o usuário pediu — "CRT scanlines", "glitch", "film grain", "shimmer sweep" — 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 habilidade; 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 retornou nada que se encaixe. Escreva a cópia. Você possui O QUÊ (modelo / primitivas + conteúdo + âncoras); o frame-worker possui 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 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 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 trabalhador recebe exatamente um quadro e este contexto:
PROJECT_DIR: <caminho_abs>
frame_id: <NN-frame_id> # = a base do nome do arquivo do quadro, ex.: 02-f2; o id da composição
Seu bloco: o bloco `## Quadro 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); assets/ preparados (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/<frame_id>.html
O trabalhador bifurca os materiais citados, converte cada âncora para segundos locais do quadro (local_t = track_t − span_sec[0]), controla 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 nos 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 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 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 ausente 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 um conjunto de verificações e relata a prontidão para renderização. Em seguida, faça o build ou renderize.
cd "$PROJECT_DIR"
npx hyperframes check && npx hyperframes render
Se check falhar, corrija os problemas relatados (comum: caminhos de arquivos de quadro não resolvidos, trabalhadores que não seguiram contratos). Reconstrua/remonte conforme necessário.
Após a renderização, apresente o resultado ao usuário (../hyperframes/references/review-loop.md § 2): compartilhe o caminho do arquivo e um resumo de uma linha, e solicite aprovação (render: yes/render: no). No modo autônomo, isso é o portão de verificação final: menos de 2 minutos de renderização é imediato; mais de 2 minutos, publique a prévia como um aviso e continue (a renderização é o resultado final, e o tempo de espera é dominado pelo navegador cabeça, não por você).
Portão: renders/video.mp4 existe; usuário disse render: yes (autônomo: prévia publicada; o arquivo é a saída final).
Resumo dos Portões
| Etapa | Portão | Responsabilidade |
|---|---|---|
| 0 | hyperframes.json + assets/bgm.mp3 existem; aspect, duração, fps anotados | Configuração e preparação de ativos |
| 1 | audiomap.json existe; audio.duration_sec conhecido | Análise de música, um analisador |
| 2 | Quadros cobrem a faixa; cada um tem span_sec, pacing, mood, feel; Grupos TBD | Esqueleto estrutural sem conteúdo |
| 3 | frame.md é cópia do preset; plano validado; usuário aprovou | Preenchimento de plano com aprovação do usuário |
| 4 | Cada quadro tem compositions/frames/NN-*.html no disco | Construção de composição (por subagente) |
| 5 | index.html existe; duração total corresponde | Montagem e fiação |
| 6 | renders/video.mp4 existe; usuário aprovou (render: yes) | Renderização final e verificação |