framevelo 是做什麼的？
FrameVelo 將一個透過程式碼繪製影格的頁面轉換成 MP4。影格會留在 GPU 上（使用 drawElementImage 或頁面的 canvas），並直接送入硬體編碼器，因此相比於基於截圖的渲染器，渲染所需的 CPU 和記憶體僅為其一小部分。HyperFrames 專案由官方 HyperFrames 管線編譯；FrameVelo 只取代捕捉與編碼階段。
呼叫方式
當此外掛的 MCP 工具可用時，請直接使用。首次啟動時，外掛會將 FrameVelo 安裝到 ~/.cache/framevelo（約需一分鐘）；如果安裝外掛後工具仍未出現，請稍候並重新連線（/mcp），或使用下方的 CLI。
render：渲染；回傳輸出路徑、影格數、尺寸、時間統計、警告以及最後幾行日誌。doctor：檢查 Node、FFmpeg、Chrome、drawElementImage、硬體編碼器以及 HyperFrames 支援。install_browser：當未安裝 Chrome 151+ 時，下載 chrome-headless-shell（約 100 MB）。
若無工具可用，請執行 CLI。加上 --json 會將結果（或 {"error": ...}）輸出至 stdout：
npx -y -p github:gnipbao/framevelo -p @hyperframes/[email protected] -p @hyperframes/[email protected] framevelo render /abs/project -o /abs/out.mp4 --json -q
第一次執行 npx 需要約 30 秒安裝。如果經常需要渲染，建議使用者一次性安裝：npm install -g github:gnipbao/framevelo @hyperframes/[email protected] @hyperframes/[email protected]。CLI 與工具接受相同的選項，以旗標形式傳遞（--frames 30 --quality draft）。執行 framevelo render --help 可列出所有選項。
請使用絕對路徑。一次只執行一個渲染作業：它們共用同一個硬體編碼器，而且 MCP 伺服器本身也會排隊。
工作流程
- 尋找輸入：包含
index.html的專案目錄，或一個.html檔案。時長、FPS 與尺寸由頁面決定（HyperFrames 的data-duration/data-fps/data-width、window.__framevelo.duration、GSAP 時間軸長度、window.__comp）。只有在需要覆蓋時才傳遞這些參數。 - 預覽片段：當合成內容是新的或剛修改時：
{ input, output: "/tmp/preview.mp4", start: 2, frames: 30, quality: "draft" }。這只需要幾秒鐘。檢查某一幀：ffmpeg -v error -ss 0.5 -i /tmp/preview.mp4 -frames:v 1 /tmp/preview.png，然後檢視 PNG。 - 完整渲染：使用預設值。加入
scale: 2可從 1080p 版面輸出 4K，或subframes: 3可開啟動態模糊。 - 檢查結果：
frames應符合預期幀數；audio在合成包含聲音時為 true；閱讀warnings。screenshotFrames > 0表示某些區間未通過驗證，改用截圖方式捕捉（結果仍正確，但較慢）。 - 回報：輸出路徑、長度、大小以及耗時（
wallMs）。
使頁面可渲染
每個影格必須是時間的純函數。FrameVelo 會依序尋找以下驅動方式來跳轉頁面：
window.__framevelo = { seek(t), duration, fps }。seek可以回傳 Promise。window.__seek(t)，可搭配選擇性的window.__duration。- 暫停的 GSAP 時間軸，位於
window.__timelines.main（或第一個鍵）。
<canvas id="scene" width="1920" height="1080"></canvas>
<script>
const g = document.getElementById("scene").getContext("2d");
function draw(t) {
g.fillStyle = "#05060a";
g.fillRect(0, 0, 1920, 1080);
g.fillStyle = "#6cf";
g.fillRect(200 + 300 * t, 500, 120, 120);
}
window.__framevelo = { duration: 4, seek: draw };
</script>
- 使用
<video data-start="1.5" src="clip.mp4">將素材放入時間軸（可選data-media-start、data-duration、data-playback-rate）。FrameVelo 會將影片跳轉到精確的影格；長 GOP 來源會自動建立快取的 all-intra 代理。 Math.random會被固定種子，因此渲染可重複。requestAnimationFrame迴圈、CSS 轉場、Date.now()和performance.now()動畫無法被跳轉。請將它們移至seek(t)或暫停的 GSAP 時間軸。- 在暴露驅動介面前，請等待頁面內的資源（字型、圖片）載入完成，或從
seek回傳 Promise。
值得了解的選項
| 需求 | 參數 |
|---|---|
| 快速檢查 | frames: 30, quality: "draft", start: <s> |
| 從 1080p 版面輸出 4K | scale: 2 |
| 未宣告尺寸的垂直頁面 | viewport: "1080x1920" |
| 更小的檔案 | codec: "hevc" |
| 動態模糊 | subframes: 3（以及 shutter，預設 0.5） |
| 取代配樂 | audio: "/abs/music.m4a" |
| 捕捉特定元素 | selector: "#stage" |
| 在透明 DOM 上疊加顏色 | background: "#000" |
| code-video skill 未找到 | mounts: {"/@skill/": "/abs/path/to/code-video"} |
| 將 HyperFrames 專案視為一般頁面 | hyperframes: false |
失敗處理
| 訊息 | 處理方式 |
|---|---|
Chrome not found | 呼叫 install_browser（或執行 framevelo browser install），然後重新渲染。 |
FFmpeg / FFprobe failing in doctor | 請使用者安裝 FFmpeg（brew install ffmpeg）。請勿自行安裝系統軟體。 |
The page exposes no way to seek time | 頁面需要時間驅動；請參閱「使頁面可渲染」。 |
Unknown duration | 傳遞 duration 或 frames，或在頁面中宣告時長。 |
The composition failed to set up | 合成內容中有腳本錯誤。請修正頁面；訊息中會包含頁面錯誤。 |
No element matches selector / Nothing to capture / has no size | 將 selector 指向一個有尺寸的可見元素，或修正版面配置。 |
Rendering a HyperFrames project needs ... @hyperframes/producer | 使用上面的 npx -p @hyperframes/... 指令，或在 FrameVelo 旁安裝這些套件。 |
No paint event within ... | 頁面停止繪製，通常是腳本當機。請在瀏覽器中檢查。 |
渲染是原子性的：失敗或取消的渲染不會留下輸出檔案。