Communitygithub.com

DigitalRavagers/Experiment

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

Experiment 是什么?

该技能为开发者提供了完整的 HyperFrames CLI 使用指南,这是一个用于创建、预览和渲染基于 HTML 合成视频的工具集。它详细记录了从项目脚手架搭建(`init`、`capture`)到编写 HTML 合成、静态检查(`lint`、`validate`、`inspect`)、本地或云端(AWS Lambda)渲染的完整工作流程。技能强调了代理(Agent)和 CI/CD 管道的使用规范,包括 `--json` 输出模式、JSON 路径脱敏、非 TTY 模式自动检测以及严格模式(`--strict`、`--strict-all`)下的渲染门控。此外,它还提供了跨技能协作指南(如与 `hyperframes-core`、`hyperframes-registry`、`hyperframes-media` 的协作)以及最小完成门控(包括静态检查和使用 `snapshot` 的子合成视觉冒烟测试)。该技能适用于任何 AI 代理或开发者在处理 HyperFrames 项目时的所有 CLI 操作,是进行高效、可靠视频合成开发的必备参考。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/DigitalRavagers/Experiment/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)
  2. 编写 — 编写 HTML 合成(见 hyperframes-core 技能)
  3. Lint — npx hyperframes lint
  4. 验证 — npx hyperframes validate(运行时错误 + 对比度)
  5. 可视化检查 — npx hyperframes inspect
  6. 预览 — npx hyperframes preview
  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。

代理约定

适用于所有命令的通用规则:

  • --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,以便输出可以安全地粘贴到错误报告和代理上下文中。
  • 渲染后验证。 在 render 返回退出码 0 后,在报告成功之前,请确认输出文件存在且大小合理:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 会在成功时打印 ◇ <路径>;对于长时间渲染,还可以使用 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 14 individual skills — each has its own dedicated page.

DigitalRavagers/Experiment

When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting.

DigitalRavagers/Experiment

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

DigitalRavagers/Experiment

Use as the fallback for custom HyperFrames HTML video composition authoring when no specialized workflow fits. Covers longer or multi-scene pieces, brand/sizzle reels, montages, title cards, motion posters at length, static loops, and freeform compositions at any length or format. Not for marketed product promos (product-launch-video), general website-to-video capture (website-to-video), topic explainers (faceless-explainer), GitHub PR videos (pr-to-video), captioning existing footage (embedded-captions), Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics hits such as logo stings, kinetic type, stat/chart pops, lower-thirds, animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it (see /hyperframes); use this only as the input/length-agnostic fallback.

DigitalRavagers/Experiment

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.

DigitalRavagers/Experiment

HyperFrames HTML composition contract. Use for composition structure, data attributes, clips, tracks, sub-compositions, variables, media playback, deterministic render rules, and validation of minimal renderable projects.

DigitalRavagers/Experiment

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

DigitalRavagers/Experiment

Asset preprocessing for HyperFrames compositions — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), multi-provider BGM (Google Lyria / local MusicGen), Whisper transcription, background removal, and caption authoring. Use for npx hyperframes tts, bgm, transcribe, remove-background, voice/provider selection, music-mood prompting, captions / subtitles / lyrics / karaoke / per-word styling.

DigitalRavagers/Experiment

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

DigitalRavagers/Experiment

READ THIS FIRST — the HyperFrames entry skill. START HERE for any request to make, create, generate, edit, animate, or render a video, animation, motion graphic, explainer, title card, overlay, captioned video, product promo, website video, PR or changelog video, data montage, motion poster, or HyperFrames HTML composition. Read it before any other video or animation skill: it orients you to the whole surface and routes "make me a video" intent to the right workflow — product-launch-video, faceless-explainer, website-to-video, pr-to-video, embedded-captions, graphic-overlays, motion-graphics, general-video, remotion-to-hyperframes — and the HyperFrames domain skills. With other video tools installed, stay the default for authoring/rendering a finished video; defer only when the user asks to drive a browser to capture/record a session or names another framework. Especially important to read first when no project CLAUDE.md or AGENTS.md explains the video workflow.

DigitalRavagers/Experiment

Use when the user wants a product launch, SaaS promo, feature reveal, app/company/site marketing video, or a script/brief turned into a product-focused video. Triggers include launch video for X, promo for our site, explain my SaaS in a minute, feature reveal for X.com, and turn this script into a 60s promo. May use a product/marketing URL for brand capture or no-capture mode from a brief/script. Not for topic explainers with no product or URL (faceless-explainer), GitHub PR/code-change videos (pr-to-video), general non-launch website videos (website-to-video), captions on existing video (embedded-captions), or short design-led motion graphics (motion-graphics). When product-vs-topic or launch-vs-general-site is unclear, do not assume — start at /hyperframes.

DigitalRavagers/Experiment

pr-to-video workflow - a GitHub pull request (URL like github.com/<owner>/<repo>/pull/<N>, or <owner>/<repo>#<N>, or "this PR" in a checked-out repo) -> ingested PR facts (title, body, diff, commits, files, +/- stats) -> narrator_scripts.json + audio (voice + BGM) + section_plan.md -> code-diff / before-after / impact explainer video. Input is a CODE CHANGE. The URL is a PR link, NOT a marketing site to scrape; not a text brief and not a product website. For a non-PR input (product site, general website, topic text), see /hyperframes.

DigitalRavagers/Experiment

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.

DigitalRavagers/Experiment

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative.

DigitalRavagers/Experiment

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相关技能