OpenMontage 完整教學 — AI 代理影片製作系統深度解析

1. 專案定位：它解決什麼問題？

一句話定義

OpenMontage 是全球第一個開源的 agentic video production system（代理式影片製作系統），它讓你的 AI coding assistant（如 Claude Code、Cursor、Copilot）變成一整個影片製作團隊。

白話解釋

想像你今天想做一支 60 秒的教學影片，傳統流程是：

1. 寫腳本（30 分鐘）
2. 找素材圖片/影片（1-2 小時）
3. 錄旁白或找 AI 配音（30 分鐘）
4. 找背景音樂（30 分鐘）
5. 剪輯合成（2-3 小時）
6. 加字幕（1 小時）

用 OpenMontage，你只需要打一行字：

1"Make a 60-second animated explainer about how neural networks learn"

然後 AI agent 會自動完成上面所有步驟：自動研究主題、寫腳本、生成圖片/影片、配音、找音樂、加字幕、最後渲染出成品。

與現有工具的比較

三個核心概念

1. Agent-first（代理優先）：沒有 Python orchestrator，AI agent 本身就是導演
2. Pipeline-driven（管線驅動）：每個影片類型有對應的 production pipeline
3. Instruction-driven（指令驅動）：所有品質標準、創意決策寫在 YAML + Markdown 中，agent 讀取後執行

2. 安裝指南

2.1 系統需求

2.2 基礎安裝（三行指令）

1# Step 1: 克隆 repo
2git clone https://github.com/calesthio/OpenMontage.git
3
4# Step 2: 進入目錄
5cd OpenMontage
6
7# Step 3: 一鍵安裝（Python 依賴 + Remotion + Piper TTS + HyperFrames）
8make setup

make setup 會自動完成：

• 安裝 Python 依賴（pip install -r requirements.txt）
• 安裝 Remotion composer（cd remotion-composer && npm install）
• 安裝免費離線 TTS（Piper TTS）
• 預熱 HyperFrames runtime（npx cache）
• 建立 .env 檔案（從 .env.example 複製）

沒有 make？ 手動執行：

1pip install -r requirements.txt
2cd remotion-composer && npm install && cd ..
3pip install piper-tts
4cp .env.example .env

Windows 注意：若 npm install 出現 ERR_INVALID_ARG_TYPE，改用 npx --yes npm install。

2.3 API Key 設定（可選，越多越強）

編輯 .env 檔案，加入你有的 API Key：

 1# ⭐ 最推薦先設定的（覆蓋最廣的功能）
 2FAL_KEY=your-key               # FLUX 圖片 + Veo/Kling/MiniMax 影片（一把鑰匙解鎖最多）
 3PEXELS_API_KEY=your-key        # 免費素材庫（申請免費）
 4OPENAI_API_KEY=your-key        # OpenAI TTS + DALL-E 圖片
 5
 6# 🎵 音樂
 7SUNO_API_KEY=your-key          # AI 音樂生成
 8
 9# 🎙️ 語音
10ELEVENLABS_API_KEY=your-key    # 高品質 TTS
11
12# 🎬 更多影片 provider
13RUNWAY_API_KEY=your-key        # Runway Gen-4
14HEYGEN_API_KEY=your-key        # HeyGen 多模型 gateway
15XAI_API_KEY=your-key           # Grok 圖片/影片
16
17# 📷 更多圖片
18GOOGLE_API_KEY=your-key        # Google Imagen + Google TTS (700+ 語音)

2.4 GPU 加速（可選，免費本地影片生成）

1make install-gpu
2
3# 在 .env 加入：
4VIDEO_GEN_LOCAL_ENABLED=true
5VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b  # 可選：wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b

2.5 驗證安裝

1# 檢查可用工具
2make preflight
3
4# 檢查 HyperFrames runtime
5make hyperframes-doctor
6
7# 跑零 API Key 的 demo
8make demo

2.6 安裝流程圖

flowchart TD
    A["git clone OpenMontage"] --> B["cd OpenMontage"]
    B --> C["make setup"]
    C --> D{"安裝完成"}
    D --> E["設定 .env API Keys
（可選）"]
    D --> F["make install-gpu
（有 GPU 時）"]
    E --> G["make preflight
驗證安裝"]
    F --> G
    G --> H{"開始製作影片！"}

    style A fill:#e3f2fd
    style C fill:#fff3e0
    style H fill:#e8f5e9

3. 核心架構解析

3.1 整體架構圖

flowchart TB
    subgraph USER["👤 使用者"]
        U1["自然語言 prompt
例：Make a 60s explainer about CRISPR"]
    end

    subgraph AGENT["🤖 AI Agent（Claude Code / Cursor / Copilot）"]
        direction TB
        A1["讀取 pipeline manifest
pipeline_defs/*.yaml"]
        A2["讀取 stage director skill
skills/pipelines/*/"]
        A3["呼叫 Python tools
tools/*/"]
        A4["自我審查
skills/meta/reviewer.md"]
        A5["設定 checkpoint
lib/checkpoint.py"]
        A1 --> A2 --> A3 --> A4 --> A5
    end

    subgraph TOOLS["🔧 52 個 Python Tools"]
        T1["video/ — 影片生成/合成"]
        T2["audio/ — TTS/音樂/混音"]
        T3["graphics/ — 圖片生成/圖表"]
        T4["analysis/ — 轉錄/場景偵測"]
        T5["enhancement/ — 升級/去背/調色"]
        T6["subtitle/ — 字幕生成"]
    end

    subgraph RENDER["🎬 渲染引擎"]
        R1["Remotion
React 程式化影片"]
        R2["HyperFrames
HTML/CSS/GSAP 動態"]
        R3["FFmpeg
編碼/合成/後製"]
    end

    subgraph QA["✅ 品質管控"]
        Q1["Pre-compose validation"]
        Q2["Post-render self-review"]
        Q3["Delivery promise 檢查"]
        Q4["Slideshow risk scoring"]
    end

    U1 --> A1
    A3 --> TOOLS
    TOOLS --> RENDER
    RENDER --> QA
    QA --> |"通過"| OUTPUT["📹 最終影片輸出"]
    QA --> |"未通過"| A3

3.2 三層知識架構

OpenMontage 採用三層知識架構，這是理解整個系統的關鍵：

flowchart LR
    subgraph L1["Layer 1: 能力層"]
        direction TB
        L1A["tools/ — 52 個 Python 工具"]
        L1B["pipeline_defs/ — 12 條 YAML 管線"]
        L1C["tool_registry.py — 自動發現"]
    end

    subgraph L2["Layer 2: 慣例層"]
        direction TB
        L2A["skills/pipelines/ — 每階段導演指令"]
        L2B["skills/creative/ — 創意技巧"]
        L2C["skills/meta/ — 審查/檢查點"]
        L2D["skills/core/ — 核心工具指引"]
    end

    subgraph L3["Layer 3: 技術知識層"]
        direction TB
        L3A[".agents/skills/ — 外部技術知識包"]
        L3B["Provider 專用 prompting 指引"]
        L3C["API 參數最佳化"]
    end

    L1 -->|"What exists
有什麼工具"| L2
    L2 -->|"How to use it
怎麼用"| L3
    L3 -->|"How it works
底層原理"| OUTPUT2["🎬 高品質影片"]

    style L1 fill:#e3f2fd
    style L2 fill:#fff3e0
    style L3 fill:#fce4ec

為什麼要三層？ 舉例來說：

• Layer 1 告訴 agent：「有一個叫 kling_video 的工具可以生成影片」
• Layer 2 告訴 agent：「在 cinematic pipeline 的 asset 階段，要先做 cost estimate 再呼叫影片工具」
• Layer 3 告訴 agent：「用 Kling 時，prompt 要加 cinematic camera motion 關鍵字，效果最好」

3.3 Production Pipeline 流程

每條 pipeline 都遵循相同的 7 階段流程：

flowchart LR
    S1["🔍 Research
網路研究"] --> S2["💡 Proposal
概念提案"]
    S2 --> S3["📝 Script
腳本撰寫"]
    S3 --> S4["🎬 Scene Plan
場景規劃"]
    S4 --> S5["🎨 Assets
素材生成"]
    S5 --> S6["✂️ Edit
剪輯決策"]
    S6 --> S7["🎥 Compose
渲染合成"]

    S1 -.->|"每階段都有"| SK["📋 Stage Director Skill
教 agent 怎麼執行"]
    S1 -.->|"每階段都有"| CP["💾 Checkpoint
可恢復狀態"]
    S2 -.->|"關鍵決策點"| HA["✋ Human Approval
人類審批"]

    style S1 fill:#e8eaf6
    style S5 fill:#fff3e0
    style S7 fill:#e8f5e9

3.4 目錄結構一覽

 1OpenMontage/
 2├── tools/                  # 52 個 Python 工具（agent 的「手」）
 3│   ├── video/             # 影片生成 + 合成 + 剪輯（30+ 個工具）
 4│   ├── audio/             # TTS (4 provider) + 音樂 + 混音 + 增強
 5│   ├── graphics/          # 圖片生成 (10 provider) + 圖表 + 程式碼片段
 6│   ├── enhancement/       # 升級 + 去背 + 人臉增強 + 調色
 7│   ├── analysis/          # 轉錄 + 場景偵測 + 幀取樣 + 影片理解
 8│   ├── avatar/            # Talking head + 嘴型同步
 9│   ├── subtitle/          # SRT/VTT 字幕生成
10│   └── character/         # 角色動畫（SVG rig + pose library）
11│
12├── pipeline_defs/         # 12 條 YAML pipeline manifest
13├── skills/                # Markdown skill 指令檔
14│   ├── pipelines/        # 每條 pipeline 的 stage director
15│   ├── creative/         # 創意技巧（prompting、風格、storytelling）
16│   ├── core/             # 核心工具技能（FFmpeg、Remotion、HyperFrames）
17│   └── meta/             # 審查、checkpoint、onboarding
18│
19├── schemas/              # 15 個 JSON Schema（契約驗證）
20├── styles/               # 視覺風格 playbook（YAML）
21├── remotion-composer/    # React/Remotion 影片合成引擎
22├── lib/                  # 核心基礎建設
23├── tests/                # 測試套件
24├── config.yaml           # 全域設定
25└── Makefile              # 一鍵指令

4. 12 條 Production Pipeline 詳細用法

4.1 Pipeline 選擇指南

4.2 零成本上手範例

完全不需要 API Key 就能做的事：

 1# 範例 1：動畫解說影片（用 Piper TTS + Remotion 動畫）
 2"Make a 45-second animated explainer about why the sky is blue"
 3
 4# 範例 2：紀錄片剪輯（用免費素材庫 + FFmpeg）
 5"Make a 90-second documentary montage about city life at 4am.
 6Use real footage only, no narration, elegiac tone, with music."
 7
 8# 範例 3：角色動畫（用 SVG rig + HyperFrames）
 9"Create an animated character explaining how to recycle"
10
11# 範例 4：軟體 Demo（用 screen recording + FFmpeg）
12"Record a demo of the CLI setup process"

4.3 進階付費範例

 1# 範例 1：Ghibli 風格動畫（~$0.15，用 FLUX 圖片）
 2"Create a 30-second Ghibli-style animated video of a magical floating
 3library in the clouds at golden hour"
 4
 5# 範例 2：電影級預告片（~$1-$3，用 Kling/Veo 影片生成）
 6"Create a cinematic 30-second trailer for a sci-fi concept:
 7humanity receives a warning from 1000 years in the future"
 8
 9# 範例 3：從參考影片出發（最實用！）
10"Here's a YouTube Short I love. Make me something like this,
11but about quantum computing."

5. 應用場景

5.1 學術與研究

具體範例（生物醫學領域）：

1"Make a 90-second animated explainer about how CRISPR-Cas9 gene editing
2works, covering the guide RNA mechanism, double-strand break, and
3cellular repair pathways. Use diagram style, with narration."

5.2 企業與商業

5.3 藥物研發與 Biotech 應用場景

對於 AI-driven drug repositioning（AI 驅動藥物再利用）公司，OpenMontage 有以下實用場景：

具體 prompt 範例：

1"Make a 90-second animated explainer about AI-driven drug repositioning:
2how computational pipelines can discover new therapeutic uses for
3approved drugs, covering target identification, molecular docking,
4and clinical success probability prediction. Use clean professional
5style with data visualizations."

5.4 教育與內容創作

6. 資安掃描報告

掃描範圍

• tools/ — 52 個 Python 工具
• lib/ — 核心程式庫
• scripts/ — 輔助腳本
• .env.example — 環境變數範本

掃描結果

🟡 中風險：math_animate 未沙箱化程式碼執行

問題：tools/graphics/math_animate.py 接受使用者提供的 Python scene_code，直接寫入暫存檔案並透過 subprocess.run 執行 Manim 渲染。雖然沒有使用 eval() 或 exec()（是透過外部程序 manim CLI 執行），但理論上惡意的 scene_code 可以在 Manim 環境中執行任意 Python 程式碼。

已知 Issue：#219 — 「math_animate executes caller-supplied Python scene_code without sandboxing」

實際風險：中等。因為 OpenMontage 是本地執行的工具，scene_code 來自 AI agent 而非外部使用者輸入，但仍建議關注此 issue 的進展。

🟡 中風險：仿冒 repo 安全警告

已知 Issue：#200 — 「Security warning: lookalike Open-Montage/OpenMontage release behaves like malware」

說明：存在仿冒的 GitHub repo（注意是 Open-Montage 而非 OpenMontage），其 release 包含惡意程式碼。務必從正確的 URL 安裝：https://github.com/calesthio/OpenMontage。

🟢 低風險：subprocess 使用規範

正面發現：

• 全部 subprocess.run 呼叫都沒有使用 shell=True（避免 shell injection）
• 程式碼中有明確註解避免 shell=True
• 所有外部命令都使用 list 形式的 cmd 參數

🟢 低風險：API Key 管理

• 所有 API Key 都透過 .env 環境變數管理
• .env.example 只有空值範本，不含真實金鑰
• .gitignore 已排除 .env 檔案

🟢 低風險：__import__ 使用

• tools/base_tool.py 中有 __import__ 用於動態載入工具模組，這是 tool registry 自動發現機制的一部分，屬於正常設計模式

掃描總結

整體評估：安全性良好。最值得注意的是務必從正確 URL 安裝（Issue #200），以及 math_animate 的沙箱化問題（Issue #219，已在社群追蹤中）。

7. FAQ

Q1: 完全不花錢能做影片嗎？

可以。 make setup 就能用以下免費工具：

• Piper TTS：免費離線配音
• Archive.org + NASA + Wikimedia：免費公共素材
• Pexels / Pixabay / Unsplash：免費素材（需申請免費 API Key）
• Remotion / HyperFrames：免費本地渲染
• FFmpeg：免費編碼/後製

Q2: 支援哪些 AI coding assistant？

Claude Code、Cursor、Copilot、Windsurf、Codex — 任何能讀檔案和執行 Python 的 AI assistant 都可以。

Q3: 影片最長可以多長？

理論上無限。OpenMontage 的 pipeline 會根據場景規劃分段處理，最後拼接。實務上建議 30 秒到 3 分鐘最佳。

Q4: 可以用自己的素材嗎？

可以。Hybrid pipeline 就是設計來混合你的素材 + AI 生成內容。OpenMontage 會自動 probe 你的素材（解析度、codec、音軌、長度）再做規劃。

Q5: 成本怎麼控制？

OpenMontage 內建 budget governance：

• 執行前預估成本
• 單次操作超過 $0.50 需人類確認
• 總預算上限預設 $10（可調）
• 所有花費都有 audit trail

Q6: Remotion 和 HyperFrames 怎麼選？

agent 會在 proposal 階段推薦，但使用者有最終決定權。

Q7: 跟 AIKT (AI-knowledge template) 的 quarkdown slides 有什麼不同？

兩者可以互補：先用 quarkdown 做文字版教學，再用 OpenMontage 將精華段落做成影片。

8. 進階技巧

8.1 從參考影片出發（最高效）

這是 OpenMontage 最強大的功能之一。貼一個你喜歡的影片（YouTube、Reel、TikTok），agent 會分析：

• 保留什麼：節奏、hook 風格、結構、語調
• 改變什麼：主題、視覺處理、角度、旁白方式
• 成本預估：在開始前告訴你
• 實際效果：用你目前可用的工具能做出什麼

1"Here's a YouTube Short I love: [URL]. Make me something like this,
2but about CRISPR for high school students."

8.2 Atelier 模式（獨一無二的影片）

預設的 templated 模式會重複使用內建元件（TextCard、StatCard 等），如果你要做 hero work（行銷、品牌影片），建議開啟 atelier 模式：

• 每一幕從零設計
• 獨特的視覺語言
• 不使用任何既有元件
• 成本更高，但不會跟別人撞風格

8.3 Documentary Montage（免費紀錄片）

這是唯一能做「真影片」（不只是靜態圖片動畫）的免費路徑：

1"Create a 60-second Adam-Curtis-style archival collage about 1950s
2consumer optimism. Prefer Archive.org and Wikimedia footage."

agent 會從 Archive.org、NASA、Wikimedia Commons 建構 CLIP-searchable corpus（語義搜尋影片庫），然後根據主題自動檢索、剪輯、合成。

8.4 Provider 選擇的 7 維度評分

OpenMontage 的 tool selector 用 7 個維度評分選擇最佳 provider：

9. 與 AIKT Layer 的整合策略

9.1 整合架構圖

flowchart TB
    subgraph AIKT["🧠 AI-Knowledge Template (AIKT)"]
        direction TB
        L1["Layer 1: ai-save
知識輸入"]
        L2["Layer 2: ai-gh-save
GitHub 知識"]
        L7["Layer 7: quarkdown
Markdown → HTML"]
        L9["Layer 9: paper-search
論文檢索"]
        L10["Layer 10: paper-qa-lite
RAG 問答"]
        L11["Layer 11: kami
PDF 排版"]
        L12["Layer 12: gh-tutorial-qd
全套交付"]
        L15["Layer 15: paper-tutorial
論文教學"]
        L17["Layer 17: video-to-tutorial
影片轉教學"]
        L22["Layer 22: company-intel
盡職調查"]
    end

    subgraph OM["🎬 OpenMontage"]
        direction TB
        OM1["Animated Explainer
教學動畫"]
        OM2["Cinematic
品牌影片"]
        OM3["Screen Demo
軟體展示"]
        OM4["Documentary Montage
紀錄片"]
    end

    L7 -->|"slides → video
文字教學轉影片"| OM1
    L9 -->|"paper findings →
科學影片"| OM1
    L15 -->|"tutorial md →
影片版教學"| OM1
    L17 -->|"逆向：影片 → 教學
↔ 教學 → 影片"| OM1
    L22 -->|"company profile →
BD 影片"| OM2
    L12 -->|"GitHub tutorial →
Demo 影片"| OM3
    L11 -->|"kami PDF →
animated version"| OM1

    style AIKT fill:#e8eaf6
    style OM fill:#fff3e0

9.2 具體整合路徑

路徑 A：Quarkdown Slides → OpenMontage 影片

1. 用 qd: 產出 slides HTML 教學
2. 提取 slides 的核心段落和 mermaid 圖
3. 用 OpenMontage Animated Explainer 做成動態影片版

1# 在 OpenMontage 中
2"I have a slide deck about drug repositioning pipeline
3(see attached markdown). Convert the key concepts into a
460-second animated explainer video with narration."

路徑 B：Paper-Tutorial → 研究影片

1. 用 paper-tutorial: 做完 N 篇論文的整合教學 HTML
2. 從 tutorial md 提取「是什麼 / 為什麼 / 怎麼做」三段
3. 用 OpenMontage 做成影片版

路徑 C：Company-Intel → BD 影片

1. 用 dd: 做完公司盡調報告
2. 提取核心資訊（市場定位、競爭格局、技術優勢）
3. 用 OpenMontage Cinematic/Animation 做成 BD pitch 影片

路徑 D：Video-to-Tutorial 逆向整合

1. 用 OpenMontage 做了影片
2. 用 v2t: 將影片轉成教學 markdown
3. 用 qd: 轉成 HTML 教學文件
4. 形成 影片 ↔ 文字 雙向知識載體

9.3 整合時的注意事項

10. 重點摘要 Checklist

• 安裝：git clone → make setup → 設定 .env（三步完成）
• 第一支影片：用零成本 prompt 試做（不需 API Key）
• 理解架構：Agent-first + Pipeline-driven + 三層知識
• 選對 Pipeline：12 條 pipeline 各有適用場景
• Provider 設定：API Key 越多，能力越強
• 成本控制：內建 budget governance，不會意外超支
• 資安注意：務必從正確 URL 安裝（不是 Open-Montage）
• AIKT 整合：文字教學 ↔ 影片 雙向轉換可行
• 進階用法：從參考影片出發 > 從零 prompt 效率更高
• 品質管控：Pre-compose + Post-render 雙重自動 QA

11. 進一步閱讀

相關 AIKT 文件