OpenMontage 使用教學：把 AI 程式助手變成影片製作流水線

OpenMontage 不是“一句話返回一個影片檔案”的線上生成器，而是一套由 AI 程式設計助手驅動的本地影片生產流水線。它會在專案目錄中完成研究、方案、指令碼、分鏡、素材選擇、配音、合成和質檢，因此安裝成功的判斷不能只看依賴是否裝完，還要確認工具登錄檔、Provider 能力和最終媒體檔案都可驗證。

專案地址：calesthio/OpenMontage

快速結論

最低準備項是 Python 3.10+、Node.js 18+、FFmpeg 和一個能讀取檔案並執行命令的 AI 程式設計助手。
make setup 是 macOS/Linux 的最短路徑；Windows 應使用獨立虛擬環境和 PowerShell 安裝命令。
沒有付費 API Key 也能使用 Piper、開放檔案素材和 Remotion/HyperFrames，但實際可用能力必須透過工具登錄檔確認。
第一次不要直接做長影片。先執行零 Key 示例或 15 至 30 秒測試片段，再檢查輸出檔案、時長、音軌和日誌。

安裝前先做環境檢查

不要等 make setup 中途失敗後才查版本。先執行：

1
2
3
4
5


python3 --version
node --version
npm --version
ffmpeg -version
git --version

Python 應不低於 3.10，Node.js 應不低於 18。只要 ffmpeg -version 無法執行，後續編碼、字幕燒錄或音訊混合就不可能完整透過。

macOS 和 Ubuntu 可以分別安裝 FFmpeg：

1
2
3


brew install ffmpeg
sudo apt update
sudo apt install ffmpeg

macOS 或 Linux 安裝

官方快速開始如下：

1
2
3


git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

沒有 make 時，使用虛擬環境執行手動安裝，避免把依賴寫進系統 Python：

1
2
3
4
5
6
7
8


python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cd remotion-composer
npm install
cd ..
python -m pip install piper-tts
cp .env.example .env

安裝結束後重新開啟終端時，需要再次執行 source .venv/bin/activate。

Windows PowerShell 安裝

Windows 不要直接照抄 Bash 的 source 和 cp：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


git clone https://github.com/calesthio/OpenMontage.git
Set-Location OpenMontage
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Set-Location remotion-composer
npm install
Set-Location ..
python -m pip install piper-tts
Copy-Item .env.example .env

若 npm install 返回 ERR_INVALID_ARG_TYPE，官方 README 給出的替代命令是：

1

npx --yes npm install

如果 PowerShell 拒絕啟用指令碼，先確認是執行策略問題，而不是反覆重建環境。也可以不啟用，直接用 .\.venv\Scripts\python.exe 執行後續 Python 命令。

用登錄檔驗證實際能力

檔案安裝完成不代表影片工具都已發現。在倉庫根目錄、虛擬環境已啟用的情況下執行：

1
2


python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.provider_menu(), indent=2))"

第一條用於確認當前機器能夠支援哪些生產能力，第二條顯示可以選擇的 Provider。命令非零退出、Python 匯入失敗或返回空能力時，都不應繼續讓 Agent 製作完整影片。

從零 Key 示例開始

OpenMontage 官方提供 make demo 作為低成本渲染入口：

1

make demo

也可以讓 Codex、Claude Code 或 Cursor 在已開啟的倉庫中執行一個範圍明確的任務：

1

Make a 30-second animated explainer about why the sky is blue, with narration and captions. Use only tools available without paid API keys.

驗收時不要只看 Agent 的總結。先定位新生成的 MP4，再用 FFprobe 檢查媒體流：

1
2


find . -type f -name "*.mp4" -print
ffprobe -v error -show_entries format=duration:stream=codec_type,codec_name -of json PATH_TO_OUTPUT.mp4

合格結果至少應包含非零時長的影片流；要求配音時還應有音訊流。只有專案檔案、沒有最終 MP4，說明流水線未完成。

配置 Provider，但不要一次開啟全部 Key

複製 .env.example 後，只加入本輪測試需要的服務：

1
2
3
4
5
6


PEXELS_API_KEY=your-key
PIXABAY_API_KEY=your-key
UNSPLASH_ACCESS_KEY=your-key
ELEVENLABS_API_KEY=your-key
OPENAI_API_KEY=your-key
FAL_KEY=your-key

先驗證免費素材或單個 Provider，再逐個增加能力。把所有 Key 同時寫入後才開始測試，會讓 401、429、額度不足和模型不可用混在一起。.env 不應提交到 Git；提交前執行 git status --short，確認它沒有進入暫存範圍。

本地 NVIDIA GPU 路徑需要額外安裝：

1

make install-gpu

然後再啟用對應模型：

1
2


VIDEO_GEN_LOCAL_ENABLED=true
VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b

本地生成失敗時先檢查 CUDA、視訊記憶體和模型下載，不要把“Python 可以匯入”誤判成“GPU 推理可用”。

從參考影片發起任務

參考影片更適合用於約束節奏、結構和鏡頭語言，而不是複製原內容：

1

Analyze this reference video and propose three original 45-second variants about quantum computing. Keep the pacing pattern, but do not reuse its script or assets. Show estimated tool choices and cost before generation.

在素材生成前檢查 proposal、預計費用和 render_runtime。資料驅動解說通常更適合 Remotion，偏 HTML/CSS 動效的內容可能走 HyperFrames；真正使用哪條路徑，應以專案記錄為準。

常見失敗怎麼判斷

現象	先檢查	判斷標準
`ModuleNotFoundError`	當前 Python 路徑和虛擬環境	`python -c "import sys; print(sys.executable)"` 應指向 `.venv`
`ffmpeg` 找不到	PATH 與 FFmpeg 安裝	新終端中 `ffmpeg -version` 仍能成功
Remotion 安裝失敗	Node/npm 版本、`remotion-composer/node_modules`	`npm install` 必須零退出，不能只看到部分包下載
Provider 請求失敗	對應環境變數、額度和 Provider 日誌	區分 401、429、超時與模型不存在，不要連續更換多個 Key
有畫面無聲音	TTS 產物、音軌和 FFprobe 輸出	MP4 中應出現預期音訊流
Agent 聲稱完成但沒有成片	專案輸出目錄和最終質檢步驟	必須找到可播放 MP4 並透過 FFprobe

恢復到可工作的安裝狀態

依賴環境損壞時，不要直接覆蓋整個倉庫。先保留現場並確認程式碼是否被 Agent 改動：

1
2
3


git status --short
git rev-parse --short HEAD
python -c "import sys; print(sys.executable)"

可以把舊虛擬環境改名為 .venv-broken，再按安裝步驟建立新的 .venv；這樣仍可對比舊環境。前端依賴問題應只在 remotion-composer 內重灌，不要同時更換 Python、Node、FFmpeg 和 Provider。

如果新 Provider 或 GPU 配置導致失敗，先從 .env 移除剛加入的那一項，重新執行能力登錄檔和零 Key 示例。恢復標準不是“錯誤消失”，而是同一個短片樣本重新生成，並透過 FFprobe 檢查。

最終驗收清單

Python、Node、FFmpeg 在新終端中都能讀取版本。
兩條工具登錄檔命令零退出，並顯示符合預期的能力和 Provider。
一個 15 至 30 秒測試任務生成了可播放 MP4。
FFprobe 顯示非零時長以及預期的影片、音訊流。
.env 和生成素材沒有誤入 Git。
已實際演練移除新增 Provider 後回到零 Key 或上一可用配置。

OpenMontage 適合願意檢查中間產物和成本的流水線實驗，不適合在沒有驗收記錄時直接承擔商用批次生產。先把一個短樣本做成可重複基線，再增加影片長度、Provider 和本地 GPU，排錯成本會低很多。