🎬 Remotion 渲染平台 — 說明手冊
對應版本 v1.3 · 最後更新 2026-07-27 · https://remotion.candle.com.tw
這是什麼
用版型 + 參數自動出短影音的平台。你不用開剪輯軟體:選一個版型、填內容(或直接用一句話讓 AI 填),後端就用 Remotion 渲染成 mp4,完成後推到 Telegram / LINE。
- 會做的事:字卡、長條圖動畫、TTS 配音敘事(含自動字幕)、封面靜態圖、品牌浮水印片頭尾、批次量產、定時自動出片。
- 不做的事:影片剪輯(不是剪輯軟體)、對外開放註冊。
- 四種入口:Prompt(AI 填參)、手動表單、批次(JSON/CSV)、排程(cron)。四種都能組合配色 / 品牌 / 背景音樂 / 通知。
登入
- 網址
https://remotion.candle.com.tw,帳號密碼登入,session 保留 7 天。 - 第一次登入:密碼 = 你自己的 API key,登入後系統會強制你設新密碼(至少 8 碼)。
- 忘記密碼 → 請 admin 在管理頁按「清密碼」,再用 API key 重走一次首次登入流程。
- 程式 / agent 走
x-api-keyheader,完全不受登入機制影響(見 API)。
① Prompt 出片(AI 選版型、AI 填內容)
在「✨ Prompt 出片」描述你要的影片,AI 會挑版型並填好參數,直接排進渲染。
做一支直式字卡,主標「週五全員大會」,副標「下午三點 會議室A」,深藍底
做一支配音敘事,旁白介紹我們的新產品,用 16:9- LLM 依管理頁的 router 順序 failover(目前 qwen73 優先 → claude → gemini)。
- 選了「套用配色」時品牌色蓋過 AI 選的顏色。
- AI 不會幫你選素材庫的背景圖 / 背景音樂(它不可能知道素材 id)——那些要自己在下拉選。
- 典型耗時:字卡約 10 秒內,配音敘事約 25 秒(要跑 TTS + 字幕對齊)。
② 手動出片(表單 + 即時預覽)
選版型後,表單會依該版型的欄位自動生成(色票、下拉、勾選、長文字框)。右邊的「👁 即時預覽」跟著參數即時變動,不用先出片就能看版面。
預覽是瀏覽器端算的,品牌套版與背景音樂不在預覽內(那兩項是出片後的合成階段)。配音敘事的長度預覽只是用字數估算,實際長度由 TTS 決定。
- JSON 模式:按「JSON 模式」可直接貼參數 JSON,適合從別處複製設定。
- Jobs 清單的 ✎ 會把該支影片的參數帶回表單,改一個字再送出 = 新的一支。
③ 批次量產(一次出很多支)
用上面選好的版型 / 配色 / 品牌,貼進資料列,一列出一支。上限 200 列。
[{"title":"標題一","subtitle":"副標一"},{"title":"標題二"}]
或 CSV(首列 = 欄位名):
title,subtitle
標題一,副標一
標題二,副標二- 壞掉的列只跳過該列並回報原因,不會擋掉整批。
- 批次的優先序低於單發,不會卡住你臨時要出的片。
- 通知只在整批跑完發一則彙總(成功 N / 失敗 M),不會洗版。
④ 排程出片(定時自動出)
先在上面把效果調到滿意,再到「⏰ 排程出片」建立排程。時區固定 Asia/Taipei。
兩種參數來源
| 模式 | 行為 | 適合 |
|---|---|---|
| 🛠 手動 | 固定版型 + 固定參數重複出片,只有時間變數會變 | 每日早報字卡、固定格式提醒 |
| ✨ Prompt | 每次觸發都重跑一次 AI 填參,內容會有變化 | 需要每次不一樣的內容 |
頻率(cron 五欄:分 時 日 月 週)
| 寫法 | 意思 |
|---|---|
0 9 * * * | 每天 09:00 |
0 9 * * 1-5 | 平日 09:00 |
0 18 * * 5 | 每週五 18:00 |
0 9 1 * * | 每月 1 號 09:00 |
0 * * * * | 每小時整點 |
下拉有常用預設;打字時下方會即時顯示接下來三次的觸發時間,寫錯會馬上提示。
時間變數
標題與文字參數可以寫變數,每次觸發自動代入當下時間:
{date} 2026-07-27 · {time} 09:00 · {datetime} · {year} {month} {day} · {weekday} 週一
影片標題:早報 {date}
副標:{weekday} 晨間更新操作
- ▶ 立即跑一次(不影響下次排程時間) · ⏸/▶️ 停用 / 啟用 · ✎ 編輯(參數帶回上面表單) · 🗑 刪除排程(已出的片不受影響)
- 排程只能由建立者本人或 admin 修改 / 刪除,但所有人都看得到清單。
限制與保護
- 兩次觸發間隔至少 5 分鐘(避免把渲染佇列灌爆),cron 必須是 5 欄。
- 建立當下就會試組一次參數,壞參數當場擋下來,不會等到半夜才炸。
- 停機補跑規則:平台停機錯過的排程,只補跑一小時內的那一次;更舊的直接跳過不補(不會一開機吐出一堆過期影片)。
- 排程總數上限 50 支。
版型與參數
textcard — 直式字卡(9:16)
| 參數 | 說明 |
|---|---|
title 必填 | 主標題,≤40 字 |
subtitle | 副標,≤80 字 |
bgImage / bgImageDim | 素材庫背景圖 + 壓暗程度(0–0.9) |
bgColor accentColor textColor | 底色 / 重點色 / 文字色 |
durationSec | 長度 2–30 秒(預設 4) |
chartbars — 長條圖動畫(16:9)
| 參數 | 說明 |
|---|---|
title 必填 | 圖表標題,≤60 字 |
data 必填 | 1–12 筆 {"label":"一月","value":120} |
barColor bgColor textColor | 長條 / 底色 / 文字色 |
durationSec | 長度 3–60 秒(預設 6) |
narrated — TTS 配音敘事(可直可橫)
| 參數 | 說明 |
|---|---|
script 必填 | 旁白文字 ≤1500 字,會轉語音 + 自動生成同步字幕 |
title | 開場標題(可留空) |
voiceId | 語音,下拉會列出 tts2 現有的聲音(預設溫柔女聲 HsiaoChen) |
format | 9:16 或 16:9 |
showCaptions | 是否顯示字幕 |
bgImage / 顏色 | 同字卡 |
影片長度由語音長度決定(沒有 durationSec)。字幕文字一律用你寫的原稿(繁體、用字、專有名詞都正確),
時間軸則靠語音辨識對齊,所以字會準確落在唸到的位置。
共用選項(所有版型都能用)
| 選項 | 說明 |
|---|---|
| 套用配色 | 管理頁定義的色票,只會蓋掉該版型有的色欄。優先於 AI 選色。 |
| 品牌套版 | 浮水印 logo(四角/大小/透明度)+ 片頭卡 + 片尾卡。可設「預設」自動套,或「強制」全部都套;選「(不套用品牌)」可單支跳過。 |
| 背景音樂 | 選素材庫的音樂 + 音量;勾「自動壓低」= 有旁白時音樂自動變小(ducking),旁白結束回復。音樂比影片短會自動循環,結尾淡出。 |
| 輸出形式 | 影片(mp4) 或 靜態圖(封面 / 縮圖,可指定抽第幾秒、PNG/JPEG)。靜態圖只套浮水印,片頭尾與背景音樂對單張圖沒意義。 |
| 完成後推播通知 | 取消勾選 = 這一支不推播(兩條管道都靜音)。 |
小技巧:配音敘事出封面圖時不會跑 TTS(約 2 秒就好),想快速拿一張社群縮圖很方便。
出片後自動品管
每支片子出完會自動抽 3-4 格檢查一遍(約多花 10-15 秒)。Jobs 清單多了一欄「品管」:
| 顯示 | 意思 |
|---|---|
| ✅ | 抽樣的每一格都沒問題 |
| ⚠️ N | N 個提醒(不算不合格),滑鼠移上去看細節 |
| ❌ N | N 個問題,滑鼠移上去看是什麼 |
| 略過 / - | 這支沒跑品管(或是加這個功能之前的舊 job) |
會抓到的問題:文字被切到畫面外、出現缺字方框(字型沒有那些字)、 影片中間有黑畫面、該有聲音卻是無聲(配音 / 配樂的片)、 畫面上找不到應該出現的文字。片頭片尾的黑只算提醒(那通常是淡入淡出)。
品管不合格不會擋下成品 —— 片子照樣產出、照樣能下載,只是標記給你看,推播通知也會多一行提醒。要不要重出由你決定。
文字辨識偶爾會認錯字(襯線體中文尤其容易),所以「找不到文字」這項一定會同時告訴你畫面上實際讀到的是什麼,一眼就能分辨是真的漏了還是認錯。走 API 出片時可用 qa:false 關掉這支的檢查,或用 qaExpect:["..."] 明確指定畫面上該出現哪些字。
素材庫
- 圖片 ≤6MB(PNG/JPEG/WebP)—— 背景圖、品牌 logo。
- 音樂 ≤25MB(MP3/M4A/WAV/OGG)—— 背景音樂。
- 出片頁下方可直接上傳,上傳完立刻能在下拉選到;管理頁的「🖼️ 素材庫」可預覽 / 試聽 / 刪除。
- 刪除限 admin 或上傳者本人;正在被品牌當 logo 用的圖片會擋下來。
Jobs 與檔案
| 操作 | 說明 |
|---|---|
| 下載 / 縮圖 | 完成後「輸出」欄是下載連結;靜態圖直接顯示縮圖 |
| ✎ 編輯 | 參數帶回表單,送出 = 新的一支(原本那支不動) |
| ↻ 重渲 | 相同參數重新算一次 |
| 🗑 刪除 | 連同輸出檔一起刪;正在渲染中的擋下(409) |
保存期限:輸出檔 30 天後自動清除。要長期保留請自己下載,或在伺服器上替該檔案建一個同名
.pinned 檔釘住。
下載連結是難猜的 UUID 且不需登入(方便分享,LINE 附檔也靠它)——不想外流的內容別把連結貼出去。
通知(Telegram / LINE)
兩條管道各自獨立開關,在管理頁設定。完成通知會附上:標題、版型、長度、檔案大小、品牌、配樂、字幕數、排程名稱與下載連結。
| Telegram | LINE | |
|---|---|---|
| 影片 | 直接上傳 mp4(>45MB 退成連結) | 用公開連結送影片訊息(自動產生預覽縮圖) |
| 靜態圖 | 照片訊息(>10MB 退連結) | 圖片訊息 |
| 失敗 | 兩邊都會收到失敗原因(重試用完才發一次,不會重複洗) | |
| 批次 | 整批跑完只發一則彙總 | |
LINE 有月配額(免費方案 200 則 / 月)。平台把說明文字與影片合併成一次推送,所以一支片只花 1 則。
管理頁「發測試訊息」會順便顯示本月用量。若配額用完,LINE 會退回失敗——Telegram 不受影響。
管理頁(限 admin)
登入後右上角 ⚙️ 管理。
- 使用者:建帳號、發 / 重發 API key(key 只在建立或重發時顯示一次)、停用、清密碼。最後一個 admin 不能刪或停。
- 配色:色票 CRUD,出片時可一鍵套用。
- 品牌套版:logo 上傳、浮水印位置 / 大小 / 透明度、片頭尾文字與秒數、預設 / 強制。
- LLM Router:Prompt 模式用的後端順序,可排序 / 啟停 / 測試連通性。
- Telegram 通知 / 💬 LINE 推播:啟用、token、對象、要不要附檔。公開網址要填,LINE 附檔與通知裡的下載連結都靠它。
- 素材庫:全站素材的預覽 / 試聽 / 刪除。
API(給 agent / n8n / OpenClaw)
認證用 x-api-key header(每個使用者一把)。所有路徑前綴 /api。
# 出一支字卡
curl -X POST https://remotion.candle.com.tw/api/jobs \
-H "x-api-key: $KEY" -H "content-type: application/json" \
-d '{"template":"textcard","title":"公告",
"props":{"title":"系統維護","subtitle":"今晚 10 點","durationSec":5}}'
# → {"id":"","state":"queued"}
# 查狀態(completed 後 output 就是下載路徑)
curl -H "x-api-key: $KEY" https://remotion.candle.com.tw/api/jobs/
# 一句話出片(AI 填參)
curl -X POST https://remotion.candle.com.tw/api/prompt \
-H "x-api-key: $KEY" -H "content-type: application/json" \
-d '{"prompt":"做一支直式字卡宣傳週五聚餐,活潑一點"}'
# 出封面圖而不是影片
-d '{"template":"textcard","output":"still","stillFormat":"jpeg","stillTimeSec":2,"props":{...}}' | 端點 | 用途 |
|---|---|
GET /api/templates | 版型清單(含 JSON Schema,可用來自動組參數) |
POST /api/jobs · GET /api/jobs/:id | 出片 / 查狀態 |
POST /api/jobs/:id/rerender | 相同參數重渲(可覆蓋部分 props) |
POST /api/prompt · GET /api/prompt/:id | AI 填參出片 / 查結果 |
POST /api/batch · GET /api/batch/:id | 批次量產 / 查批次進度 |
GET POST PUT DELETE /api/schedules[/:id] | 排程 CRUD |
POST /api/schedules/:id/run · /toggle | 立即跑一次 / 停用啟用 |
GET /api/schedules/preview?cron= | 驗證 cron 並回傳接下來三次時間 |
GET POST /api/assets | 素材清單 / 上傳(base64 data URL) |
GET /api/palettes · /api/brands · /api/voices | 配色 / 品牌 / 語音清單(給下拉或程式選用) |
共用選項在 body 直接帶:paletteId、brandId("none" = 不套)、bgm + bgmVolume + bgmDuck、output、notify:false、title。
疑難排解
| 症狀 | 原因 / 處理 |
|---|---|
props validation failed | 參數不合該版型的 schema(缺必填、超長、顏色不是 #rrggbb)。錯誤訊息會指出是哪個欄位。 |
unknown image/audio asset | 素材 id 不存在或種類不對(把音樂填到背景圖欄之類)。 |
排程存不下去:排程間隔不能小於 5 分鐘 | cron 太密集,改成 5 分鐘以上的間隔。 |
| 配音敘事字幕怪怪的 / 擠在開頭 | 語音辨識服務可能沒回來,系統會自動退回「按比例估算」的字幕。重渲一次通常就好。 |
| 出片完成但沒收到通知 | ①該支有沒有取消勾選推播 ②管理頁該管道有沒有啟用 ③LINE 月配額是否用完(測試按鈕會顯示用量)。 |
| LINE 只收到文字沒有影片 | 公開網址沒填 https,或 LINE 抓不到檔案 —— 訊息裡會註明原因。 |
| 頁面改了沒變 / 版本號不對 | 強制重新整理(Ctrl+F5)。標題右邊的版本號是判斷依據。 |
| Prompt 模式一直失敗 | 管理頁 LLM Router 按「測試」看哪個後端掛了,調整順序或改用手動出片。 |
運維速查
給維護者用;一般使用者可以略過。
| 項目 | 內容 |
|---|---|
| 主機 | .89(remotion),程式在 /opt/remotion-platform,產出與設定在 /data/remotion |
| 元件 | redis + api(:8090,含排程器)+ worker(渲染)三個容器,另有 host 上的 remotion-llm systemd 服務(Prompt 模式用,因為 claude 憑證在 host) |
| 對外 | gw-6 → NPM(.206)→ .89:8090,Let's Encrypt 憑證 |
| 相依 | TTS 與字幕靠 .74(:8082 / :8087),Prompt 模式靠 .73 LLM。.74 重開機後 whisper 容器不會自己回來,字幕會靜默退回估算,記得檢查。 |
| 改前端 | webui/ 是 bind-mount,改完重新整理即可,不必 rebuild |
| 改後端 | docker compose build api worker && docker compose up -d api worker;改到 templates.js 另外 sudo systemctl restart remotion-llm |
| 看 log | docker compose logs -f worker(渲染 / 通知)、logs -f api(請求 / 排程)、journalctl -u remotion-llm -f |
| 設定檔 | /data/remotion/config/*.json(使用者、配色、品牌、素材、通知、排程),通知檔含 token 權限 600 |
有問題或想加功能 → 直接跟 Claude 說。