html-video 完整教學：用 HTML 在本機生成真實 MP4 影片

目錄

1. 專案總覽
2. 核心概念與術語
3. 系統架構
4. 安裝與環境設置
5. 快速上手
6. 資安評估
7. 深度功能解析
8. 模板系統
9. 進階使用情境
10. 常見問題與排錯
11. 總結與評價

1. 專案總覽

這是什麼？

html-video 是由 nexu-io（Open Design 團隊）開發的開源「HTML 轉影片」meta-layer 框架。它不是另一個渲染引擎，而是坐在所有渲染引擎之上的抽象層 — 讓你用自然語言描述影片內容，由 AI coding agent 自動挑選模板、填入內容、渲染為真實 MP4。

為什麼需要它？

HTML-to-Video 是一個真實的技術類別，但現有引擎各有各的創作模型：

html-video 的價值在於：你不需要學每個引擎的 DSL，只需要對 agent 說話，它會選引擎、選模板、填內容、渲染影片。引擎是可替換的實作細節。

關鍵數據

2. 核心概念與術語

Content Graph（內容圖）

多幀 storyboard 的中間表示法（IR）。由「節點」（entity / data / text）和「邊」（sequence / dependency / contrast）組成，拓撲排序後決定幀序與時序。這是 agent 與引擎之間的解耦介面。

Engine Adapter（引擎適配器）

統一的 render(input, ctx) 合約介面。任何渲染後端（Hyperframes、Remotion、Motion Canvas）只要實作此介面，就能無縫接入。目前僅 Hyperframes 已完成實作。

Agent Runtime

自動偵測使用者 PATH 上的 coding agent CLI，透過 stdio / ACP 協議與之互動。支援 14 種 agent backend。

Template Manifest

每個模板目錄下的 template.html-video.yaml，描述模板用途、支援解析度、輸入 schema、授權來源。Agent 讀取此檔即可知道如何驅動模板。

Studio

本機瀏覽器 UI，在 http://127.0.0.1:3071 運行。提供對話、模板庫、逐幀編輯、配樂、匯出等功能。

3. 系統架構

整體架構圖

graph TB
    subgraph 輸入層
        A[自然語言 Prompt]
        B[文章 URL]
        C[GitHub Repo URL]
    end

    subgraph Studio 層
        D[project-studio
瀏覽器 UI]
        E[cli / studio-server
HTTP Server]
    end

    subgraph Agent 層
        F[runtime
Agent 偵測 / 啟動 / 串流]
        G[14 種 Agent Backend]
    end

    subgraph 核心處理層
        H[core
Project / Asset / Registry
MiniMax + ffmpeg mux]
        I[content-graph
Storyboard IR
節點 + 邊 + 拓撲排序]
    end

    subgraph 渲染層
        J[adapter-hyperframes
Chromium + ffmpeg]
        K["未來: Remotion Adapter"]
        L["未來: Motion Canvas Adapter"]
    end

    subgraph 資產層
        M[21 個策展模板
template.html-video.yaml]
        N[MiniMax AI 配樂]
    end

    subgraph 輸出層
        O[MP4 影片檔案]
    end

    A --> D
    B --> E
    C --> E
    D --> E
    E --> F
    F --> G
    G --> I
    I --> H
    H --> J
    H -.-> K
    H -.-> L
    M --> J
    N --> H
    J --> O

渲染流程

sequenceDiagram
    participant U as 使用者
    participant S as Studio Server
    participant A as AI Agent
    participant CG as Content Graph
    participant HF as Hyperframes Adapter
    participant FF as ffmpeg

    U->>S: 貼入 URL / 輸入 Prompt
    S->>S: 抓取來源內容（Server-side Fetch）
    S->>A: 傳送內容 + 模板樣式
    A->>CG: 生成 Content Graph（Storyboard）
    CG->>CG: 拓撲排序 → 決定幀序
    loop 每一幀
        A->>HF: 生成 HTML 區塊
        HF->>HF: headless Chromium 錄製
        HF->>FF: WebM → MP4 (libx264)
    end
    FF->>FF: Concat 所有幀 + 混入配樂
    FF->>U: 輸出最終 MP4

Monorepo 結構

graph LR
    subgraph packages/
        CORE[core
型別 + Registry
+ MiniMax + ffmpeg mux]
        CG[content-graph
Storyboard IR]
        RT[runtime
Agent 偵測與啟動]
        AH[adapter-hyperframes
Chromium 渲染]
        CLI[cli
命令列 + Studio Server]
        PS[project-studio
瀏覽器 UI]
        SN[studio-next
下一代 Studio]
    end

    subgraph templates/
        T1[21 個模板目錄]
    end

    CLI --> CORE
    CLI --> AH
    CLI --> PS
    CLI --> RT
    CLI --> CG
    AH --> CORE
    RT --> CORE
    CG --> CORE

4. 安裝與環境設置

前置需求

安裝步驟

 1# 1. 複製專案
 2git clone https://github.com/nexu-io/html-video.git
 3cd html-video
 4
 5# 2. 安裝 Playwright Chromium（渲染引擎需要）
 6npx playwright install chromium
 7
 8# 3. 安裝依賴
 9pnpm install
10
11# 4. 建構所有套件
12pnpm -r build
13
14# 5. 啟動 Studio
15node packages/cli/dist/bin.js studio
16# → 開啟 http://127.0.0.1:3071

Agent 設置

html-video 會自動偵測 PATH 上的 coding agent CLI。不需額外設定，只要確保至少一個 agent 可用：

1# 檢查已安裝的 agent 與引擎
2node packages/cli/dist/bin.js doctor

如果沒有任何 CLI agent，設定 Anthropic API key 即可直接使用 Messages API：

1export ANTHROPIC_API_KEY=sk-ant-...

Windows 注意事項

截至目前，有多個已知的 Windows 相容性問題：

• chmod 指令無法識別（Issue #27/#28）
• Agent CLI 偵測失敗（Issue #7/#10/#29/#31）
• 建議在 WSL2 環境下使用

5. 快速上手

情境一：從 Prompt 建立影片

1在 Studio 中：
21. 點擊 "New Project"
32. 從模板庫選擇一個模板（例如 frame-glitch-title）
43. 在對話框輸入描述：「一個科技風格的開場動畫，標題是 AI Driven Innovation」
54. Agent 自動生成 Content Graph + 逐幀 HTML
65. 預覽 → 匯出 MP4

情境二：從文章連結建立影片

1在 Studio 對話框中：
2「做一個解讀影片 https://example.com/article」
3→ Studio server-side 抓取文章
4→ Agent 讀完文章後自動規劃 storyboard
5→ 多幀解說影片生成

情境三：從 GitHub Repo 建立影片

1「幫我做一個介紹這個開源專案的影片 https://github.com/user/repo」
2→ 抓取 description + README + 結構
3→ 自動建構「專案介紹」風格的多幀影片

CLI 工具

1# 搜尋適合的模板
2node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3
3
4# 診斷環境
5node packages/cli/dist/bin.js doctor

6. 資安評估

總評：黃燈 (MODERATE)

本專案為本機運行的開發工具，整體資安風險可控，但有數個需注意的面向。

詳細評估

機密管理

程式碼執行

前端安全

供應鏈

網路通訊

授權與合規

資安建議

1. 低風險即可使用：本專案為本機工具，無雲端依賴（配樂除外），API key 管理正確
2. 注意 innerHTML：若需客製 Studio UI，建議用 textContent 或 DOM API 取代 innerHTML
3. Windows 使用者：目前有多個 Windows 相容問題，建議使用 WSL2
4. MiniMax API：配樂功能會將文字描述發送到 MiniMax 雲端，注意勿包含機密內容

7. 深度功能解析

7.1 Content Graph（內容圖）

Content Graph 是 html-video 的核心創新。它是一個有向無環圖（DAG），將影片內容結構化為：

• 節點類型：entity（實體）、data（資料）、text（文字）
• 邊類型：sequence（順序）、dependency（依賴）、contrast（對比）
• 排序：拓撲排序決定幀的播放順序
• 時序：每個節點可指定 duration，系統自動計算總時長

這個設計讓 agent 可以用結構化的方式描述影片故事線，而不是逐幀手動排列。

7.2 Hyperframes 渲染引擎

目前唯一已實作的渲染後端。流程如下：

1. 每一幀是一個獨立的 HTML 檔案（含 CSS + GSAP 動畫）
2. headless Chromium（透過 Playwright）載入 HTML
3. 自動偵測動畫長度，擴展錄製時間以完整捕捉動畫
4. 逐幀錄製為 WebM
5. ffmpeg 將 WebM 轉為 MP4（libx264）
6. 所有幀 concat 為最終影片

關鍵設計決策：

• 動畫感知：不會在動畫播放中途截斷（修復 commit d7cd10c）
• GSAP 安全：偵測並處理 GSAP 無限迴圈，避免 duration 膨脹到 30s 上限（修復 commit 214c382）
• 字體閃爍修復：避免 font-swap 閃爍（修復 commit 0029840）

7.3 Agent Runtime 架構

Agent 偵測與啟動採用統一的型別系統：

1interface AgentDef {
2  bins: string[];          // CLI 二進位名稱（第一個存在的為主）
3  env?: Record<string, string>;  // 額外環境變數
4  mode: 'child' | 'http';       // child: spawn 子程序; http: 直接呼叫 API
5}

偵測流程：which <bin> → 確認版本 → 加入可用清單 → Studio 頂部切換器顯示

7.4 AI 配樂

透過 MiniMax API 提供兩種音訊功能：

• 背景音樂：描述氛圍（如「calm cinematic ambient, slow build」），生成器材音樂
• 旁白 TTS：輸入腳本文字，MiniMax 語音合成

音訊混合流程：

1. 背景音樂在語音段落自動降低音量（ducking）
2. 可選 fade-in / fade-out
3. 最終由 ffmpeg 混入 MP4

7.5 來源抓取

Studio server 端負責抓取外部內容，支援：

• 一般網頁：抓取 + 轉為 Markdown
• WeChat 公眾號文章：server-rendered 頁面直接處理
• GitHub Repo：透過 public API 取得 description + README + 結構

抓取在 server side 完成，解決了跨域限制問題。

8. 模板系統

21 個策展模板分類

模板 Manifest 結構

每個模板目錄包含：

1frame-glitch-title/
2├── template.html-video.yaml   # Manifest（Agent 讀取用）
3├── SKILL.md                   # Agent skill 描述
4├── example.md                 # 使用範例
5├── package.json               # 套件資訊
6└── preview.png / poster.svg   # 預覽圖

template.html-video.yaml 包含：

• category / tags / best_for：用途分類
• 支援的 resolution / aspect ratio / fps / duration
• inputs JSON Schema：Agent 知道要填什麼欄位
• SPDX 授權 + attribution_required / redistribution_allowed / commercial_use 旗標

9. 進階使用情境

9.1 品牌規範整合

透過 design.md / frame.md 檔案定義品牌 + 動態規範（commit 166fdc1），Agent 會在生成時套用品牌風格。

9.2 批次影片生成

html-video CLI 支援腳本化操作，可整合到 CI/CD pipeline：

1# 搜尋模板
2node packages/cli/dist/bin.js search-templates --intent "product launch" --top 3
3
4# 未來可期待的 CLI render 指令
5node packages/cli/dist/bin.js render --template frame-product-promo --data content.json --output out.mp4

9.3 自訂模板開發

建立新模板只需：

1. 在 templates/ 下建立目錄
2. 寫 template.html-video.yaml manifest
3. 寫 HTML 動畫（使用 GSAP / CSS Animation）
4. Studio 啟動時自動掃描

9.4 多引擎整合（規劃中）

引擎適配器介面已設計完成，未來可支援：

• Remotion：React 元件式影片
• Motion Canvas / Revideo：TypeScript generator 風格
• Manim：數學 / 3D 動畫

10. 常見問題與排錯

Q1：Windows 上無法啟動

症狀：chmod 不被識別、Agent CLI 找不到

解法：

• 使用 WSL2 環境
• 追蹤 Issue #27, #28, #29, #31
• 社群正在積極修復 Windows 支援

Q2：部分模板渲染為空白 MP4

症狀：使用 data-composition-src 的模板渲染結果全黑

原因：Hyperframes runtime 未在 page.goto() 前注入（Issue #16, #18）

狀態：已有修復 PR，追蹤中

Q3：中文對話產生亂碼

症狀：中文提示詞或回應出現亂碼

追蹤：Issue #9，標記為 bug + help wanted

Q4：MiniMax 配樂報錯

解法：

• 確認 API key 正確
• 檢查 region 設定（MiniMax 有區域限制，預設已修正 commit cecbe0a）
• 配樂為可選功能，不影響主要渲染流程

Q5：GSAP 動畫導致渲染時間過長

原因：GSAP infinite loop 會將 per-frame duration 膨脹到 30s 上限

已修復：commit 214c382 加入了 infinite loop 偵測與處理

11. 總結與評價

優勢

• 創新的 meta-layer 設計：不綁定特定引擎，Content Graph 是優雅的抽象
• 極低門檻：自然語言描述 → MP4，不需要學任何 DSL
• 14 種 Agent 支援：幾乎涵蓋所有主流 AI coding agent
• 授權友好：Apache-2.0，模板來源記錄完整
• 本機優先：無雲端依賴（配樂除外），無 per-render 費用
• 依賴精簡：核心僅依賴 ajv + yaml，供應鏈風險極低
• 活躍開發：12 天內 30+ commits，快速迭代

限制

• 極早期：建立僅 12 天，無正式 Release，API 可能劇烈變動
• 僅 Hyperframes 引擎：Remotion / Motion Canvas 尚未實作
• Windows 不穩定：多個已知問題，建議 WSL2
• 中文支援有瑕疵：亂碼問題待修
• 無測試覆蓋率資訊：未見明確的測試策略
• Studio UI 使用 innerHTML：資安上雖影響有限但不夠理想

適用場景

最終評價

html-video 是一個概念新穎、設計精良的早期專案。Content Graph + Engine Adapter 的雙層抽象展現了良好的工程品味。專案發展速度驚人（12 天 2,000+ stars），社群反應熱烈。適合作為「AI 影片生成」技術探索的參考專案，但因極度早期（無正式 Release），不建議用於生產環境。建議持續關注，待 Windows 支援穩定 + 第二個引擎（Remotion）上線後再進行深度整合評估。