【2026 最新】HyperFrames 教學：用 Claude Code／Codex 把 HTML 變成可重跑 MP4

你只想改品牌短片的一句標題，卻得重新拉時間軸、對轉場，最後還不確定新版和舊版到底差在哪裡嗎？這篇 HyperFrames 教學要解決的不是「按一下就生成神片」，而是更實際的問題：如何讓影片像程式專案一樣，可以修改、檢查、版本控制，再穩定重跑。

我們會用 Claude Code 或 Codex 當協作代理，讓它直接編輯 HTML、CSS、JavaScript 與素材清單，再由 HyperFrames 輸出 MP4。本文專為第一次接觸程式化影片的讀者寫；你不必先會影片工程，但要願意把「好看」拆成可以檢查的規格。

先說結論：影片能重跑，靠的不是一句 Prompt

最值得記住的公式是：可重跑影片 ＝ 固定原始碼 ＋ 固定素材 ＋ 固定環境 ＋ 固定驗收點。

• 固定原始碼：分鏡、文字、版面與動畫都存在 Git 可追蹤的檔案裡。
• 固定素材：圖片、影片、聲音與字型使用本機檔案，不在 render 中途臨時下載。
• 固定環境：鎖定 HyperFrames、Node、Chrome、FFmpeg 與輸出參數；跨機協作時再用 Docker。
• 固定驗收點：在指定秒數截圖、跑自動檢查、比對 decoded frames，最後由人看完、聽完成片。

HyperFrames 的核心，是把瀏覽器動畫變成可定位時間的畫面。render 不是任由網頁播放再錄螢幕，而是依序跳到每一幀對應的時間、擷取畫面，再交給 FFmpeg 編碼。第 3 秒因此可以被重複檢查，Agent 也能針對「第 3 秒標題超框」修改原始檔，而不是盲猜整支影片。

HyperFrames 是什麼？Claude Code、Codex 又做什麼？

HyperFrames 是用 HTML、CSS、JavaScript 與媒體素材製作影片的開源框架。截至 2026 年 9 月 9 日，npm 最新版為 0.8.31，要求 Node.js 22 以上，程式碼採 Apache-2.0 授權；安裝與格式仍應以官方 repository及最新 Quickstart為準。

Claude Code 與 Codex 不是影片編碼器，而是會讀專案、改檔、執行指令並依錯誤繼續修正的 coding agent。HyperFrames 負責 preview、逐幀擷取與 render；Agent 負責把你的分鏡翻成檔案、修正檢查結果。若你還不確定該選哪一個，可先看 Claude Code vs Codex 客觀比較；想先理解 Agent 為何能持續做事，可讀 AI Agent Harness 是什麼。

Codex 會讀專案中的 AGENTS.md，並可從 .agents/skills載入 Skill；Claude Code 主要讀 CLAUDE.md，專案 Skill放在 .claude/skills。重複規則放指令檔，完整製片流程放 Skill；不要把兩者混成一份超長 Prompt。Codex 的 Skill 呼叫方式是 $hyperframes或從 /skills選取，Claude Code 則使用 /hyperframes。

誰適合這套 HTML 轉 MP4 流程？

適合：文字卡、產品介紹、資料圖表、教學片頭、同一版型的大量變體，以及原本就熟悉 Web 設計的人。這些作品的價值在版面、資訊與一致性，HTML 和設計 token 很好維護。

先搭配別的工具：如果主體是寫實人物、電影鏡頭或生成式 B-roll，可先用影像模型產生素材，再讓 HyperFrames 負責字幕、Logo、版型和合成。想看偏生成式的 Agent 影片工作流，可延伸閱讀 Claude Code AI Video Studio；想做可編輯的動畫網頁，則看 Claude Code 動畫網站教學。

HyperFrames 教學第 1 步：先隔離、安裝，再鎖版本

先建立一個新的 Git 專案，確認 Node.js 22 以上、FFmpeg 與 Chrome 可用。第三方 Skill 能指示 Agent 執行終端命令；安裝前先看內容，並讓所有變更都可用 Git 還原。互動安裝與 Agent／CI 更新是兩條路，選一條即可：

# 人類互動安裝：選 Core Skills
npx skills add heygen-com/hyperframes

# Agent／CI 非互動更新；另可先用 skills check 唯讀檢查
npx --yes hyperframes@0.8.31 skills check
npx --yes hyperframes@0.8.31 skills update

更新 Skill 會追蹤專案目前提供的內容，因此把 HyperFrames repository commit 一起記到 ENVIRONMENT.md；更新後視為一次正式升級，重跑完整驗收。接著用明確版本建立空白專案：

npx --yes hyperframes@0.8.31 init my-video --example blank --non-interactive
cd my-video
npx --yes hyperframes@0.8.31 doctor --json | jq -e '.ok' >/dev/null

init產生的 package.json scripts 會帶著呼叫時的精確 HyperFrames 版本。提交 package.json與 .nvmrc；若另裝 GSAP 等套件，也提交 lockfile。FFmpeg、Chrome、作業系統與 CPU 架構則寫進環境收據。注意：doctor --json能執行不代表環境健康，上面的 jq -e '.ok'才會把檢查結果變成 CI gate。

第一支片先控制在 5～10 秒，只用文字、色塊與一個本機 Logo。確認整條管線能重跑後，再一次加入一種素材：先字型，再圖片，最後才是影片與聲音。這樣出錯時，你知道是哪一層新增依賴，而不是讓 Agent 同時排查十個變數。

第 2 步：先寫 storyboard 與 scene contract

不要只對 Agent 說「幫我做一支很酷的片」。先把腳本拆成 storyboard（分鏡）、scene contract（場景契約）、品牌 token 與素材清單。每幕至少寫開始時間、長度、訊息、素材與可觀察的完成條件：

scene: solution
start: 3
duration: 3
message: 把 HTML 變成可重跑影片
assets:
  - assets/logo.svg
  - assets/product.webp
acceptance:
  - 3.0 秒標題已進場
  - 4.5 秒產品圖完整可見
  - 文字不超框，Logo 保留安全距離

這樣，「更有質感」就會變成可修改的版面與節奏。這和 Agentic Artifact Creation／SlideOps的思路相近：先定義結構和驗收，再讓 Agent 反覆加工。

給 Agent 的起手式：請製作 8 秒、1920×1080、30fps 的三幕產品介紹。只用 assets 內的本機 Logo 與字型；動畫必須能由暫停時間軸 seek。完成後跑 lint、check –strict，並截取第 0、3、7.9 秒。不要在 render 期間抓遠端素材。

第 3 步：集中品牌 token，素材全部本機化

不要讓 Agent 在每一幕各自猜顏色、字級與留白。把品牌規則集中成 token，之後只改一處；把字型放進 assets/fonts並用 @font-face載入，避免依賴某台電腦剛好裝好的字型。

:root {
  --brand-primary: #6c5ce7;
  --brand-ink: #10131a;
  --brand-paper: #f7f7fb;
  --title-size: 96px;
  --safe-x: 120px;
}

@font-face {
  font-family: "BrandSans";
  src: url("./assets/fonts/brand-sans.woff2") format("woff2");
}

正式 render 不要依賴會變動的圖片 URL、Google Fonts、CDN script 或即時 API。先下載、審核，再用相對路徑引用；同時建立 ASSETS.md，記錄檔名、原始網址、作者／權利人、取得日期、授權與 SHA-256。HyperFrames 的 Apache-2.0 授權只涵蓋工具程式碼，不會替照片、音樂、Logo 或字型取得使用權。

第 4 步：把動畫寫成可 seek 的暫停時間軸

可重跑的技術核心是：「給我時間 t，就能算出對應畫面狀態。」composition root 固定 ID、秒數、尺寸與 fps；可見元素是有明確起訖的 clip，GSAP timeline 則保持暫停並同步註冊：

<div id="root" data-composition-id="main"
  data-start="0" data-duration="8" data-fps="30"
  data-width="1920" data-height="1080">
  <div id="title" class="clip"
    data-start="0" data-duration="8" data-track-index="1">
    HyperFrames
  </div>
</div>

<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });
  tl.fromTo("#title", { opacity: 0, y: 40 },
    { opacity: 1, y: 0, duration: 0.6 }, 0);
  window.__timelines["main"] = tl;
</script>

paused: true代表時間由 HyperFrames 控制，不是頁面載入後自己往前跑。render 關鍵路徑避開 Date.now()、未設定 seed 的 Math.random()、執行中的 fetch()、setTimeout()與自由觸發的 CSS transition。要隨機粒子，就先用固定 seed 產生座標並保存；要 API 文案，就先抓取、審核，再寫入本機 JSON。

白話說，攝影機每次喊「第 90 幀」時，所有演員都要能回到同一站位。只會隨真實時鐘往前走的動畫做不到這點；能暫停、能 seek、有有限長度的時間軸才做得到。

HyperFrames 教學第 5 步：preview、check、snapshot、render

第一版完成後，先預覽與定點驗收，最後才花時間輸出：

npm run dev
npx --yes hyperframes@0.8.31 lint
npx --yes hyperframes@0.8.31 check --strict --at-transitions
npx --yes hyperframes@0.8.31 snapshot --at 0,3,7.9 --no-end
npx --yes hyperframes@0.8.31 render \
  --no-best-effort --strict-all --output renders/final-a.mp4
npx --yes hyperframes@0.8.31 render \
  --no-best-effort --strict-all --output renders/final-b.mp4

1. preview讓你播放並拖曳時間軸，檢查節奏與訊息。
2. lint找 HTML 結構、timeline 註冊與素材宣告問題。
3. check --strict --at-transitions檢查 runtime、版面、動態、媒體與對比，也抽查轉場邊界；warning 也會阻擋。
4. snapshot保存開場、每個故事節點、轉場兩側與結尾前一幀。8 秒影片用 7.9 秒比 8 秒更適合看實際尾畫面。
5. --no-best-effort --strict-all讓正式 render 遇到未就緒媒體或 lint warning 時直接失敗，不悄悄交付有警訊的成品。

這些是 gate，不是品質保證。preview 正常、check 全綠，仍可能漏掉短暫閃爍、音畫接縫或一個小區域消失；所以固定快照、區域 diff 和完整觀看不能省。

第 6 步：雙重 render，留下可重現收據

在同一個乾淨環境輸出 final-a.mp4與 final-b.mp4。先完整解碼，再查尺寸、fps、時長與實際幀數；最後比較統一 pixel format 後的逐幀雜湊：

ffmpeg -v error -i renders/final-a.mp4 -f null -

ffprobe -v error -count_frames -select_streams v:0 \
  -show_entries stream=codec_name,width,height,avg_frame_rate,duration,nb_read_frames \
  -of json renders/final-a.mp4

ffmpeg -v error -i renders/final-a.mp4 -map 0:v:0 \
  -vf format=yuv420p -f framemd5 final-a.video.framemd5
ffmpeg -v error -i renders/final-b.mp4 -map 0:v:0 \
  -vf format=yuv420p -f framemd5 final-b.video.framemd5
diff -u final-a.video.framemd5 final-b.video.framemd5

兩份 framemd5一致，是同一套受控條件下很強的逐幀證據。不一致時先查遠端素材、字型、隨機數、真實時間、Chrome／FFmpeg 版本與 GPU 路徑；再抽取指定幀做 absolute-error diff，確認差異落在哪裡。

要交給團隊、CI 或長期封存，可改用 render --docker固定 Chromium、字型與 FFmpeg 環境。不過，「deterministic timeline」不等於任何電腦都會得到位元完全相同的 MP4；容器映像、CPU 架構、encoder build 與 metadata 仍可能造成差異。務實順序是：規格一致 → 關鍵畫面正確 → 受控環境逐幀一致 → 人工完整看完、聽完。

最常踩的 6 個坑

1. 只保存 Prompt：提示詞不是成品規格；保存實際 HTML、素材、版本與驗收時間點。
2. 交件前才升級：CLI 或 Skill 更新都可能改變行為；獨立提交，從頭驗收。
3. 讓 Agent 臨時找網路素材：網址會更新、失效，也未必有使用權；先下載與登記。
4. preview 會動就算完成：自由播放正常，不代表逐幀 seek 正常；看 snapshot 與輸出檔。
5. 只比較 MP4 SHA-256：container metadata 也能改 hash；同時查規格與 decoded frames。
6. 把 Agent 當最終審片者：它擅長修明確 finding，人仍要判斷訊息、節奏、聲音與品牌語氣。

成本也要算進去：HyperFrames 本身是開源本機 renderer，但 Agent 訂閱、雲端算力、TTS、音樂、圖庫或商用字型可能收費。越早把這些依賴寫入 scene contract，越不容易在成片後才發現無法重跑或無法合法交付。

HyperFrames 教學 FAQ

完全不會寫程式，也能用 HyperFrames 嗎？

可以，但仍要會描述需求與驗收畫面。Claude Code 或 Codex 能代寫多數檔案；你至少要說清楚影片長度、尺寸、每幕訊息、素材和哪些秒數必須看到什麼。

應該選 Claude Code 還是 Codex？

兩者都可以。選你已熟悉、能安全存取專案並執行終端指令的 Agent；可重跑性主要由檔案、環境與驗收契約決定，不由 Agent 名稱決定。

每台電腦輸出的 MP4 都會完全相同嗎？

不能這樣保證。固定版本與 Docker 能縮小差異，仍應以規格、關鍵畫面、受控環境的逐幀雜湊及人工審片共同驗收。

可以直接把線上網站變成影片嗎？

可以把網站當起點。官方有 website-to-video 流程；正式 render 前仍要保存實際文字、素材、字型與必要資料，避免網站更新後舊版無法重跑。

一定要用 Docker 嗎？

不一定。單人本機迭代可先鎖 Node、HyperFrames、Chrome 與 FFmpeg；跨團隊、CI 或長期保存的案子，再用 Docker 固定更多環境因素。

CSS transition 可以直接做所有動畫嗎？

不建議讓關鍵動畫只靠自由觸發的 transition。優先用可暫停、可 seek、有限長度且已註冊的時間軸，才能從任意時間點還原狀態。

HyperFrames 是 Apache-2.0，就能商用所有輸出嗎？

不代表所有素材都自動有商用權。工具授權與照片、音樂、字型、Logo 的權利是兩件事；每項外部素材都要留下使用依據。

改一句字幕後，需要跑完整流程嗎？

至少要重跑受影響場景，交付 final 時再過完整 gate。一句變長的文字可能造成換行、遮擋或節奏改變；不能只看程式 diff。

給新手的 5 個重點

1. 先固定 8 秒、三幕與三個驗收時間點，再追求華麗效果。
2. 讓 Claude Code／Codex 改檔與跑指令，不要把 Prompt 當唯一規格。
3. 鎖 hyperframes@0.8.31與環境收據，素材和字型全部本機化。
4. 動畫必須可暫停、可 seek；排除即時時間、未設 seed 的隨機與 render 中途抓取。
5. 用 lint、check、snapshot、雙重 render、framemd5、ffprobe 與人工審片組成驗收鏈。

想把這套「規格 → Agent → 驗收」方法系統化放進日常工作，可到 AlphaLab 線上課程；更多工具與方法也整理在 AI 專區。