Communitygithub.com

Army161/OpenMontage

HyperFrames CLI 开发循环工具。用于运行 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 或 remove-background,以及排查 HyperFrames 构建/渲染环境问题。同时作为 AWS Lambda 云端渲染的入口点(`hyperframes lambda deploy / render / progress / destroy / policies`)。

OpenMontage 是什么?

Army161/OpenMontage 是一个针对 HyperFrames CLI 的 AI Agent 技能。它提供了一套围绕 `npx hyperframes` 命令的完整开发工作流,涵盖项目初始化、代码检查(lint、validate、inspect)、视觉预览与交互式编辑(Studio 时间线编辑器)、本地与云端(AWS Lambda)渲染等环节。该技能适用于各类 AI 编程助手(如 Claude Code、Cursor 等),其核心价值在于通过自动化脚手架、静态/动态验证、快照对比和 Lambda 分布式渲染,结构化地将视频合成开发流程化,显著缩短渲染迭代周期。技能文档详细阐述了所有子命令的使用场景、Agent 与 CI 集成约定(包括 JSON 输出、非 TTY 检测、渲染用户确认门槛等)、跨技能协作路径(Tailwind、注册表、媒体预处理)以及最小完成门槛——通过 lint、validate、inspect 和 snapshot 的组合确保 `index.html` 与子合成的挂载正确性,防止跨文件挂载失败。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Army161/OpenMontage/tree/HEAD/.agents/skills/hyperframes-cli

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames CLI

所有操作均通过 npx hyperframes 执行,除非项目说明指定了本地包装器。请严格遵守本地包装器。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 脚手架 — npx hyperframes init my-video(或从 URL 执行 capture)。init 还会检查本地安装的技能是否与 GitHub 上的最新版本一致,如有过时则更新全局技能集。--skip-skills 标志当前已被禁用(临时措施,等待 skills.sh 注册表跟上),因此每次 init 都会执行此检查并拉取我们最新的技能。
  2. 编写 — 编写 HTML 合成(参见 hyperframes-core 技能)
  3. 代码检查 — npx hyperframes lint
  4. 验证 — npx hyperframes validate(运行时错误 + 对比度)
  5. 视觉检查 — npx hyperframes inspect
  6. 预览 — npx hyperframes preview 会打开 Studio(时间线编辑器),用户可以在其中手动编辑任何内容(不仅仅是观看)。在那里审查,然后在渲染前询问用户。
  7. 渲染 — 选择变体:
    • 迭代:npx hyperframes render --quality draft
    • 交付:npx hyperframes render --quality high --output out.mp4
    • CI / 跨主机复现:npx hyperframes render --docker --strict --output out.mp4
    • 云端(长时间/大规模):npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(参见下面的 Lambda 部分)

在预览前运行 lint、validate 和 inspect。lint 会捕获丢失的 data-composition-id、重叠的轨道和未注册的时间线。validate 在无头 Chrome 中加载合成,并报告运行时控制台错误以及 WCAG 对比度问题。inspect 会在时间线中搜索,报告文本溢出气泡/容器或画布的情况——并且,当存在 *.motion.json 侧边文件时,会根据相同的时间线搜索验证运动意图(进入帧的触发、交错顺序、在帧内、活跃度)。

对于运动密集型工作,优先使用快照驱动的迭代和 *.motion.json 侧边文件——相关规范请参见 references/lint-validate-inspect.md。

Agent 约定

适用于所有命令的跨领域规则:

  • 除 render、preview 和 play 外,所有命令均可使用 --json。 任何 Agent / CI 调用支持的命令时都应使用它;输出包含一个 _meta 信封(CLI 版本、最新可用版本、更新建议)。render 仅通过 stdout + 退出码报告状态——请通过下面的渲染后检查来验证成功;preview / play 是服务器,没有 JSON。
  • doctor --json 始终以退出码 0 退出,即使环境出现问题。通过检查 payload 的 ok 字段来判断:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这可以避免管道受 CLI 发布变更的影响。
  • 非 TTY 模式会被自动检测。 当 stdout 不是 TTY(CI、Agent、管道输出)时,CLI 会自动切换到非交互模式;此时 init 需要 --example。可通过 --non-interactive 强制启用此模式,即使在 TTY 上也是如此。
  • CI 对渲染的约束:--strict 在遇到 lint 错误时失败,--strict-all 在遇到警告时也失败,--strict-variables 在遇到未声明的 --variables 键时失败。
  • --json 中的路径会被脱敏——$HOME 会变成字面字符串 $HOME,以便输出可以安全地粘贴到错误报告和 Agent 上下文中。
  • 渲染需要用户确认。 检查通过后切勿自动渲染。在 preview 处暂停,告知用户视频可在 Studio 中编辑,仅在用户批准后执行渲染。
  • 渲染后验证。 在 render 返回退出码 0 后,先确认输出文件存在且大小合理,再报告成功:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 成功时会打印 ◇ <path>;对于长时间渲染,还需使用 ffprobe -i "$OUTPUT" -show_format -v error 进行时长验证。

路由指南

想要…请阅读
搭建项目(init、capture、skills)references/init-and-scaffold.md
检查正确性(lint、validate、inspect、snapshot)references/lint-validate-inspect.md
预览或渲染(preview、play、render、publish)references/preview-render.md
诊断环境(doctor、browser)references/doctor-browser.md
在 AWS Lambda 上云端渲染(lambda deploy / sites / render / progress / destroy / policies)references/lambda.md
其他(info、upgrade、compositions、docs、benchmark、telemetry、资产预处理)references/upgrade-info-misc.md

跨技能协作

  • Tailwind 项目(init --tailwind)→ 在编辑类或主题令牌之前,使用 hyperframes-core(Tailwind 参考)。
  • 注册表块/组件(hyperframes add、hyperframes catalog)→ 对于安装路径、子合成连接和代码片段合并,使用 hyperframes-registry。
  • 资产预处理(tts、transcribe、remove-background)→ 对于语音选择、Whisper 模型规则、字幕和 TTS 到字幕链,使用 hyperframes-media。
  • 参数化渲染(--variables)→ 通过在 <html> 上声明 data-composition-variables 来实现;完整模式参见 hyperframes-core。

Lambda(云端渲染)

hyperframes lambda 将分布式渲染部署到 AWS Lambda,并从您的笔记本或 CI 驱动渲染。端到端需要三个命令:

npx hyperframes lambda deploy                                             # 部署 SAM 堆栈 (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # 拆除 (S3 存储桶会被保留)

当渲染对单台主机来说太长时间/太大(多分钟视频、4K、大批量并行)且您已配置 AWS 凭证时,请使用 Lambda。对于开发循环迭代,请坚持使用本地 render。

先决条件、所有 6 个子命令(deploy、sites create、render、progress、destroy、policies)、IAM 策略验证、状态文件以及成本/清理规则,请参见 references/lambda.md。

最低完成门槛

静态检查

npx hyperframes lint
npx hyperframes validate

对于布局敏感的工作,添加 inspect;在 CI 中使用 render --strict 以在 lint 错误时失败。

视觉冒烟测试——当项目使用子合成时必须执行

lint / validate / inspect 仅单独评估每个合成。它们从不加载 index.html 并通过 data-composition-src 挂载子合成,因此无法捕获跨文件挂载失败(参见 hyperframes-core → references/sub-compositions.md,“常见陷阱”)。唯一能捕获它们的检查是实际加载 index.html 并在时间线中搜索。

请使用 hyperframes snapshot——它以与 render 相同的方式加载项目(因此执行相同的挂载路径),但仅捕获您指定的时间点,因此只需几秒钟而非完整渲染:

# 在每个子合成的中间点捕获一帧。
# 中间点 = index.html 中每个宿主槽位的 data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# 或者,如果你不需要逐场景定位,可以使用均匀间隔的样本:
npx hyperframes snapshot --frames 9

输出位于 snapshots/frame-NN-at-Xs.png。目视检查每帧与场景计划的一致性。

每帧的警示标志(每个都对应静态检查无法捕获的特定失败模式):

你看到的内容根本原因
文本在左上角显示为微小且无样式<style> 块留在 <head> 的 <template> 外部(陷阱 1)—— CSS 未到达实时 DOM
SVG/图标元素放大到画布大小同上——未应用宽度/高度约束
场景的核心元素完全缺失;仅可见背景和水印宿主 ID ≠ 模板 ID(陷阱 2)—— 时间线从未运行,帧在初始状态被捕获
快照命令日志显示 Sub-composition timelines not registered after 45000ms陷阱 2——直接确认

snapshots/ 可在目视检查后删除;最终面向用户的渲染是使用 npx hyperframes render 的独立步骤。

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

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

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.

相关技能