Communitygithub.com

Army161/OpenMontage

Áudio e mídia para composições HyperFrames, produzidos por um motor de áudio compartilhado (`scripts/audio.mjs`) — TTS multi-provedor (HeyGen / ElevenLabs / Kokoro local), música de fundo + efeitos sonoros (recuperação da biblioteca de áudio HeyGen por padrão, com geração local Lyria / MusicGen e uma biblioteca SFX integrada como fallback sem credenciais), transcrição Whisper, remoção de fundo e autoria de legendas.

O que é OpenMontage?

O skill Army161/OpenMontage gerencia todos os ativos de áudio e mídia necessários para composições HyperFrames, operando através de um único motor de áudio centralizado em `scripts/audio.mjs`. Ele oferece suporte a múltiplos provedores de TTS (incluindo HeyGen, ElevenLabs e Kokoro local), geração e recuperação de música de fundo (BGM) e efeitos sonoros (SFX), transcrição via Whisper, remoção de fundo e criação de legendas. O motor é inteligente: quando uma credencial HeyGen está disponível, ele usa serviços REST para TTS com timestamps de palavras nativos e recuperação de música/SFX da biblioteca HeyGen. Sem credencial, ele degrada graciosamente para geração local (Lyria/MusicGen para BGM, Kokoro para TTS com transcrição encadeada para timestamps, e uma biblioteca SFX local de 21 arquivos). O fluxo de trabalho sempre executa uma verificação de autenticação primeiro (`npx hyperframes auth status`), recomendando login antes de prosseguir, garantindo que o usuário decida entre usar serviços HeyGen ou modos offline. O skill é parte do ecossistema HyperFrames e é usado principalmente em ambientes de desenvolvimento, como Claude Code, Cursor ou Codex, onde agentes de IA automatizam a criação de mídia para composições interativas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Army161/OpenMontage/tree/HEAD/.agents/skills/hyperframes-media

Perguntar na sua IA favorita

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

Documentação

HyperFrames Mídia

Crie os ativos de áudio e mídia que uma composição precisa — narração (TTS), música de fundo + efeitos sonoros, transcrição, legendas, remoção de fundo — e então consuma e anime esses dados em HTML. Para colocar ativos em composições, veja hyperframes-core.

O motor de áudio — uma fonte para TTS · BGM · SFX

Os fluxos de trabalho NÃO criam áudio manualmente nem usam cópias avulsas. Existe um motor — scripts/audio.mjs — que recebe um audio_request.json neutro e escreve audio_meta.json (mais ativos em assets/voice|bgm|sfx):

# <MEDIA_DIR> = diretório deste skill
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json

Todas as três capacidades dependem de UMA chave — se uma credencial HeyGen está presente (resolvida de $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, não da CLI):

CapacidadeCredencial HeyGen presenteausente
TTSHeyGen Starfish REST (timestamps de palavras nativos)→ ElevenLabs → Kokoro (encadeie transcribe para palavras)
BGMRecuperação de música HeyGenLyria → MusicGen geração local (separada)
SFXRecuperação de efeitos sonoros HeyGen (min_score 0.4)biblioteca local de 21 arquivos (assets/sfx/)
  • Requisição (audio_request.json): { provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }. id conecta cada linha ao modelo do chamador (um número de quadro, um ID de cena, …). bgm.mode = retrieve | generate | none; omita para automático (recuperar quando com credencial, senão gerar). Um retrieve explícito é estrito — ele pula em vez de iniciar uma geração separada (para chamadores sem etapa wait-bgm).
  • Saída (audio_meta.json, indexada por id): { tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }.
  • --only tts,bgm,sfx executa um subconjunto e funde em um --out existente (ex.: TTS+BGM cedo, SFX quando as pistas existirem).
  • Geração de BGM é iniciada separadamente (bgm_pending: true) — execute scripts/wait-bgm.mjs antes de montar.
  • scripts/heygen-tts.mjs é uma CLI de uso único sobre o mesmo código (um texto → wav + palavras) para quando você só precisa de TTS HeyGen sem um arquivo de requisição.

A lista completa de flags e o esquema audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes do provedor e casos extremos por trás de cada capacidade.

Pré-verificação — mostre status de login antes de qualquer áudio

Sempre execute isso antes de gerar voz ou BGM — dentro de um fluxo de trabalho completo ou uma solicitação avulsa de "gere um BGM/narração para mim". Não ter credencial HeyGen não é motivo para cair silenciosamente em motores locais: primeiro recomende fazer login e deixe o usuário decidir. Execute a pré-verificação compartilhada e repassa sua saída literalmente — não improvise seu próprio prompt de "chave ausente" e não se ofereça para escrever chaves em um .env por repositório:

npx hyperframes auth status
  • Conectado → ele imprime a conta; prossiga.
  • Não conectado (exit 1 é esperado aqui — "não conectado" é um estado normal, não uma falha) → ele imprime orientação de registro primeiro. Recomende fazer login: npx hyperframes auth login é OAuth no navegador — ele faz login e cria uma conta (sempre disponível através da CLI deste repositório). Para usar uma chave de API HeyGen existente (de app.heygen.com/settings/api), execute npx hyperframes auth login --api-key — ele salva no ~/.heygen compartilhado (sem .env por repositório). A saída também lista os motores locais para os quais voz/BGM cairão e uma dica pip quando dependências estiverem faltando. Repasse esta saída como está — não a parafraseie com suas próprias palavras. Então PARE e aguarde o usuário escolher — fazer login, ou dizer "vai" / "local" para continuar offline — antes de gerar qualquer coisa. Este é um ponto de decisão real, não uma nota passageira: não o misture em outra pergunta e não prossiga além dele por conta própria. (Exceção: em modo autônomo / não interativo, anote o status e continue offline.)
  • npx hyperframes auth status --json retorna { configured, recommended_action, offline_engines } para ramificação determinística.
  • Se a CLI não puder ser executada (não no PATH e npx não consegue obtê-la) → ainda recomende fazer login (npx hyperframes auth login) e PARE para a escolha do usuário — não trate "sem credencial" como um sinal verde silencioso para geração local.

Resolução de credenciais, prioridade total de chaves e a lista de dependências locais estão em references/requirements.md.

Cadeias de provedores (os detalhes por trás do motor)

TTS — o primeiro provedor disponível vence (o motor, ou npx hyperframes tts "..."):

OrdemProvedorDetectado quandoTimestamps de palavras
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth loginSim, nativo — passe --words narration.words.json para capturar
2ElevenLabs$ELEVENLABS_API_KEY definidoNão — encadeie transcribe após
3Kokoro-82M (local, 54 vozes)sempre (nenhuma chave necessária)Não — encadeie transcribe após

A CLI publicada hyperframes tts é frequentemente a versão apenas local (seu --help diz "Kokoro-82M", sem --provider/--words) e cai silenciosamente para Kokoro mesmo com $HEYGEN_API_KEY definida. É por isso que o caminho HeyGen do motor é o scripts/heygen-tts.mjs autossuficiente (REST), NÃO a CLI; a CLI é usada apenas para o caminho Kokoro. Veja references/tts.md.

BGM e SFX — por padrão recuperados da biblioteca de áudio HeyGen (/v3/audio/sounds), mesma credencial do TTS HeyGen, com o fallback sem credencial da chave acima:

AtivoHeyGen typeDestinoFallback (sem credencial)
BGMmusicassets/bgm/track.mp3 (recuperar) · track.wav (gerar)Geração Lyria / MusicGen
SFXsound_effects (min_score 0.4)assets/sfx/<slug>.mp3biblioteca local de 21 arquivos (assets/sfx/* + manifest.json)

Veja references/bgm.md e references/sfx.md.

Roteamento

TarefaLeia
O motor de áudio — esquema de requisição/meta, --only, a chavescripts/audio.mjs (comentário do cabeçalho)
npx hyperframes tts / heygen-tts.mjs — provedores, vozes, palavrasreferences/tts.md
BGM — Recuperação HeyGen + geração local Lyria / MusicGenreferences/bgm.md
SFX — Recuperação HeyGen (min_score 0.4) + biblioteca local integradareferences/sfx.md
npx hyperframes transcribe — Whisper, regras de modelo, formato de saídareferences/transcribe.md
npx hyperframes remove-background — recortes transparentesreferences/remove-background.md
TTS → transcrição → legendas (sem narração gravada)references/tts-to-captions.md
Autoria de legendas — detecção de estilo, layout, agrupamento de palavras, saídareferences/captions/authoring.md
Manipulação de transcrições — formatos de entrada, gates de qualidade, limpeza, APIsreferences/captions/transcript-handling.md
Movimento de legendas — karaokê, efeitos de marcador, áudio-reativoreferences/captions/motion.md
Caches de modelo, dependências do sistema, solução de problemasreferences/requirements.md

Regras inegociáveis

  • Um motor, sem cópias avulsas. Produza áudio via scripts/audio.mjs (ou heygen-tts.mjs para TTS HeyGen de uso único). Não reimplemente TTS/BGM/SFX dentro de um fluxo de trabalho — escreva um adaptador audio_request.json e chame o motor.
  • "HeyGen disponível" = uma credencial resolvível, não a CLI. Toda a chave depende de heygenCredential(); a CLI publicada hyperframes tts pode ser apenas Kokoro, e não há nenhum comando hyperframes bgm / hyperframes sfx.
  • IDs de voz são específicos do provedor. am_michael é apenas Kokoro; UUIDs do HeyGen não funcionam no Kokoro. Se você passar --voice, também fixe --provider para evitar desvio silencioso de provedor quando o ambiente do usuário mudar.
  • Sempre passe --model para transcribe. O padrão da CLI small.en traduz silenciosamente áudio não-inglês. Veja references/transcribe.md → "Regra de Idioma".
  • HeyGen retorna timestamps de palavras; ElevenLabs / Kokoro não. O motor encadeia transcribe automaticamente para os dois últimos; de forma independente, passe --words para HeyGen ou execute transcribe no arquivo de áudio.
  • Legendas consomem o formato de matriz plana de palavras com { id, text, start, end }. Veja references/transcribe.md → "Formato de Saída".
  • remove-background --background-output é corte de buraco, não inpaint. Para "cena sem a pessoa", uma ferramenta diferente é necessária. Veja references/remove-background.md → "Quando NÃO é a ferramenta certa".
  • BGM/SFX padrão são recuperação HeyGen; o fallback sem credencial é geração (BGM) ou a biblioteca local (SFX). /audio/sounds classifica por uma consulta de texto — nomeie efeitos concretamente (glass shatter, não dramatic sound); uma não correspondência pula, nunca bloqueia a renderização. SFX ficam em volume ~0,35 sob voz + BGM. Veja references/sfx.md / references/bgm.md.
  • Trate o HTML de legendas do fluxo de trabalho como saída gerada. Para vídeos com skins predefinidas, a fonte da skin reutilizável está em .hyperframes/caption-skin.html e o script do fluxo de trabalho escreve compositions/captions.html; não edite compositions/captions.html gerado para corrigir a skin. Reconstrua via captions.mjs do fluxo de trabalho, ou use o mecanismo de substituições explícitas desse fluxo de trabalho quando presente.

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

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

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

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