remotion-render-pipeline
將腳本轉換為已交付的 MP4。
觸發條件
remotion-composition-builder回報ready: true。- 使用者說「渲染它」/「發送它」,並帶有已知的工作任務。
輸入
jobIdcomposition— 與src/Root.tsx中 ID 匹配(例如Explainer)outputPath— 相對於remotion-studio/output/props— 完整的輸入屬性(品牌 + 分鏡 + ...)作為 JSONlinear—{teamId, projectId}用於工單路由
方法
- 前置型別檢查 —
cd remotion-studio && npx tsc --noEmit。若失敗,將錯誤返回給remotion-composition-builder。 - 旁白合成 —
render/voiceover.ts將每個場景的 MP3 寫入public/audio/{jobId}/scene-N.mp3(在public/下以便staticFile()解析)。使用快取鍵sha1(voiceId|style|text)。若缺少ELEVENLABS_API_KEY則跳過 — 腳本仍須僅以螢幕文字渲染。 - 渲染 —
npx tsx render/render.ts --comp={composition} --out={outputPath} --props='{...}' --jobId={jobId}。設定 600 秒超時;若掛起或崩潰則重試一次。 - 驗證 — 檔案存在,時長 ±0.5 秒預期值,編碼
h264,解析度符合腳本,大小小於 100MB。 - 交付:
- 上傳至 Supabase 儲存桶
remotion-renders— 簽署 URL,保留 90 天。 - 透過
app.server.telegram_video.send_telegram_video()(共用工具)傳送至 Telegram。若檔案大於 45MB,則發送簽署 URL 連結而非內嵌上傳(Telegram 上限為 50MB)。 - 在
{teamId}/{projectId}下開啟 Linear 工單,包含:渲染 URL、來源簡報、BrandConfig 版本(src/brands/{slug}.ts的 git SHA)、腳本檔案路徑。
- 上傳至 Supabase 儲存桶
- 狀態 — 將摘要寫入
.research/renders/{jobId}.json。
輸出
{
"jobId": "ra-nir-explainer-2026-04-28T15-30-00",
"mp4Path": "remotion-studio/output/ra-nir-explainer-2026-04-28T15-30-00.mp4",
"supabaseUrl": "https://<project>.supabase.co/storage/v1/object/sign/remotion-renders/...",
"telegramSent": true,
"linearIssue": "RA-2049",
"validation": { "durationSec": 60.0, "codec": "h264", "resolution": "1920x1080", "sizeMB": 12.4 }
}
邊界
- 當
tsc --noEmit失敗時,絕對不要執行渲染 — 會浪費 2-5 分鐘產生必定有問題的輸出。 - 在渲染驗證通過之前,絕對不要自動合併來源 PR(腳本 + 品牌變更)。
- 絕對不要將帶有
[DRAFT]標記的渲染上傳到品牌儲存桶 — 草稿應傳送至remotion-drafts。
失敗升級
- 超時 / 掛起 → 終止,重試一次 → 若第二次仍失敗,則開啟 Linear 工單,設定
priority: 2,附上 stderr。 - 驗證失敗(時長 / 編碼不符) → Linear 工單
priority: 3,附上差異與預期值。 - Telegram 失敗 → 改以
send_telegram_document()附加.mp4檔案。
重複使用的資源
render/render.tsrender/voiceover.tsapp/server/telegram_video.py(共用工具)config/harness/projects.json用於解析 Linear 團隊/專案
各專案 API 金鑰
此技能從呼叫專案內部(Synthex、Pi-SEO、RestoreAssist 等)被調用。每個專案透過其自己的 .env / .env.local 提供自己的金鑰。技能絕不從 Pi-Dev-Ops 讀取金鑰。
渲染時必需或可選的環境變數:
ELEVENLABS_API_KEY— 旁白合成。若缺失 = 僅以螢幕文字渲染(記錄警告,渲染繼續執行)。TELEGRAM_BOT_TOKEN,TELEGRAM_CHAT_ID— Telegram 傳送。若缺失 = 跳過 Telegram 步驟(MP4 仍會寫入磁碟並上傳至 Supabase(若有設定))。SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY— 簽署 URL 上傳。若缺失 = 跳過 Supabase 步驟。LINEAR_API_KEY— 工單建立。若缺失 = 跳過 Linear 步驟。REMOTION_LICENSE_KEY— 任何商業渲染在 Remotion 的公平原始碼授權下需要。
從專案 Shell 的調用模式:
cd ~/Pi-CEO/Synthex
source .env.local # 專案自己的金鑰
cd ~/Pi-Dev-Ops/remotion-studio
npx tsx render/render.ts \
--comp=Explainer \
--out=$OLDPWD/.remotion-renders/synthex-launch.mp4 \
--jobId=synthex-launch-$(date +%s) \
--props='{"brand":"synthex","hookSec":8,"ctaSec":8,"storyboard":[...]}'
或透過 Pi-Dev-Ops 協調器 API 調用,該 API 在會話建立時繼承呼叫專案的環境。
輸出慣例:預設將 MP4 寫入 <呼叫專案>/.remotion-renders/(已加入 .gitignore)— 將每個專案的成品保留在其自己的目錄樹中。可使用 --out=... 覆蓋。