Communitygithub.com

Army161/OpenMontage

Recursos de audio y medios para composiciones HyperFrames, impulsados por un motor de audio compartido (`scripts/audio.mjs`) — TTS multi-proveedor (HeyGen / ElevenLabs / Kokoro local), música de fondo + efectos de sonido (recuperación de la librería de audio de HeyGen por defecto, con generación local Lyria / MusicGen y una biblioteca SFX empaquetada como respaldo sin credenciales), transcripción Whisper, eliminación de fondo y creación de subtítulos.

¿Qué es OpenMontage?

Army161/OpenMontage es una habilidad de agente de IA diseñada para generar y gestionar activos de audio y medios para composiciones HyperFrames. Su núcleo es un motor de audio unificado (`scripts/audio.mjs`) que toma una solicitud neutral (`audio_request.json`) y produce metadatos estructurados (`audio_meta.json`) junto con archivos de voz, música de fondo (BGM) y efectos de sonido (SFX). El motor admite múltiples proveedores de texto a voz (TTS): HeyGen (nativo con marcas de tiempo de palabra), ElevenLabs y Kokoro local (sin necesidad de clave API). Para BGM y SFX, de forma predeterminada utiliza la librería de audio de HeyGen si hay una credencial configurada; de lo contrario, recurre a la generación local con modelos como Lyria o MusicGen para BGM, o a una biblioteca SFX empaquetada de 21 archivos. También incluye funciones como transcripción con Whisper, eliminación de fondo, y creación de subtítulos con soporte para karaoke y estilizado por palabra. La habilidad enfatiza un flujo de trabajo centralizado: nunca se debe implementar TTS, BGM o SFX manualmente en los flujos de trabajo; en su lugar, se escribe un adaptador `audio_request.json` y se invoca el motor. La decisión de usar servicios en la nube o motores locales depende completamente de la presencia de una credencial de HeyGen, la cual se maneja a través del comando `npx hyperframes auth status/login` (OAuth o clave API). Una regla crucial es ejecutar siempre este preflight antes de generar cualquier audio para que el usuario decida si iniciar sesión o continuar sin conexión, en lugar de hacer una fallback silenciosa.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

HyperFrames Media

Crea los activos de audio y medios que necesita una composición: locución (TTS), música de fondo + efectos de sonido, transcripción, subtítulos, eliminación de fondo — y luego consume y anima esos datos en HTML. Para colocar activos en composiciones, consulta hyperframes-core.

El motor de audio — una fuente para TTS · BGM · SFX

Los flujos de trabajo NO implementan audio manualmente ni crean copias internas. Hay un solo motor — scripts/audio.mjs — que toma un audio_request.json neutral y escribe audio_meta.json (más los activos bajo assets/voice|bgm|sfx):

# <MEDIA_DIR> = directorio de esta habilidad
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json

Las tres capacidades se degradan según UN SOLO INTERRUPTOR — si hay una credencial de HeyGen presente (resuelta desde $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, no desde la CLI):

CapacidadCredencial HeyGen presenteausente
TTSHeyGen Starfish REST (marcas de tiempo de palabra nativas)→ ElevenLabs → Kokoro (encadena transcribe para palabras)
BGMRecuperación de música de HeyGenGeneración local Lyria → MusicGen (desconectada)
SFXRecuperación de efectos de sonido de HeyGen (min_score 0.4)Biblioteca empaquetada de 21 archivos (assets/sfx/)
  • Solicitud (audio_request.json): { provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }. id vincula cada línea de vuelta al modelo del llamante (un número de fotograma, un ID de escena, …). bgm.mode = retrieve | generate | none; omítelo para modo automático (recuperar si hay credencial, si no generar). Un retrieve explícito es estricto — omite en lugar de iniciar una generación desconectada (para llamantes que no tienen un paso wait-bgm).
  • Salida (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 ejecuta un subconjunto y fusiona en un --out existente (por ejemplo, TTS+BGM temprano, SFX una vez que existen las señales).
  • La generación de BGM se inicia desconectada (bgm_pending: true) — ejecuta scripts/wait-bgm.mjs antes de ensamblar.
  • scripts/heygen-tts.mjs es una CLI de un solo uso sobre el mismo código (un texto → wav + palabras) para cuando solo necesitas TTS de HeyGen sin un archivo de solicitud.

La lista completa de flags y el esquema de audio_meta.json están en el encabezado de scripts/audio.mjs. Las referencias a continuación cubren los detalles del proveedor y los casos límite detrás de cada capacidad.

Verificación previa — muestra el estado de inicio de sesión antes de cualquier audio

Ejecuta esto siempre antes de generar voz o BGM — tanto en un flujo de trabajo completo como en una solicitud única de "genera un BGM/locución". Que no haya credencial de HeyGen no es razón para recurrir silenciosamente a motores locales: primero recomienda iniciar sesión y deja que el usuario decida. Ejecuta la verificación previa compartida y transmite su salida textualmente — no improvises tu propio mensaje de "clave faltante" y no ofrezcas escribir claves en un .env por repositorio:

npx hyperframes auth status
  • Con sesión iniciada → imprime la cuenta; continúa.
  • Sin sesión iniciada (se espera exit 1 — "no has iniciado sesión" es un estado normal, no un fallo) → imprime una guía de registro. Recomienda iniciar sesión: npx hyperframes auth login es OAuth en el navegador — inicia sesión y crea una cuenta (siempre disponible a través de la CLI de este repositorio). Para usar una clave API de HeyGen existente (de app.heygen.com/settings/api), ejecuta npx hyperframes auth login --api-key — la guarda en ~/.heygen compartido (sin .env por repositorio). La salida también enumera los motores locales a los que recurrirán la voz/BGM y una pista de pip cuando falten dependencias. Transmite esta salida tal cual — no la parafrasees con tus propias palabras. Luego DETENTE y espera a que el usuario elija — iniciar sesión, o decir "adelante" / "local" para continuar sin conexión — antes de generar nada. Este es un punto de decisión real, no una nota pasajera: no lo mezcles en otra pregunta y no lo pases por tu cuenta. (Excepción: en modo autónomo / no interactivo, anota el estado y continúa sin conexión.)
  • npx hyperframes auth status --json devuelve { configured, recommended_action, offline_engines } para ramificación determinista.
  • Si la CLI no se puede ejecutar (no está en PATH y npx no puede obtenerla) → aún así recomienda iniciar sesión (npx hyperframes auth login) y DETENTE para que el usuario decida — no trates "sin credencial" como un semáforo verde silencioso para la generación local.

La resolución de credenciales, la prioridad completa de claves y la lista de dependencias locales están en references/requirements.md.

Cadenas de proveedores (el detalle detrás del motor)

TTS — gana el primer proveedor disponible (el motor, o npx hyperframes tts "..."):

OrdenProveedorDetectado cuandoMarcas de tiempo de palabra
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth loginSí, nativas — pasa --words narration.words.json para capturarlas
2ElevenLabs$ELEVENLABS_API_KEY configuradaNo — encadena transcribe después
3Kokoro-82M (local, 54 voces)siempre (no requiere clave)No — encadena transcribe después

La CLI publicada hyperframes tts suele ser la compilación solo local (su --help dice "Kokoro-82M", sin --provider/--words) y recurre silenciosamente a Kokoro incluso con $HEYGEN_API_KEY configurada. Por eso la ruta de HeyGen del motor es el scripts/heygen-tts.mjs autónomo (REST), NO la CLI; la CLI se usa solo para la ruta de Kokoro. Consulta references/tts.md.

BGM y SFX — por defecto se recuperan de la librería de audio de HeyGen (/v3/audio/sounds), misma credencial que para TTS de HeyGen, con el respaldo sin credencial del interruptor anterior:

ActivoTipo de HeyGenAterriza enRespaldo (sin credencial)
BGMmusicassets/bgm/track.mp3 (recuperación) · track.wav (generación)Generación Lyria / MusicGen
SFXsound_effects (min_score 0.4)assets/sfx/<slug>.mp3Biblioteca empaquetada de 21 archivos (assets/sfx/* + manifest.json)

Consulta references/bgm.md y references/sfx.md.

Enrutamiento

TareaLee
El motor de audio — esquema de solicitud/meta, --only, el interruptorscripts/audio.mjs (comentario del encabezado)
npx hyperframes tts / heygen-tts.mjs — proveedores, voces, palabrasreferences/tts.md
BGM — Recuperación de HeyGen + generación local Lyria / MusicGenreferences/bgm.md
SFX — Recuperación de HeyGen (min_score 0.4) + biblioteca local empaquetadareferences/sfx.md
npx hyperframes transcribe — Whisper, reglas de modelo, forma de salidareferences/transcribe.md
npx hyperframes remove-background — recortes transparentesreferences/remove-background.md
TTS → transcripción → subtítulos (sin locución grabada)references/tts-to-captions.md
Creación de subtítulos — detección de estilo, diseño, agrupación de palabras, salidareferences/captions/authoring.md
Manejo de transcripciones — formatos de entrada, compuertas de calidad, limpieza, APIsreferences/captions/transcript-handling.md
Movimiento de subtítulos — karaoke, efectos de marcador, reacción al audioreferences/captions/motion.md
Cachés de modelo, dependencias del sistema, solución de problemasreferences/requirements.md

Reglas no negociables

  • Un solo motor, sin copias internas. Produce audio a través de scripts/audio.mjs (o heygen-tts.mjs para TTS de HeyGen de un solo uso). No reimplementes TTS/BGM/SFX dentro de un flujo de trabajo — escribe un adaptador audio_request.json y llama al motor.
  • "HeyGen disponible" = una credencial resoluble, no la CLI. Todo el interruptor depende de heygenCredential(); la CLI publicada hyperframes tts puede ser solo Kokoro, y no existe ningún comando hyperframes bgm / hyperframes sfx.
  • Los IDs de voz son específicos del proveedor. am_michael es solo de Kokoro; los UUID de HeyGen no funcionan en Kokoro. Si pasas --voice, también fija --provider para evitar una deriva silenciosa de proveedor cuando el entorno del usuario cambia.
  • Pasa siempre --model a transcribe. El valor predeterminado de la CLI small.en traduce silenciosamente el audio que no está en inglés. Consulta references/transcribe.md → "Regla de idioma".
  • HeyGen devuelve marcas de tiempo de palabra; ElevenLabs / Kokoro no. El motor encadena transcribe automáticamente para los dos últimos; de forma independiente, pasa --words a HeyGen o ejecuta transcribe contra el archivo de audio.
  • Los subtítulos consumen el formato plano de arreglo de palabras con { id, text, start, end }. Consulta references/transcribe.md → "Forma de salida".
  • remove-background --background-output es recorte de agujero, no relleno. Para "escena sin la persona", se necesita una herramienta diferente. Consulta references/remove-background.md → "Cuándo NO es la herramienta adecuada".
  • BGM/SFX por defecto usan recuperación de HeyGen; el respaldo sin credencial es generación (BGM) o la biblioteca empaquetada (SFX). /audio/sounds clasifica por una consulta de texto — nombra los efectos de forma concreta (vidrio rompiéndose, no sonido dramático); una falta de coincidencia omite, nunca bloquea la representación. Los SFX se sitúan en un volumen ~0.35 por debajo de la voz + BGM. Consulta references/sfx.md / references/bgm.md.
  • Trata el HTML de subtítulos del flujo de trabajo como salida generada. Para videos basados en plantillas, la fuente de la máscara reutilizable está en .hyperframes/caption-skin.html y el script del flujo de trabajo escribe compositions/captions.html; no edites el compositions/captions.html generado para arreglar la máscara. Reconstruye a través del captions.mjs del flujo de trabajo, o usa el mecanismo de anulaciones explícitas de ese flujo de trabajo cuando esté 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.

Skills relacionados