Communitygithub.com

HyperFrames CLI 视频编辑工具包

HyperFrames CLI 工具 — 用于项目搭建、代码检查、视觉检查、预览、渲染、音频转录、文字转语音以及环境诊断。

HyperFrames CLI 视频编辑工具包 是什么?

HyperFrames CLI 是一个专为视频项目工作流设计的命令行工具集,支持从模板搭建、代码检查到最终渲染的完整流程。它通过 `npx hyperframes` 运行,依赖 Node.js >= 22 和 FFmpeg。该技能适用于 Agent 环境(如 Claude Code、Cursor 或 Codex)需要自动化视频创作任务时。核心命令包括:`init`(交互式项目搭建与媒体复制)、`lint`(静态 HTML 检查,如缺失 `data-composition-id` 或轨道重叠)、`inspect`(在无头 Chrome 中视觉检测文本溢出和布局问题)、`preview`(带热更新的 Studio 预览)、`render`(支持不同质量和格式的 MP4/WebM 输出)、`transcribe`(Whisper 音频转录)、`tts`(文字转语音)以及 `doctor`(环境诊断)。通过严格检查避免渲染错误,并支持 `--json` 输出以优化 LLM 上下文窗口。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/hyperframes-skills/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

所有操作均通过 npx hyperframes 运行。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 脚手架搭建 — npx hyperframes init my-video
  2. 编写 — 编写 HTML 组合(参见 hyperframes 技能)
  3. 代码检查 — npx hyperframes lint
  4. 视觉检查 — npx hyperframes inspect
  5. 预览 — npx hyperframes preview
  6. 渲染 — npx hyperframes render

在预览前先执行 lint 和 inspect。lint 会捕获缺少 data-composition-id、轨道重叠以及未注册的时间线。inspect 会在无头 Chrome 中打开渲染后的组合,沿时间线扫描,并报告文本超出气泡/容器或画布的问题。

脚手架搭建

npx hyperframes init my-video                        # 交互式向导
npx hyperframes init my-video --example warm-grain   # 选择示例
npx hyperframes init my-video --video clip.mp4        # 包含视频文件
npx hyperframes init my-video --audio track.mp3       # 包含音频文件
npx hyperframes init my-video --non-interactive       # 跳过提示(CI/Agent)

模板:blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph。

init 会创建正确的文件结构、复制媒体文件、使用 Whisper 转录音频,并安装 AI 编码技能。请使用它而不是手动创建文件。

代码检查

npx hyperframes lint                  # 当前目录
npx hyperframes lint ./my-project     # 指定项目
npx hyperframes lint --verbose        # 信息级别结果
npx hyperframes lint --json           # 机器可读格式

检查 index.html 和 compositions/ 中的所有文件。报告错误(必须修复)、警告(应修复)和信息(通过 --verbose)。

视觉检查

npx hyperframes inspect                 # 检查时间线上渲染的布局
npx hyperframes inspect ./my-project    # 指定项目
npx hyperframes inspect --json          # Agent 可读结果
npx hyperframes inspect --samples 15    # 更密集的时间线扫描
npx hyperframes inspect --at 1.5,4,7.25 # 显式关键帧时间戳

在 lint 和 validate 之后使用,尤其适用于包含对话气泡、卡片、字幕或紧凑排版的作品。它会报告:

  • 文本扩展到最近的视觉容器或气泡之外
  • 文本被自身固定宽/高的框裁剪
  • 文本扩展到组合画布之外
  • 子元素逃离裁剪容器

错误应在渲染前修复。警告会呈现给 Agent 审查;添加 --strict 可在警告时也让构建失败。重复的静态问题默认会折叠,以便 JSON 输出在 LLM 上下文中保持紧凑。如果溢出是入场/出场动画所必需的,请在元素或祖先上标记 data-layout-allow-overflow。如果装饰元素不应被检查,请标记 data-layout-ignore。

npx hyperframes layout 仍可作为同一次视觉检查的兼容别名使用。

预览

npx hyperframes preview                   # 服务当前目录
npx hyperframes preview --port 4567       # 自定义端口(默认 3002)

文件更改时热重载。自动在浏览器中打开 Studio。

当将项目交还给用户时,请使用 Studio 项目 URL,而不是源 index.html 路径:

http://localhost:<port>/#project/<project-name>

使用预览输出中的实际端口和项目目录名称。例如,在 codex-openai-video 中执行 npx hyperframes preview --port 3017 后,报告 http://localhost:3017/#project/codex-openai-video。

将 index.html 仅视为源代码上下文。作为实现文件链接是可以的,但不要将其标记为项目或预览界面。

渲染

npx hyperframes render                                # 标准 MP4
npx hyperframes render --output final.mp4             # 命名输出
npx hyperframes render --quality draft                # 快速迭代
npx hyperframes render --fps 60 --quality high        # 最终交付
npx hyperframes render --format webm                  # 透明 WebM
npx hyperframes render --docker                       # 字节一致
标志选项默认值说明
--output路径renders/name_timestamp.mp4输出路径
--fps24, 30, 603060fps 会使渲染时间加倍
--qualitydraft, standard, highstandarddraft 用于迭代
--formatmp4, webmmp4WebM 支持透明背景
--workers1-8 或 autoauto每个工作线程启动一个 Chrome
--docker标志off可重现的输出
--gpu标志offGPU 加速编码
--strict标志offlint 错误时构建失败
--strict-all标志off错误和警告时构建失败

质量指南: 迭代时使用 draft,审阅时使用 standard,最终交付时使用 high。

转录

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt   # 导入现有字幕
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

文字转语音

npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list  # 显示所有语音

故障排除

npx hyperframes doctor       # 检查环境(Chrome, FFmpeg, Node, 内存)
npx hyperframes browser      # 管理捆绑的 Chrome
npx hyperframes info         # 版本和环境详情
npx hyperframes upgrade      # 检查更新

如果渲染失败,请先运行 doctor。常见问题:缺少 FFmpeg、缺少 Chrome、内存不足。

其他

npx hyperframes compositions   # 列出项目中的组合
npx hyperframes docs           # 打开文档
npx hyperframes benchmark .    # 基准测试渲染性能

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

govindgoel2001/video-editing-toolkit

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

govindgoel2001/video-editing-toolkit

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, and registry discovery.

govindgoel2001/video-editing-toolkit

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

相关技能