música-para-vídeo — um fluxo de trabalho de vídeo sincronizado com a batida e baseado na 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, organiza 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 a base (um vídeo completo não precisa de nenhum ativo); qualquer mídia fornecida pelo usuário é inserida 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). Faça tudo sozinho, exceto a Etapa 4, onde você despacha um subagente por quadro. Mantenha as regras de design e movimento fora deste arquivo — elas ficam em references/ e no subagente frame-worker.
SKILL_DIR = este diretório da 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/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 / ataques / 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 adapte-se pelas frases e energia e nunca faça cortes duros nela. Decidir em qual caso você está é opacingde cada quadro (Etapa 2). - Um quadro = um arquivo; grupos vivem dentro dele. 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 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 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.
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 adapte-se pela frase em vez da batida). Se o usuário forneceu áudio — um arquivo de música ou um vídeo para extrair o áudio — use-o. Se não, gere um: escolha o humor da descrição do usuário (por exemplo, "synthwave intenso", "batida trap", "corporativo animado") e produza uma faixa via /hyperframes-media (references/bgm.md — recuperação HeyGen quando credenciado, senão Lyria local / MusicGen; ElevenLabs ou outro gerador também funciona). Antes de gerar, execute npx hyperframes auth status e transmita sua saída literalmente (não parafraseie ou reescreva) — ela mostra se o BGM vem do HeyGen ou do MusicGen local e, se não estiver conectado, como conectar-se. Se não estiver conectado, PARE e aguarde o usuário escolher — conectar-se ou continuar offline com MusicGen local — antes de gerar a faixa; não escreva chaves em um .env por repositório. (No modo autônomo, anote o status e continue offline). Veja /hyperframes-media → Preflight para a orientação canônica. De qualquer forma, a faixa termina em assets/bgm.mp3. Prepare quaisquer imagens ou vídeos fornecidos pelo usuário para que os quadros possam incorporá-los na grade de batidas; caso contrário, a tipografia carrega todo o vídeo.
Inicialize apenas se hyperframes.json estiver faltando. Nomeie <projeto> a partir do resumo 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
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), ataques + onset_rate, rolagens, silêncios, hard_stops, key_moments, frases, andamento / 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 organizar os quadros — o esqueleto de STORYBOARD.md.
Leia references/frame-skeleton.md. Converta 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 um âncora do mapa de áudio. 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 combina com um modelo). Apenas classifique e organize aqui: deixe cada ### Grupos do quadro como TBD (Etapa 3) e o style do frontmatter em branco — sem modelos, texto, cor ou fontes. Espere cerca de 1 a 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 qualquer lugar.
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 — modelos possuem composição). Copie-o paraframe.mdsem modificações e preencha o frontmatterstyle(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 mapa de áudio), uma composição livre do catálogo de primitivas ou um tratamento de ativo que obedeça ao
pacing. Escreva o texto. Você possui O QUE (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, uma src ausente); avisos são de melhor esforço. Em seguida, mostre ao usuário um resumo quadro a quadro e itere até que ele aprove.
Portão: frame.md é uma cópia literal do preset; validate-plan.mjs sai com 0; o usuário aprovou o plano.
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-core/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-frame_id> # = a raiz 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); 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 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 os arquivos errados. O trabalhador apenas escreve no contrato e para; você verifica após a montagem (Etapa 6). Conforme 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 jogá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 de quadro para 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 podiam executá-lo). lint verifica a estrutura, validate executa Chrome headless (capturando erros de JS e ativos ausentes), inspect tira instantâneos dos quadros.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
Inspecione em t=0, cada início de quadro, o DROP / SURGE mais forte, cada hard_stops[].t e o quadro final. Em caso de falha, faça a correção segura mais barata você mesmo: edite o compositions/frames/NN-*.html ofensivo. Nunca mude a duração ou o tempo do áudio para esconder um problema de sincronia. Assim que os portões passarem, pause para revisão do usuário, então renderize apenas após aprovação:
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
Portão: lint / validate / inspect passaram; o usuário aprovou; renders/video.mp4 existe com áudio, duração == audiomap.audio.duration_sec. A resposta final informa o caminho do MP4 e a duração.
Tabela de retomada
| Você tem | Continue de |
|---|---|
Apenas assets/bgm.mp3 | Etapa 1 |
audiomap.json | Etapa 2 |
STORYBOARD.md (esqueleto) | Etapa 3 |
STORYBOARD.md (completo) | Etapa 4 |
| todos os arquivos de quadro | Etapa 5 |
index.html | Etapa 6 |
Referência rápida
Formatos: paisagem 1920x1080 por padrão; retrato 1080x1920; quadrado 1080x1080. Defina o canvas uma vez no frontmatter do storyboard (canvas: { w, h, fps }).
Scripts em scripts/: analyze-beatgrid.py (o único analisador), validate-plan.mjs (verificação do plano), assemble-index.mjs (montagem do índice), stage-assets.mjs (preparação de mídia do usuário), lib/storyboard.mjs (analisador fornecido). Todo o resto é o CLI hyperframes.
| Leia | Quando |
|---|---|
references/frame-skeleton.md | Etapa 2: ler a música, organizar os quadros, definir pacing |
references/planning.md · storyboard-format.md | Etapa 3: escolher a marca, preencher cada quadro, escrever o plano |
references/template-catalog.md | Etapa 3: escolher um modelo por grupo |
references/motion-primitive-catalog.md | Etapa 3: escolher uma composição livre por grupo |
references/montage.md | Etapa 3: quando o usuário fornecer ativos de mídia |
../hyperframes-creative/references/design-spec.md | Etapa 3: escolher um preset de marca |
sub-agents/frame-worker.md | Etapa 4: construir cada quadro |
../hyperframes-core/references/sub-compositions.md | Etapa 4: contrato de composição |
../hyperframes-core/references/determinism-rules.md | Etapa 4: regras de determinismo |
../hyperframes-core/references/subagent-dispatch.md | Etapa 4: despacho do subagente |