用 Codex 自动剪辑：HyperFrames 从素材整理到 MP4 成片的完整实操

用桌面理线器做一条 30 秒海外产品介绍视频：安装环境与 Skill、整理真实素材、编排时间线、制作英文字幕、预览修改和导出。附完整提示词、中文流程图、常见报错处理与交付清单，免费阅读全文。

这一篇，我带你把自己拍的产品素材整理成一条 30 秒竖屏介绍视频。最后要拿到四样东西：能播放的 MP4、可继续修改的 HyperFrames 项目、镜头与字幕清单，以及导出检查记录。换产品时，保留项目结构、替换素材和文案，再让 Codex 调整时间线，就不用每次从空白开始。

这里用桌面理线器演示：桌面电线散乱 → 把线放进理线器 → 展示整理后的桌面。第一版只做英文屏幕文案，不做配音；背景音乐有合适授权素材才加。先把结构和画面跑通，再做花哨的效果。

01 · 先弄清楚它在帮你做什么

Codex 负责理解需求、整理素材、写脚本和项目文件；HyperFrames 负责把 HTML、CSS、媒体和可按时间定位的动画渲染成视频。HTML 是视频画面的源文件，不是最终成片。常见项目还会有配置、分镜文件、素材和子场景，并不一定只有一个 HTML。

它适合产品介绍、图文动画、教程演示、已有片段的拼接和版本改稿。给它一句话可以开始任务，但素材、卖点和目标用户越清楚，第一版才越接近你要的结果。长口播的精细去口癖、多机位同步和复杂调色，需要另外准备对应工具和操作流程，不要默认一句话全能完成。

HyperFrames 来自 HeyGen 的公开仓库，目前使用 Apache-2.0 开源许可。软件许可和素材授权是两件事：你拍的产品素材、音乐、字体和品牌标识仍需确认使用权。本文命令按 2026 年 10 月 7 日的 CLI 0.8.139 和官方文档核对；本机已核对版本、命令帮助和环境诊断，下面的产品镜头、时间线和英文文案是可替换练习方案，未把整条产品视频的导出写成已实测成果。

02 · 准备账号、电脑和四个工具

准备一台可运行 Codex 和 Node.js 的电脑、能正常使用的 Codex 账号，以及可用网络。本文免费阅读；Codex 的账号方案和额度按你当前账号为准。HyperFrames 的本地渲染不要求你购买 HeyGen 数字人套餐，但额外的生图、配音、音乐生成和云渲染可能涉及其他服务或费用，这篇不需要调用它们。

四个基础工具是：Codex、Node.js 22 或更高版本、FFmpeg（通常同时包含 FFprobe）、HyperFrames 使用的 Chrome。Docker、语音转写和音乐生成模型不是这次入门必装项。先看诊断中的具体项目，不要因为可选项没装就把所有工具装一遍。

Codex：先完成账号登录，在电脑上能新建任务、打开本地文件夹。未安装的可先看下面这篇入门教程，再回来继续。

Node.js：到官方页面下载适合系统的 LTS 安装程序，确认版本不低于 22。安装后关闭并重新打开终端；Windows 用 PowerShell，Mac 用“终端”。以下命令一行一行执行，不要把所有结果当成一条命令复制。

Codex 从 0 到 1：安装登录、常用功能与出海实操

Node.js 官方下载

node --version
npm --version
npx --version

完成标准：node 输出 v22、v24 或更高的受支持版本，npm 和 npx 都能输出版本号。如果出现“command not found”或“不是内部或外部命令”，先重新打开终端；还不行，就让 Codex 检查 PATH 和安装位置。不要把服务器密钥或你的账号密码发进聊天。

FFmpeg：Mac 已安装 Homebrew 的，可以执行下一条命令；没安装 Homebrew 的，先按其官网安装说明处理。Windows 从 FFmpeg 官方下载页进入提供的 Windows 构建，解压后把包含 ffmpeg.exe 和 ffprobe.exe 的 bin 文件夹加入 PATH，再重开 PowerShell。不要在 Windows 里执行 brew。

brew install ffmpeg

FFmpeg 官方下载

Homebrew 安装说明

ffmpeg -version
ffprobe -version
npx hyperframes@latest --version
npx hyperframes@latest doctor

第一次运行 npx，npm 可能询问是否下载官方包，检查包名是 hyperframes 后再继续。doctor 会检查 Node、磁盘、FFmpeg、Chrome 等项目。确认本次需要的基础项可用；转写、TTS、音乐模型和 Docker 等可选项没装，不影响先做无配音版本。

如果提示找不到渲染用的 Chrome，可以执行下面的 browser ensure，让 HyperFrames 查找或下载它使用的浏览器。下载可能较大，首次安装也可能慢；看到下载进度时不要重复开几个相同任务。

npx hyperframes@latest browser ensure

03 · 安装 Skill，再新建视频项目

我建议先安装 HyperFrames 的核心 Skill，让 Codex 按它的时间线和渲染规则写项目，而不是随手写一个普通网页。下面的 update 会从项目当前仓库安装或更新核心技能，不是视频生成命令。首次操作可能需要网络和安装确认；完成后重新打开 Codex 任务，检查是否能读取 hyperframes 技能。

如果你已经安装过，也先核对版本；旧项目可能固定在旧 CLI，不能只更新技能、忽略项目版本。

npx hyperframes@latest skills update

接着打开你准备放项目的父文件夹，在那里新建一个叫 cable-organizer-video 的项目。命令会创建目录，进入目录后再预览或导出。名称暂时用英文和短横线，减少新手复制路径时的错误。

已有同名文件夹时，先换一个新名字或打开旧项目检查，不要覆盖旧成果。--resolution portrait 表示 1080×1920 竖屏；--non-interactive 让初始化使用参数，不进入交互问答。

npx hyperframes@latest init cable-organizer-video --resolution portrait --non-interactive
cd cable-organizer-video

让 Codex 把这个文件夹作为当前项目打开。你应该能看到 index.html 和项目配置等文件，具体附带文件以当前版本为准。后面提到“在终端运行”，都是在这个项目目录里执行。Codex 可以帮你运行本地命令，但预览后的修改和最终导出仍需要你确认。

请检查当前 cable-organizer-video 项目，不要制作视频内容。
1. 确认工作目录正确，列出实际存在的配置和入口文件。
2. 读取可用的 hyperframes 技能；如果读不到，说明缺失位置和安装方式，不要假装已经读取。
3. 检查 Node.js、FFmpeg、FFprobe 和 Chrome 是否满足本地渲染需要。
4. 如果项目 scripts 固定了 HyperFrames 版本，列出该版本；按官方 upgrade --project . --check 核对升级状态。
5. 只处理本地准备；不使用云渲染，不调用收费模型，不提交任何外部反馈。
最后给我一个“可继续 / 缺少什么”的结果。

04 · 拍三段素材，别让 AI 猜产品

案例面向在家办公、桌面线材多的海外用户，内容只讲一个问题：线容易掉下桌，拿取和整理不方便。先确认你的实物确实能完成演示，不能因为练习文案提到“固定线材”，就默认任何理线器都适用。

手机竖屏拍三段，每段约 8—10 秒，尽量使用 1080p、30fps，光线和机位保持一致。第一段拍凌乱桌面和线掉下去的过程；第二段拍安装、放线和取线；第三段拍整理后的桌面。动作慢一点、完整一点，前后各留一秒。不要拍成三个只有产品摆着不动的镜头。

素材这样命名：01-problem.mp4、02-demo.mp4、03-result.mp4，再补一张清晰产品图 product.jpg。放在项目的 assets 文件夹里；没有就请 Codex 创建。安装方式、适用线径、材质、价格和链接写到 product-facts.md，没有确认的内容写“待确认”。

音乐不是必需素材。如果有商用授权，命名为 bgm.mp3，保存来源和许可说明；没有就先做静音版。没有真实视频时，可以用自己拍的图片做图文动画版，但要明确它没有展示真实操作过程，不要让 AI 伪造使用前后效果。

请先整理素材，不要写成片，也不要改动原素材。
产品：桌面理线器；目标用户：居家办公、桌面线材多的海外用户。
唯一已确认卖点：以我实物演示和 product-facts.md 为准，其余字段保留待确认。
请读取 assets 中实际存在的 01-problem.mp4、02-demo.mp4、03-result.mp4 和 product.jpg。
使用 FFprobe 核对每个视频的时长、尺寸、帧率和音轨，记录文件是否能解码。
如果具备实际逐帧查看能力，抽查开头、中间和结尾再描述画面；否则明确没有看过内容，不根据文件名猜镜头。
生成 assets-audit.md：文件名、实际参数、可用时段、主体位置、风险、缺少素材。
竖屏尺寸或帧率不一致时先提出统一方案，保留原文件，只生成工作副本。
音乐只使用已授权 bgm.mp3；缺失则记录无音乐，不调用生成服务。

这一关完成后，你要能回答：每个视频有多长，哪一段能用，安装动作有没有拍全，裁成竖屏会不会切掉手和产品。assets-audit.md 里如果只有“素材不错”四个字，继续让它给出文件名和时间范围。以你实际看过的素材确认镜头内容，不能把文件参数检查当成画面审看。

05 · 先定 30 秒结构，再写英文文案

我会把第一版分成六段，先给 Codex 明确时间预算，再让它根据真实素材选镜头。

0—3 秒：线掉下桌的烦恼，开头文案“Still chasing your charger cable?”。
3—8 秒：展示产品和真实安装方式。
8—16 秒：完整演示把线放进去、拿出来。
16—23 秒：前后桌面同机位对比，不虚构效果。
23—27 秒：产品近景，只写一个已确认卖点。
27—30 秒：收尾，使用“See how it works.”或你的真实产品页引导。

这六段是排片练习，不是播放或转化保证。素材不够覆盖指定时段时，缩短动作片段、插入真实产品图或调整节奏，别靠重复画面硬凑。

读取 product-facts.md 和 assets-audit.md，先生成 storyboard.md 和 captions.md，不要写 HTML，不要渲染。
目标：1080×1920、30 秒、英文屏幕文案、给居家办公用户看的桌面理线器介绍。
按 0—3、3—8、8—16、16—23、23—27、27—30 秒分六段。
每段列出：成片起止、源文件、素材内入点与出点、画面任务、英文文案、中文解释、是否需要补拍。
英文短句一次只讲一个意思，每屏最多两行，不使用 best、guaranteed 或无法证明的性能承诺。
保留完整安装和取线动作，不做动作中途硬切；前后对比保持同机位。
必须区分“源视频第几秒”和“成片第几秒”。未知材质、价格、线径、承重和认证不写进文案。
音乐无授权就不加，第一版不要配音和 AI 生成素材。
最后检查总时长恰好 30 秒、所有源区间都在文件时长内，并让我确认这个方案。

看方案时，重点检查第二段是否真的有安装素材，第四段前后是不是同一个桌面，字幕有没有夸大产品。没有问题，再告诉 Codex“按这个分镜继续”。如果你想换开头，只改前三秒的画面和文字，别把已经确认的全片重写。

06 · 让 Codex 制作可渲染项目

接下来再让它把分镜落实到项目中。最重要的要求是“可按任意时间定位”：预览到第 12 秒、导出第 12 秒，都应该出现相同的画面。普通网页里靠 setTimeout 或滚动触发的动画，并不一定能正确变成视频。

让 Codex 读取 HyperFrames 的核心规则，使用框架支持的时间线、媒体区间和可定位动画。不要在项目里混用好几套互相抢控制权的播放器。图片、视频和字体尽量用本地文件，避免渲染时外链加载失败。

使用 hyperframes 技能，读取当前项目规则和已确认的 storyboard.md、captions.md、assets-audit.md，制作这一条 30 秒竖屏产品视频。
要求：
1. 使用真实 assets 素材；不得调用云渲染、付费生成、素材搜索购买或外部反馈。
2. 画布 1080×1920，30fps，总时长 30 秒。成片与源素材区间按分镜对应。
3. 使用 HyperFrames 支持的时间属性、框架管理的媒体播放和可 seek 的动画；不要写普通网页定时器充当视频时间线。
4. 镜头切换简洁，保留真实动作，不乱改产品颜色、结构和效果。文字轻量入场，禁止全程跳动。
5. 英文文案最多两行，重要内容避开右侧平台按钮区和底部字幕区；第一版参考留白：左右约 90 像素、顶部约 180、底部约 280，最终以目标平台手机预览为准。
6. 背景音乐只有已授权 bgm.mp3 才使用；默认不做配音。不要让原素材嘈杂音轨突然盖过音乐。
7. 保留原素材；列出每个实际修改文件，不覆盖已存在的导出版本。
8. 首轮做静态 lint，结构完成后运行 check --snapshots，修正持续的错位、遮挡、缺失素材和对比度问题。
9. 检查通过后启动本地 Studio，给我命令实际输出的预览地址。先停在预览，不自动导出。

如果 Codex 给你的只是“已经完成”，让它列出文件和检查结果。看到一个 HTML 文件不等于视频可用，check 也不能替代完整观看。如果检查报告显示 browserSkipped，说明浏览器那部分没有运行，不能当成画面检查通过。

07 · 打开预览，按时间点提修改

npx hyperframes check --snapshots
npx hyperframes preview --background

复制命令实际输出的 Studio 地址，在浏览器打开。默认预览常用 3002 端口，但端口占用时可能不同，以终端输出为准；地址会包含类似 #project/cable-organizer-video 的项目部分，别只复制 localhost 的前半截。预览服务需要保持运行，关闭后地址就打不开。

先从头到尾播放一次，再跳到 0、3、8、16、23、27 秒检查切换。关注手和产品有没有被裁掉、文案是否太长、动作是否完整、音乐是否突然变响。手机尺寸查看时仍要能读清文案，不能只在大屏电脑上觉得好看。

只修改当前这条视频，不重做整套风格：
1. 0—3 秒开头保留原画面，把英文改成“Your cable keeps disappearing?”，最多两行。
2. 8—16 秒的安装演示不要切掉手指，把产品和操作手完整保留；先核对实际源素材，再调整裁切。
3. 16—23 秒前后对比的文字移到上方，别挡住理线器。
4. 27—30 秒结尾保留 3 秒阅读时间，不追加未经确认的价格和链接。
其他已确认的素材、节奏和总时长保持。列出改动，再运行 check 并更新预览；仍不要渲染。

“高级一点”很难执行；“第 8 秒把产品放大到能看清安装、保留完整手势、字幕移到上方”就具体得多。改完以后重新拖动进度验证，特别留意向后跳再向前跳时，动画会不会停在错误位置。

08 · 确认画面后，导出第一版 MP4

先做草稿导出，确认渲染流程和实际成片；通过后再导出交付质量。下面的 --output 指定文件名，避免不同版本混在一起。要在项目目录里运行，输出放在 renders 中；若目录不存在，请 Codex先创建。不同电脑和素材的渲染速度差别很大，不承诺几秒完成。

新建项目可能带有固定 CLI 版本的 npm scripts。先确认 scripts，已经固定版本的项目用它的 render 脚本或同一个固定版本 CLI，并保留质量与输出参数，别在同一项目里无意混用多个版本。下面的 npx 命令是未指定其他包装脚本时的标准写法。

npx hyperframes render --quality draft --fps 30 --output renders/cable-organizer-v1-draft.mp4
npx hyperframes render --quality delivery --fps 30 --output renders/cable-organizer-v1.mp4

两条不是必须连续执行：先运行第一条，打开草稿看完；需要修改就回到 Codex，别继续第二条。草稿没问题，再导出 delivery。只想试一下效果，停在草稿也可以。

预览我已确认，现在只做本地草稿渲染。
使用项目固定的 HyperFrames 版本，30fps，quality draft，输出 renders/cable-organizer-v1-draft.mp4。
如果同名文件存在，另存 v2，不覆盖。不要调用云渲染或付费服务。
完成后用 FFprobe 核对时长、分辨率、帧率和音轨，告诉我结果；再用播放器从头播放检查。
若无法实际观看或监听，明确说明未做画面/听感验收，不要写“已确认效果完美”。先停在草稿交付，不自动发布到平台。

09 · MP4 出来了，还要检查这六件事

ffprobe -v error -show_entries stream=codec_type,width,height,avg_frame_rate:format=duration,size -of json renders/cable-organizer-v1.mp4

第一，看文件非空，播放器能打开，不只是终端显示成功。第二，时长约 30 秒，尺寸 1080×1920，帧率按目标设置；avg_frame_rate 的 30/1 就是每秒 30 帧。第三，从头播放到结尾，开场不黑屏、动作不跳帧、收尾不突然截断。第四，字幕拼写正确，手机上清楚，没被平台按钮挡住。第五，有音乐时听完整条，确认不爆音、不忽大忽小；无音乐版本没有音轨属于预期。第六，产品卖点、音乐和图片授权、目标页面链接都确认过。

FFprobe 只检查文件参数，不证明画面好看、内容正确或声音正常。做完这些再记录“已审片”，不要把渲染成功直接写成用户已经可以投放。

10 · 常见卡点，按这个顺序处理

npx 找不到 / Node 版本太低：先看 node --version 和 PATH，重开终端；不要在错误环境里反复运行 render。

依赖下载很慢：第一次要下载 npm 包或 Chrome，先看具体下载状态和网络；不重复启动多个安装。国内网络下失败不代表项目本身失效，不使用来路不明的包和镜像。

FFmpeg 或 FFprobe 缺失：先装好并确认命令有版本输出，再运行 doctor；只装视频播放器并不会补上 FFmpeg。

图片缺失 / 视频黑屏：检查大小写、扩展名和 assets 路径，先用本机播放器打开源文件，再看 check 的网络和解码错误。预览里能播放不代表每个渲染采样都就绪。

动画预览正常、导出不动：让 Codex 检查是否使用可 seek 的时间线和框架媒体规则，尤其是普通定时器、自动播放和多播放器冲突；不要靠把等待时间加长来掩盖结构问题。

文字越界或被挡：让 Codex 标出报错时间、选择器和文字框，改字号、换行、留白，别只把所有警告忽略。

渲染太慢或内存不足：关掉不用的程序，先 quality draft；必要时尝试 --workers 1，减少同时启动的 Chrome 数量。素材过大先转工作副本，不改原文件。

Chrome 无法启动：先 doctor。若错误明确是当前代理沙箱不允许启动浏览器，交给你在本机终端执行相同命令；不要关闭安全保护，也不要把静态检查当成视频检查。需要云渲染时另确认服务和费用，这篇先不走云。

当前 HyperFrames 操作失败，请只诊断这一项，不重做项目。
失败命令：[粘贴实际命令]
错误原文：[粘贴相关几行，删除个人路径、密钥与账号信息]
请检查当前目录、CLI版本、必要依赖、源文件路径、check报告中的具体时间与选择器。
先判断属于环境、素材、时间线还是渲染资源问题，说明依据，再给出最小修改。
保留原素材和已通过的场景；不要忽略全部警告，不关闭安全保护，不调用收费服务，不提交外部反馈。
修复后复跑同一检查，说明实际通过了哪一项、还有哪一项未验证。

换素材后导出失败，先检查项目和版本

保留第一版能正常导出的项目，再换素材。把视频、配音、图片集中放到项目的素材目录，使用能看懂的文件名；网页里能显示一张外链图片，不代表离线渲染一定能读到它。原始文件改名或移动后，先检查引用路径，不要反复重装软件。

开始排查前，让 Codex 列出当前工作目录、项目入口、正在使用的 HyperFrames 版本、运行命令和实际报错。当前官方文档支持通过 npx hyperframes skills update 更新核心技能，但更新技能和升级已有项目的渲染依赖不是同一件事。已有项目先保留能工作的版本与配置，不为修一个素材路径错误顺手全部升级。

只在预览里看到画面，还要检查时间轴拖到中间、回到开头、重新打开后，字幕与动画是否仍在正确时间出现。导出后从系统播放器打开 MP4，确认它不是旧文件，也不是空文件或只有首帧。保留源项目、成片、素材清单和版本说明；下次改价格或换产品时，从副本修改，不覆盖已交付版本。

请诊断当前 HyperFrames 项目，先不升级依赖、不覆盖旧成片。
确认工作目录、入口文件、CLI 与项目锁定版本、素材引用以及本次失败命令。
先区分：找不到文件、素材无法解码、字体缺失、预览动画不能正确跳转、音频或时长配置、渲染器启动失败。只根据实际日志判断，不编造已通过的检查。
保留原版，只修定位到的原因；用现有版本做一次草稿导出，保存新文件名。打开成片检查画面、声音、字幕和时长，列出仍需人工确认的项目。若需要付费服务、上传素材或升级依赖，先说明原因和影响。

11 · 换成你的出海业务，不必每次重做

跨境电商：保留“问题 → 使用 → 结果 → 近景 → 引导”结构，换成真实产品。先做自然内容版，决定投广告前再核对目标平台的规格和宣传要求。

外贸和工厂：换成“应用场景 → 工序 → 质量检查 → 交付展示”，用厂内真实素材；认证、产能和交期只写有依据的内容。第一条可以没有配音，把工序标题写清楚。

个人 IP 和知识付费：用课程截图、方法步骤或获授权片段做介绍。长口播先有准确转写和时间范围，再安排删减，别让模型凭印象剪掉观点。

做多语言时，先复制项目版本，再翻译字幕、调整换行和镜头停留时间。只替换字幕不等于完成配音或口型同步；这篇的英文版本指屏幕文案，不包含声音译制。

以已经确认的 cable-organizer-video 项目为基础，另存一个新产品版本，不修改原项目。
新产品：[名称]
目标市场与用户：[填写]
真实卖点：[仅列已确认事实]
新素材位置：[填写路径]
保持 30 秒、9:16、六段结构；先检查新素材，再更新分镜和英文字幕，不直接批量导出。
列出不能复用的镜头、需补拍素材、需要重写的事实和字幕。
确认之后再改项目，检查通过后给预览；不会自动发布，也不调用付费生成。

12 · 做完后，对照这份清单

□ Codex 能读取项目与 HyperFrames Skill，Node、FFmpeg、FFprobe、Chrome 的必要检查可用。
□ 产品事实和素材来源清楚，原文件保留备份。
□ 每段都写清源素材入出点与成片起止，时间总计 30 秒。
□ 没有编造材质、价格、认证或使用效果。
□ check 已实际执行，浏览器检查没有被跳过；持续的错误已处理。
□ Studio 完整播放与前后拖动都正常，手机上文案清楚。
□ MP4 能打开，时长、尺寸、帧率符合要求。
□ 有音乐时已实际听完，无音乐时明确是静音版本。
□ 字幕、素材授权和目标链接复核过，没有自动发布。
□ 保留分镜、字幕、工程、成片和审片记录，下一条可以继续改。

官方资料与后续更新

HyperFrames 官方仓库与开源许可

HyperFrames 官方入门文档

HyperFrames 官方文档

如果你想跟着视频把这套流程用到自己的产品上，可以加入 AI 超级玩家出海营销圈。圈内有更详细的视频教程、内部课程和答疑指导，做素材整理、内容制作和出海业务时，卡住的地方可以一起拆解。先把这篇免费教程里的第一条视频做出来，再带着具体问题继续交流。