HyperFrames CLI 成片管线全指南：preview、play、render、publish 命令深度解析（OpenMontage 视角）

HyperFrames CLI 成片管线全指南preview、play、render、publish 命令深度解析OpenMontage 视角【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontageHyperFrames 是 OpenMontage 中与 Remotion、FFmpeg 并列的三条render_runtime之一负责把 HTML/CSS/GSAP 组合composition以确定性的逐帧 seek-capture 方式渲染为视频。本文围绕 HyperFrames CLI 的四大成片命令——previewStudio 预览、play轻量播放、render正式渲染、publish发布分享链接逐一拆解命令形态、端口约定、全部渲染参数及其底层机制并结合仓库内的 hyperframes-cli 技能、hyperframes-core 技能 与 hyperframes_compose 工具 的源码证据展开。读完本文你将能够独立走通预览 → 评审 → 渲染 → 发布的完整交付链路并掌握参数化渲染、外部浏览器/CDP 附加等进阶用法。一、先建立整体认知这条命令链在 OpenMontage 中的位置在 OpenMontage 中每个成片项目会经历brief → script → scene_plan → edit_decisions → compose → render的流程而render_runtime取值为remotion、hyperframes、ffmpeg在提案阶段即被锁定并写入 proposal_packet.schema.json 的决策日志。当选择 HyperFrames 后compose 阶段由tools/video/hyperframes_compose.py负责工作区物化并驱动 HyperFrames CLI其在 OpenMontage 中的工作目录结构如下projects/project-name/ ├── hyperframes/ # HyperFrames 运行时工作区 │ ├── index.html # 根组合root composition │ ├── compositions/ # 子组合与 registry 组件 │ ├── assets/ # 项目素材拷贝或软链 │ └── hyperframes.json # CLI 配置 └── renders/ # 渲染输出关于运行时的选择矩阵、可用性探测Node.js ≥ 22、PATH 上存在ffmpeg、npx hyperframes doctor通过等细节可参考 skills/core/hyperframes.md。本文聚焦这条链路中面向人类评审与最终交付的命令面Servepreview/play、Render、Sharepublish。在深入命令之前需要先明确本仓库中 HyperFrames 技能的分层.agents/skills/hyperframes-cli/负责 CLI 用法含本主题对应的 preview-render.md.agents/skills/hyperframes-core/负责组合书写契约data-*时间轴属性、轨道、子组合、确定性渲染.agents/skills/hyperframes-animation/等负责创意动效。它们是同一事物的命令面与书写面。二、preview启动 Studio 评审面而不是一个播放器preview是 Serve 命令中的重头戏它的定位与普通静态预览有本质区别它打开的是完整的 Studio 时间线编辑器——用户可以播放视频也可以在渲染前用手工方式编辑任何东西。文档中特别强调这是评审面review surface不只是查看器viewer。npx hyperframes preview # serve 当前目录 npx hyperframes preview --port 4567 # 自定义端口默认 3002特性要点默认端口 3002可通过--port覆盖为任意可用端口。文件热更新Hot-reload组合源文件发生变更时自动刷新无需手动重启。自动打开浏览器命令执行后会自动在浏览器中打开 Studio。交接项目时请交付 Studio 项目 URL这一点是 Agent 协作规范中的硬性约定当把一个 HyperFrames 项目交还给用户评审时应给出Studio 项目 URL而不是源index.html的路径http://localhost:port/#project/project-name其中port为实际启动端口project-name为项目目录名。例如在codex-openai-video目录下执行npx hyperframes preview --port 3017后应向用户报告http://localhost:3017/#project/codex-openai-video#project/name是 Studio 专属的路由约定。请始终把index.html视为源代码上下文而不是预览面本身。三、play可嵌入的轻量播放器当评审不需要编辑器与面板时play是比 Studio 更轻的选择它通过可嵌入的hyperframes-playerWeb Component 来 serve 组合而不是完整的 Studio UI。npx hyperframes play # 当前项目端口 3003 npx hyperframes play ./my-video # 指定项目 npx hyperframes play --port 8080 # 自定义端口与preview的关键差异默认端口 3003与 preview 的 3002 不同。返回普通 URLplay报告的是朴素的http://localhost:port没有#project/name片段——那是 Studio 路由约定仅preview使用。适合分享一个预览链接或Studio 过重无编辑器、无面板的场景。playback-rate 的钳制规则播放器暴露playback-rate属性作为预览速度控制它驱动时间线的timeScale。其取值被钳制在[0.1, 5]区间内任何≤ 0或非有限NaN/Infinity的值都会回退为1。需要特别注意的是这是一个预览/播放旋钮不是组合的data-*属性。也就是说无论评审时以几倍速预览组合中的已创作动效在正式渲染时仍以1×正常速度产出预览变速不会污染最终渲染结果。这一点与># 在隔离的 Chromium profile 中打开 preview npx hyperframes preview --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile # 同样的配置外加 :9222 上的 CDP 端点可附加 DevTools / Playwright 等 npx hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222一个值得强调的健壮性设计校验发生在任何服务器启动之前。因此一旦参数非法命令会在不留下任何监听 socket 的情况下干净退出不会出现端口已占/进程残留的脏状态。五、render唯一通向交付文件的大门5.1 铁律先评审后渲染HyperFrames 的渲染门禁非常明确文档原文为Render only after the user has reviewed inpreviewand approved. Dont auto-render when the checks pass.这条规则同时以 Agent 约定形式固化在 hyperframes-cli/SKILL.md 中Render is user-gated. 即使 lint/validate/inspect 全部通过也必须暂停在 preview告知用户视频可在 Studio 中编辑只有获得用户批准后才渲染。在 OpenMontage 的自动化管线中这意味着hyperframes_compose工具的 render 操作必须被编排在人工/决策闸门之后。5.2 常见渲染形态一览npx hyperframes render # 从 cwd 渲染标准 MP4 npx hyperframes render ./my-video --output ./out.mp4 # 在项目目录外渲染 npx hyperframes render --output final.mp4 # 指定稳定输出名无时间戳 npx hyperframes render -c compositions/intro.html -o intro.mp4 # 渲染某个子组合文件 npx hyperframes render --quality draft # 快速迭代 npx hyperframes render --fps 60 --quality high # 最终交付 npx hyperframes render --format webm # 透明 WebM npx hyperframes render --docker # 字节级一致输出5.3 默认输出路径约定默认--output为renders/project-name_YYYY-MM-DD_HH-MM-SS.ext——每次渲染都打时间戳因此连续多次运行互不覆盖。需要稳定文件名时通过--output显式指定。5.4 渲染参数全表Flag选项默认说明dir位置参数pathcwd项目目录省略时使用当前工作目录。--composition,-c组合文件路径index.html渲染指定组合文件如compositions/intro.html代替项目的index.html。--output,-opathrenders/project_ts.ext输出路径默认带时间戳。--fps24, 30, 603060fps 会使渲染时间加倍。--qualitydraft, standard, highstandarddraft 用于迭代。--formatmp4, webm, mov, gif, png-sequencemp4WebM/MOV 支持透明gif 用于 GitHub PR/README/文档中的内联自动播放两遍调色板编码fps 上限 30——建议用--fps 15无音频仅 1-bit 透明HDR 回退为 SDRpng-sequence 向目录写入 RGBA 帧供 AE/Nuke/Fusion 摄取。--gif-loop0-655350GIF 循环次数0表示无限循环。仅配合--format gif。--resolutionlandscape, portrait, landscape-4k, portrait-4k, square, square-4k另有别名1080p、4k、uhd—通过 ChromedeviceScaleFactor超采样。宽高比必须与组合匹配缩放必须是整数。不能与--hdr同用。--crf0-51—编码器 CRF值越低画质越高。与--video-bitrate互斥。--video-bitrate如10M、5000k—目标码率。与--crf互斥。--hdrflagoff即使源是 SDR 也强制 HDR 输出。仅限 MP4。--sdrflagoff即使源是 HDR 也强制 SDR 输出。--workers数字或autoauto每个 worker 会派生一个 Chrome 进程约 256 MB 内存。--dockerflagoff跨主机可复现输出。--gpuflagoffGPU 加速的 FFmpeg 编码NVENC / VideoToolbox / VAAPI / QSV。--browser-gpu/--no-browser-gpuflagauto本地/ offdocker为 Chrome/WebGL 捕获使用主机 GPU。--browser-timeout秒0.001–8640060Puppeteer 对入口 HTML 的页面导航超时。当重型组合大量视频/字体/远端资源在默认 60s 内到不了domcontentloaded时应调大。--quietflagoff抑制冗长输出。--strictflagoff在 lint 错误时失败。--strict-allflagoff在 lint 错误和警告时都失败。--variablesJSON 对象—覆盖data-composition-variables中声明的值。--variables-filepath—存放变量值的 JSON 文件--variables的替代方案。--strict-variablesflagoff当--variables中出现未声明键或类型不匹配时使渲染失败。质量档位经验法则迭代用draft评审用standard最终交付用high。5.5 参数化渲染一份组合任意取值HyperFrames 的参数化机制很容易混淆因为涉及两种不同的 JSON 形态声明schema组合在html根元素上用data-composition-variables声明变量——它是一个JSON 数组每条是{id, type, label, default}。它定义了组合的可变参数契约。取值valuesCLI 的--variables {title:Q4 Report}是以 id 为键的 JSON 对象针对某一次渲染覆盖已声明的默认值未提供的键会自然回落fall through。一个声明示例详见 variables-and-media.mdhtml >const { title, accent } window.__hyperframes.getVariables(); document.getElementById(title).textContent title; document.documentElement.style.setProperty(--accent, accent);支持的变量类型及其额外选项供 Studio 编辑 UI 使用string可选placeholder、maxLength、number可选min、max、step、unit、color无、boolean无、enum必须提供options: [{ value: ..., label: ... }, ...]。由于缺失键会回落同一组合可以在 dev 预览与生产渲染中无改动地运行——这是一份源、多取值的关键设计。此外子组合宿主host也可以用data-variable-values做按实例的覆盖CI 中建议加--strict-variables把未声明键、类型不匹配、不在options里的枚举值从警告升级为错误。完整的书写模式见 hyperframes-core/SKILL.md 与 composition-patterns.md。从仓库实现看data-composition-variables声明落在html根上而单个可渲染组合的根元素则是带data-composition-id/data-width/data-height/data-duration的divGSAP 时间线需以 paused 状态创建并注册到window.__timelines[id]——最小可渲染组合的完整形态可参考 minimal-composition.md。正是这套时间线确定性注册契约保证了渲染器可以脱离交互按时间轴逐帧 seek 捕获也让--docker能实现跨主机字节级一致。5.6 关于 render 的 Agent 协作约定结合 hyperframes-cli/SKILL.md 的跨命令约定围绕render还需注意三点--json在render、preview、play上不可用其余命令均可。render只通过 stdout 退出码报告状态因此 Agent/CI 需要在渲染返回后主动做一次文件自检。渲染后校验render返回 exit 0 后先确认输出文件存在且大小合理再报告成功[ -s $OUTPUT ] || echo render produced no output长渲染还建议用ffprobe -i $OUTPUT -show_format -v error核对时长。视频密集组合用--workers 1从 OpenMontage 侧积累的实践看skills/core/hyperframes.md当组合包含超过 5 个背景视频元素时默认并行捕获会压垮 headless Chrome始终显式传--workers 1。六、publish上传源文件并拿到公开 URLnpx hyperframes publish # 上传当前项目返回公开 URL npx hyperframes publish ./my-video # 上传指定项目 npx hyperframes publish --yes # 跳过确认提示用于脚本/CIpublish会上传项目的源文件HTML 素材并返回一个可在浏览器中渲染的稳定公开 URL。它适合两种场景在渲染 MP4 之前分享一份草稿供评审把组合嵌入到其他页面中。关于 lint上传前会展示 lint 发现的问题但这些发现不阻塞上传——即 lint findings 只是提示性信息publish 仍然完成。注意与render的差异render产出的是最终媒体文件MP4/WebM 等而publish上传的是可交互、可继续编辑的 HTML 组合源。二者服务不同的交付形态——前者是成片后者是可运行的项目/交互预览。七、最佳实践把它串成一条确定性的交付流水线综合文档、CLI 技能与 OpenMontage 的接入实现推荐如下端到端实践顺序静态闸门先行npx hyperframes lint→npx hyperframes validate涉及子组合的项目再加npx hyperframes inspect与npx hyperframes snapshot用秒级抽帧覆盖index.html的真实挂载路径。静态检查通过不等于渲染可过——跨文件子组合挂载失败只能靠真正加载index.html的检查捕获。Studio 评审npx hyperframes preview打开 Studio向用户交付http://localhost:port/#project/name形式的项目 URL等待批准。迭代渲染批准后用npx hyperframes render --quality draft快速出片自查。交付渲染npx hyperframes render --quality high --output out.mp4或 CI 场景下--docker --strict --output out.mp4追求跨主机可复现。发布分享需要提前分享可交互草稿时用npx hyperframes publish。在这条链路中preview/play负责人看得懂、改得动的评审面render负责确定性、可复现的媒体产物publish负责可嵌入、可分享的项目载体三者各司其职又共享同一份组合源。而 OpenMontage 的 hyperframes_compose.pyversion 0.2.0CORE 层级、BETA 稳定性、本地运行、确定性执行正是以节点 ≥ 22 ffmpeg为依赖、把这套 CLI 封装为可编排工具的落地实现——阅读其源码可以进一步看到hyperframes_render、hyperframes_lint、hyperframes_doctor等能力是如何映射到底层命令的。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考