Communitygithub.com

Army161/OpenMontage

Use quando o usuário tem uma faixa de música (um arquivo de áudio ou um vídeo do qual extrair áudio) e deseja um vídeo HyperFrames sincronizado com a batida, do calmo ao intenso. A música rege tudo: um analisador a lê uma vez, o orquestrador define os quadros e preenche um plano por quadro, e um subagente constrói cada quadro. Tipografia e templates são a base — um vídeo completo não precisa de nenhum ativo —, mas quaisquer imagens ou vídeos fornecidos pelo usuário são inseridos nos quadros na mesma grade de batidas (corte na batida/ken-burns). O gênero (videoclipe lírico, apresentação de slides, promo cinético) surge das escolhas por quadro; o pipeline nunca ramifica com base nele.

O que é OpenMontage?

O Army161/OpenMontage é uma habilidade especializada para agentes de IA que transforma uma faixa de música em um vídeo HyperFrames totalmente sincronizado com a batida, sem necessidade de narração ou captura de sites. O fluxo de trabalho é orquestrado centralmente: um único analisador de batidas (analyze-beatgrid.py) processa a música uma vez para gerar um mapa de áudio preciso, que guia a criação de uma estrutura de storyboard. Cada quadro do vídeo é então construído por um subagente independente (frame-worker), que segue o plano definido pelo orquestrador, usando templates tipográficos ou primitivas de movimento, e integrando qualquer mídia fornecida pelo usuário (imagens ou vídeos) na mesma grade de batidas. A habilidade suporta as plataformas HyperFrames e é ideal para criar lyric videos, apresentações de slides, promos cinéticos e muito mais, onde a música é o elemento central e condutor. O processo é altamente modular e determinístico, garantindo consistência e qualidade, e inclui etapas de aprovação do usuário para o plano e a renderização final.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Army161/OpenMontage/tree/HEAD/.agents/skills/music-to-video

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

música-para-vídeo — um fluxo de trabalho de vídeo sincronizado com a batida, guiado pela música

Use esta habilidade para transformar uma faixa de música 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 fornecidos pelo usuário — não há narração nem captura de site. Tipografia e templates 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 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 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 = este diretório da habilidade. PROJECT_DIR = videos/<nome-do-projeto>/.

Fluxo de trabalho: Etapa 0 configuração → hyperframes.json + assets/bgm.mp3; Etapa 1 analisar → audiomap.json; Etapa 2 esqueleto → STORYBOARD.md (quadros, grupos TBD); Etapa 3 plano → STORYBOARD.md completo + frame.md; Etapa 4 construir → compositions/frames/NN-*.html; Etapa 5 montar → index.html; Etapa 6 renderizar → 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 / rolls / onsets / silêncios são sempre confiáveis. Seu bpm e beats_sec sã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 bruscamente nela. Decidir em qual caso você está é o pacing de cada quadro (Etapa 2).
  • Um quadro = um arquivo; grupos vivem dentro dele. A Etapa 2 divide 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-se em grupos (cada um é um template ou uma combinação de primitivas de movimento). Densidade extra vai dentro de um grupo, então a contagem de quadros acompanha 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.

A música é a espinha dorsal — estabeleça uma faixa antes de qualquer outra coisa. Esta habilidade é ajustada para BGM rápida e de alta energia: uma grade de batidas forte guia os cortes (faixas calmas funcionam, mas marque o ritmo por frase em vez de batida). Se o usuário lhe deu áudio — um arquivo de música ou um vídeo do qual 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 / MusicGen local; 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 fazer login. Se não estiver conectado, PARE e aguarde a escolha do usuário — faça login ou continue offline com o 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.) Consulte /hyperframes-media → Preflight para obter a orientação canônica. De qualquer forma, a faixa vai para assets/bgm.mp3. Armazene 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 briefing em kebab-case, como midnight-drive-loop — nunca um timestamp. init verifica as habilidades 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 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 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; proporção / 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), 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. Divida a faixa em quadros 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), 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 uma linha de feel (a situação musical simples que a Etapa 3 combina com um template). Aqui, apenas classifique e disponha: deixe cada ### Groups do quadro como TBD (Step 3) e o style do frontmatter em branco — sem templates, texto, cor ou fontes. Espere ~1–6 quadros.

Portão: os quadros ladrilham a faixa (primeiro em 0, último em duration_s); cada um carrega span_sec + pacing + mood + feel; cada ### 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 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 local, faça duas coisas:

  1. 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 templates são donos da composição). Copie-o para frame.md sem modificações e preencha o style do frontmatter (fonte + uma paleta de ≤4–6 amostras) a partir dele.
  2. Preencha cada quadro. Decida seus grupos e dê a cada um um tratamento: um template 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 ao pacing. Escreva o texto. Você é dono do O QUE (template / 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 que não ladrilham a faixa, um 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 autocontido.

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 worker recebe exatamente um quadro e este contexto:

PROJECT_DIR: <caminho abs>
frame_id: <NN-frame_id>              # = o nome 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 (templates) e
           <SKILL_DIR>/references/motion-primitives/<id>/ (livre); ativos armazenados/ (grupos de ativos)
Contratos: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <larg>×<alt>   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]), controla 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 reportariam 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 parar 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 ladrilham 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). lint verifica a estrutura, validate executa Chrome headless (capturando erros de JS e ativos ausentes), inspect captura 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 você mesmo a correção segura mais barata: edite o compositions/frames/NN-*.html ofensor. Nunca mude a duração ou o tempo do áudio para esconder um problema de sincronia. Depois que os portões passarem, pause para revisão do usuário e renderize apenas com 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 continuação

Você temContinuar de
Apenas assets/bgm.mp3Etapa 1
audiomap.jsonEtapa 2
STORYBOARD.md (esqueleto)Etapa 3
STORYBOARD.md (completo)Etapa 4
Todos os arquivos de quadroEtapa 5
index.htmlEtapa 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 (armazenar mídia do usuário), lib/storyboard.mjs (analisador sintático fornecido). Todo o resto é o CLI hyperframes.

LeiaQuando
references/frame-skeleton.mdEtapa 2: ler a música, definir os quadros, definir pacing
references/planning.md · storyboard-format.mdEtapa 3: escolher a marca, preencher cada quadro, escrever o plano
references/template-catalog.mdEtapa 3: escolher um template por grupo
references/motion-primitive-catalog.mdEtapa 3: escolher primitivas de movimento para grupos livres
references/montage.mdEtapa 3 (se houver ativos do usuário): criar grupos de montagem
sub-agents/frame-worker.mdEtapa 4: despachar um worker por quadro
../hyperframes-core/references/subagent-dispatch.mdEtapa 4: como despachar subagentes
../hyperframes-core/references/sub-compositions.md + determinism-rules.mdEtapa 4: contratos de composição
../hyperframes-creative/references/design-spec.mdEtapa 3: seleção de preset de frame (tabela de fontes + paletas)
references/bgm.mdEtapa 0: geração de BGM

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

Army161/OpenMontage

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax). Supports two gateways: HeyGen API and fal.ai API.

Army161/OpenMontage

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Army161/OpenMontage

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Army161/OpenMontage

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Army161/OpenMontage

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Army161/OpenMontage

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Army161/OpenMontage

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Army161/OpenMontage

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Army161/OpenMontage

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

Army161/OpenMontage

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

Army161/OpenMontage

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Army161/OpenMontage

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

Army161/OpenMontage

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

Army161/OpenMontage

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

Army161/OpenMontage

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

Army161/OpenMontage

Best practices for Remotion - Video creation in React

Army161/OpenMontage

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Army161/OpenMontage

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

Army161/OpenMontage

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

Army161/OpenMontage

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

Habilidades Relacionadas