ak:hyperframes
包裝 HeyGen 的 hyperframes CLI,
用於以 HTML 為主的程式化影片生成。此技能僅作為文件與包裝,
不包含 HeyGen 的原始碼,也不複製 HeyGen 的代理技能。以下所有指令
皆透過 npx 執行已發布的 npm 套件,並鎖定在已知穩定的版本。
使用時機
- 由 HTML/CSS 生成的短直式/社交影片(1080×1920,9:16)。
- 產品發布短片、促銷循環、以 HTML 組合而非 React 組件或時間軸編輯器創作的動態圖形。
- 任何以
data-composition-id/data-start時間屬性為組成來源真相的任務(請參閱 references/composition-basics.md)。
不適用於以 React 為主的組合、幀精確的插值曲線、或 Remotion 的音訊/字幕生態系統 ——請參閱已安裝的 remotion 技能以獲得該替代方案(基於 React 的程式化影片)。 不適用於純 FFmpeg/ImageMagick 編碼任務——請參閱 ak-media-processing 技能。
先決條件
- Node.js 22+
- FFmpeg 安裝於
PATH - 可選:一個 HeyGen 雲端/函式 API 金鑰 (
HEYGEN_API_KEY) 用於遠端 渲染;本地渲染無需此金鑰。
開始任何渲染工作前,請執行內建的驗證器:
node scripts/verify-prereqs.mjs
# 或用於機器可讀輸出:
node scripts/verify-prereqs.mjs --json
請參閱 references/env-and-deps.md 以取得各平台的安裝說明及固定版本的驗證備註。
固定 CLI 版本
以下每個呼叫都鎖定 [email protected]——截至 2026-08-07 的最新發布版本
(npm view hyperframes version)。升級時請在一個地方(此檔案 + references/render-workflow.md)
更新此固定版本;請勿在腳本或文件中使用未固定版本的 npx -y hyperframes ...。
工作流程
標準循環為 init → edit HTML → preview → lint → render。每個階段的具體
指令請參閱 references/render-workflow.md;簡要形式如下:
# 1. 建立一個新的組合專案。
npx -y [email protected] init my-composition --resolution portrait
# 2. 編輯生成的 HTML 組合(請參閱 composition-basics.md 了解
# data-composition-id / data-start / data-width / data-height 合約)。
# 3. 在本地開發伺服器中預覽。
npx -y [email protected] preview my-composition
# 4. 在渲染前檢查組合(捕捉格式錯誤的時間屬性)。
npx -y [email protected] lint my-composition
# 5. 渲染為 MP4。
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
務必在 render 前先執行 lint——通過 lint 檢查的組合發生渲染失敗的機率遠低於跳過 lint 直接渲染的組合。
組合合約
HyperFrames 組合是普通的 HTML 檔案,透過根元素上的 data-composition-id、data-start、data-width 和 data-height 屬性進行標註。請參閱
references/composition-basics.md 以取得完整的屬性參考及完整的垂直 1080×1920 範例。
參考資料
- references/heygen-skills.md — 此包裝器委派給的 25 個 HeyGen 代理技能,而不是重新實作;如需更深層的 HyperFrames 特定專業知識(動畫、關鍵影格、字幕、產品發布模板等),請透過
npx -y [email protected] skills安裝它們。 - references/composition-basics.md — HTML 組合屬性合約,包含完整的垂直預設範例。
- references/render-workflow.md — 完整的
init → edit → preview → lint → render流程,包含每個固定版本的指令。 - references/env-and-deps.md — 各平台的 Node/FFmpeg/API 金鑰設定。
故障排除
| 症狀 | 操作 |
|---|---|
command not found: ffmpeg | 執行 node scripts/verify-prereqs.mjs 以取得針對您平台的確切修正方式。 |
npx hyperframes 回報未知的旗標 | 此檔案中的固定版本可能落後於上游;請先執行 npx -y [email protected] --help 確認目前的旗標,再更新固定版本。 |
render 失敗並產生空白/短 MP4 | 先執行 lint;大多數渲染失敗是由 lint 可捕捉的格式錯誤 data-start/data-composition-id 屬性所導致。 |
| 需要遠端/雲端渲染 | 依照 references/env-and-deps.md 設定 HEYGEN_API_KEY,然後使用 hyperframes cloud render(一個獨立的最上層指令,不是 render 的旗標)——請參閱 references/render-workflow.md。 |
另請參閱
- 已安裝的 remotion 技能(
ak-remotion)— 基於 React 的程式化影片生成;當組合自然是一個 React 組件樹而非 HTML 標記時使用。 - ak-html-video 技能 — 另一個 HTML 轉 MP4 的包裝器(
nexu-io/html-video),擁有自己的模板/Studio 工作流程;當任務明確是 HeyGen HyperFrames 組合時,請使用 ak-hyperframes。 - ak-motion-graphics 技能 — 用於路由所有儲存庫內的影片/動態技能以及外部動態技能套件的路由器。