html-video 是 nexu-io 開源的 HTML→影片 meta-layer。你給它一段 HTML、一篇文章或一個 GitHub repo,本機的 coding agent 會讀內容、挑選範本、產生 content-graph 與逐格 HTML,再經無頭 Chromium 與 ffmpeg 渲染成 MP4。21 套授權乾淨的範本、6 種可自動偵測的 agent,全程在你的筆電上跑,沒有單次渲染費。這份手冊涵蓋安裝、套件結構、支援 agent、範本庫與完整渲染管線。
html-video 是 nexu-io 開源的 HTML→影片 meta-layer,授權為 Apache 2.0。它本身不畫影格,而是把「產生影片」這件事翻譯成 coding agent 已經會做的事:讀內容、填 HTML 範本、輸出結構化資料。輸入可以是一段 HTML、一篇文章 URL,或一個 GitHub repo;輸出是本機渲染的 MP4。
運作分工很清楚。agent 負責語意層:讀素材、選範本、產生 content-graph(多場景的中介表示)與每一格的自包含 HTML。引擎負責像素層:adapter-hyperframes 用無頭 Chromium 把每格錄成 WebM,再交給 ffmpeg 以 libx264 編碼、串接,必要時混入音訊。整條管線跑在你的筆電上,沒有雲端、沒有單次渲染費。
agent 不是寫死的。專案會偵測 PATH 上已安裝的 coding agent,支援 Open Design(Vela)、Claude Code、Cursor Agent、Codex CLI、Hermes,以及自帶金鑰的 Anthropic Messages API。渲染後端同樣是可插拔的 adapter,目前實作 Hyperframes,Remotion、Motion Canvas、Revideo、Manim 列在規劃中。
html-video 是 pnpm monorepo,需要先安裝相依、建置所有 workspace,再啟動 studio。渲染端額外需要系統層的 ffmpeg 與 Chromium(供無頭錄製)。建置完成後,studio 會在 http://127.0.0.1:3071 開啟瀏覽器介面。
doctor 會偵測本機已安裝的 coding agent 與渲染引擎,確認 html-video 找得到至少一個可用 agent。search-templates 則用自然語意搜尋範本庫,回傳最相關的幾筆。
PATH 自動偵測可用的 coding agent。本機若已裝好 Claude Code、Cursor Agent、Codex CLI、Hermes 或 Open Design(Vela)其中之一就能直接用;沒有任何 CLI agent 時,也可在 Settings 填入 Anthropic API 金鑰,走 BYOK 的 Messages API。
html-video 以 monorepo 切成六個 workspace。上半是語意層,負責內容理解、範本與 agent 編排;下半是像素層,負責擷取與編碼。日常從 cli 與 project-studio 入手,其餘套件在你要程式化整合或自訂引擎時才會直接接觸。
多場景影片不寫死成時間軸,而是先表達成一張 content-graph。node 是內容單元、edge 是它們之間的關係,經拓樸排序後決定場景順序,再由 agent 展開成逐格 HTML。
| 元素 | 型別 | 作用 |
|---|---|---|
node |
entity / data / text | 一個內容單元:實體、數據或文字。 |
edge |
sequence / dependency / contrast | 節點間關係:先後、依賴或對比。 |
| 拓樸排序 | topological sort | 依 edge 解析出場景的播放順序。 |
語意層的工作交給 coding agent。html-video 偵測 PATH 上已安裝的 agent,各以不同方式驅動;沒有 CLI agent 時也能用自帶金鑰的 Anthropic Messages API。下表是官方文件列出的六種接入方式。
| Agent | 偵測 | 驅動方式 |
|---|---|---|
| Open Design(Vela) | vela / 內建 |
ACP over stdio |
| Claude Code | claude |
claude --print via stdin |
| Cursor Agent | cursor-agent |
cursor-agent --print via stdin |
| Codex CLI | codex |
codex exec via stdin |
| Hermes | hermes |
Hermes ACP CLI |
| Anthropic API | BYOK | Direct Messages API |
範本是內容的骨架。21 套授權乾淨的範本依用途分成五類,每套都附 template.html-video.yaml manifest,定義分類、標籤、輸入 schema、支援解析度、長寬比、fps、時長界限與授權資訊。agent 依素材挑範本、填內容。
圖表導向的範本,涵蓋 NYT 風格圖表與 Swiss / Vignelli 網格排版。適合把數據與排行做成動態畫面。
來源 · 官方文件 · 範本分類文字特效範本:glitch 效果、kinetic typography、打字機游標。用於開場標題與強調字卡。
來源 · 官方文件 · 範本分類Hero 與 cinematic 範本:液態漸層、light-leak 光暈、暖色顆粒。用於品牌開場與情緒鋪陳。
來源 · 官方文件 · 範本分類多場景的 product promo 範本,提供 15 秒與 30 秒版本,直接套用於產品介紹短片。
來源 · 官方文件 · 範本分類Explainer scaffold,內含決策樹等結構,用來把流程或概念拆成可視的步驟。
來源 · 官方文件 · 範本分類在 Settings → Audio 填入 MiniMax API 金鑰後,可用 mood 描述生成背景音樂、用 TTS 加旁白。兩者混入 MP4,音樂在人聲下自動 ducking,並可加淡入淡出。
來源 · 官方文件 · Soundtrack以下示範把一個 GitHub repo 做成短片:studio 在伺服器端抓取 repo,coding agent 讀內容、選一套資料視覺化範本、產生 content-graph 與逐格 HTML,Hyperframes 用無頭 Chromium 逐格錄成 WebM,最後 ffmpeg 編碼並串接成 MP4。整段都跑在本機。
agent 沒有直接畫影格,而是輸出 content-graph 與逐格 HTML。這兩者都是文字,既能被 review,也能被引擎逐格錄製。範本提供視覺骨架、agent 填入素材內容,職責清楚分離。
渲染後端是可插拔的 adapter。目前由 adapter-hyperframes 以無頭 Chromium 實作,只要滿足單一 render(input, ctx) 介面就能替換;官方規劃中的 Remotion、Motion Canvas、Revideo、Manim 都走同一個契約。
pnpm install 再 pnpm -r build,CLI 才會出現在 packages/cli/dist/bin.js。跳過建置會找不到指令。
doctor 確認引擎就緒。
PATH 偵測。本機沒有任何 CLI agent 時,需在 Settings 填入 Anthropic API 金鑰走 BYOK,否則 agent loop 無法執行。
adapter-hyperframes 已實作;Remotion、Motion Canvas、Revideo、Manim 仍列在規劃中,尚不可用。
template.html-video.yaml 定義了支援解析度、長寬比、fps 與時長界限。輸出規格需落在範本宣告的範圍內,超出界限的需求應換範本或自訂。
studio 適合互動式產製,CLI 與套件則讓你把它接進自動化流程。以下是幾條官方文件支持的延伸方向。
1. 用 search-templates 做選範本路由。search-templates --intent "..." --top N 以自然語意搜尋範本庫,可在腳本裡先選定範本,再交給 agent 填內容。
2. 文章與 repo 一鍵成片。studio 在伺服器端抓取 URL 或 repo,適合把部落格文章、release notes、repo 簡介批次轉成短片。
3. 加上 AI 配樂與旁白。填入 MiniMax 金鑰後,用 Soundtrack 面板以 mood 生成配樂、以 TTS 加旁白,匯出時自動混音與 ducking。
4. 換用其他 agent。偵測是基於 PATH 的,裝好 Cursor Agent、Codex CLI 或 Hermes 即可切換;無 CLI agent 時用 BYOK 的 Anthropic Messages API。
5. 自訂渲染引擎。引擎是滿足 render(input, ctx) 契約的 adapter。要接 Remotion、Manim 等後端,實作同一介面即可,語意層不必更動。
① github.com/nexu-io/html-video:原始碼、套件結構、範本庫與授權(Apache 2.0)。
② repo 內 README 與各範本的 template.html-video.yaml:CLI 指令、agent 偵測與範本 manifest 規格。