Communitygithub.com

9018/mychat

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`)。

mychat 是什么?

HyperFrames CLI 是 HyperFrames 框架的核心命令行工具,为开发者提供了一套完整的视频合成开发工作流。它支持从头搭建项目(`init`)、从 URL 捕获内容(`capture`)、编写 HTML 合成、执行代码检查(`lint`)、运行时验证(`validate`)以及可视化检查(`inspect`)。CLI 还内建了基于 Studio 的预览编辑器,允许用户在渲染前手动调整任何元素。该工具支持多种渲染模式:迭代开发可使用草稿质量,交付时选择高质量输出,CI 环境支持 Docker 和严格模式,长时间或大尺寸渲染可借助 AWS Lambda 进行云端分布式渲染。HyperFrames CLI 在设计上充分考虑了代理(Agent)和 CI 场景:所有命令(除 render、preview、play 外)均支持 `--json` 输出,便于程序化处理;自动检测非 TTY 模式并切换到非交互式;提供严格的 CI 门控(`--strict`、`--strict-all`、`--strict-variables`);渲染命令需用户明确批准,并在渲染后进行文件大小和时长验证。此外,工具通过子命令(`doctor`、`browser`)帮助诊断环境问题,并与 `hyperframes-core`、`hyperframes-registry`、`hyperframes-media` 等技能无缝协作,形成完整的视频合成开发生态。

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

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

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

工作流

  1. Scaffold(搭建) — npx hyperframes init my-video(或从 URL capture)。init 还会检查已安装的技能是否与 GitHub 上的最新版本一致,并更新过时的全局技能集。--skip-skills 标志目前被禁用(临时情况,等待 skills.sh 注册表跟上),因此每次 init 都会执行此检查并拉取最新的技能。
  2. 编写(Write) — 创作 HTML 合成(参见 hyperframes-core 技能)
  3. 检查(Lint) — npx hyperframes lint
  4. 验证(Validate) — npx hyperframes validate(运行时错误 + 对比度)
  5. 可视化检查(Visual inspect) — npx hyperframes inspect
  6. 预览(Preview) — npx hyperframes preview 打开 Studio,这是一个时间线编辑器,用户可以在其中手动编辑任何内容(而不仅仅是观看)。在此处审查,然后询问是否渲染。
  7. 渲染(Render) — 选择变体:
    • 迭代开发: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 了解规范和实践,以及运动验证规范。

代理约定

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

  • --json 在所有命令上可用,除了 render、preview 和 play。 在任何代理/CI 调用支持的命令时使用它;输出包括一个 _meta 信封(cli 版本、最新可用版本、更新建议)。render 仅通过 stdout + 退出码报告状态——使用下方的渲染后检查验证成功;preview / play 是服务器,没有 JSON 输出。
  • doctor --json 始终以退出码 0 退出,即使环境损坏。通过负载的 ok 字段进行门控:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。这使管道免受 CLI 发布变更的影响。
  • 非 TTY 模式是自动检测的。 当 stdout 不是 TTY(CI、代理、管道输出)时,CLI 自动切换到非交互模式;init 此时需要 --example。传递 --non-interactive 可强制在 TTY 上也使用此模式。
  • CI 渲染门控:--strict 在 lint 错误时失败,--strict-all 在警告时也失败,--strict-variables 在未声明的 --variables 键处失败。
  • --json 中的路径会被脱敏——$HOME 变为字面量 $HOME,因此输出可以安全地粘贴到错误报告和代理上下文中。
  • 渲染需要用户批准。 检查通过后绝不自动渲染。在 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 create / 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)→ 使用 hyperframes-media 处理语音选择、Whisper 模型规则、字幕和 TTS 到字幕链。
  • 参数化渲染(--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。

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

最低完成门控

静态门控

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.

9018/mychat

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, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, Kling official direct API, and the Gemini API (Gemini Omni Flash).

9018/mychat

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.

9018/mychat

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

9018/mychat

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

9018/mychat

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".

9018/mychat

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.

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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.

9018/mychat

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`.

9018/mychat

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.

9018/mychat

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).

9018/mychat

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.

9018/mychat

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.

9018/mychat

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.

9018/mychat

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.

9018/mychat

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

9018/mychat

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

9018/mychat

Download video and audio from YouTube and 1000+ sites using yt-dlp. No API keys needed. Use when: (1) Downloading a video from YouTube or other sites, (2) Extracting audio from a video URL, (3) Downloading subtitles/captions from a video, (4) Getting video metadata without downloading.

相关技能