用 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 超級玩家出海營銷圈。圈內有更詳細的視頻教程、內部課程和答疑指導，做素材整理、內容製作和出海業務時，卡住的地方可以一起拆解。先把這篇免費教程裏的第一條視頻做出來，再帶着具體問題繼續交流。