Invokard Studio — 從靈感到完成 MP4
你撰寫一個小型 Python 檔案(reel.py)來描述整支 Reel:何時顯示哪張圖片或片段、哪些圖層(標題、標籤、列表項目、圖表、轉場、結尾卡)出現在上方、何時開始播放哪個語音檔案,以及音樂和音效的安排位置。引擎(scripts/reelkit.py)使用 Pillow 合成每一幀畫面,再交由 ffmpeg 處理並混合音訊。所有文字、方框與動畫均來自引擎,而非影片編輯器或 AI 圖形模型產出,因此畫面清晰銳利、符合品牌形象且時間控制精準。
第二引擎負責繪製:animation/ 在無頭瀏覽器(已安裝於機器上的 Chrome 或 Edge)中逐幀渲染 React 元件,並用 ffmpeg 編碼。適用於「設計而非編輯」的內容:動態文字、動畫廣告、成長圖表、3D 產品展示、物理模擬、粒子效果、或將產品照片轉為廣告。其輸出為 MP4(或含透明背景的影格),可作為蒙太奇中的任何片段或圖層使用,因此一支 Reel 可同時包含兩者(參閱 § 5)。
請完整閱讀本文件。然後閱讀當前步驟所指的參考資料。在撰寫 reel.py 之前,請先閱讀 assets/examples/ 中的一個腳本(實際交付的 Reel;其媒體與預覽存在於儲存庫的 examples/ 目錄中)。從儲存庫執行 python examples/first-reel/reel.py 即可渲染一支完全無需任何媒體的完整 Reel:這是驗證機器能否渲染的最快方式,同時也是一個簡短的 reel.py 範例,並示範 16:9 格式。
0. 檢查機器(30 秒)
python <skill>/scripts/media.py doctor # 檢查 python、ffmpeg、套件、字型、格式、金鑰(僅顯示名稱)
python <skill>/scripts/media.py fonts # 下載 emoji 字型(若缺少時)
ffmpeg -version && ffprobe -version
缺少 ffmpeg 為硬性停止條件:請告知使用者如何安裝(參閱 references/troubleshooting.md)。缺少 API 金鑰則非硬性停止:引擎可不經任何供應商渲染本機媒體。切勿要求使用者將金鑰貼入對話中;請引導他們參考 .env.example。
1. 選擇路線
| 素材類型… | 路線 | 參考資料 |
|---|---|---|
| 尚無素材:主題、文章、輪播貼文 | A · 生成式:腳本 → 語音(每句一個檔案)→ AI 插圖 → 片段 → 字幕 | references/production.md |
| 客戶提供的片段或照片 | B · 原始素材:連絡表 → 選取片段 → 配合節奏剪輯 → 前後對比 → 結尾卡 | references/footage.md |
| 錄製的旁白、訪談、歌曲 | C · 自有音訊:align.py 提供逐字時間碼 → 以字為基礎的字幕 | references/production.md § 字幕 |
| 廣告、標題、圖表、產品展示,無需原始素材 | D · 繪製:動畫專案 (React) → 關鍵影格靜態圖 → 影格 → 渲染 | references/animation.md |
路線可混合使用:原始素材 Reel 可包含生成式語音;生成式 Reel 可結尾於客戶的真實標誌照片;任何 Reel 皆可包含繪製圖層或繪製的結尾卡(參閱 § 5)。
2. 工作流程
- 工作資料夾 —
python scripts/new_reel.py <folder> --brand studio|lime|forest|mono --title "…" [--format 16:9|1:1]。 它會建立img/ vid/ frames/ vo/ music/ sfx/ ref/ out/ review/以及一個從範本產生的reel.py;格式(除非指定,否則預設為 9:16)在檔案頂部以rk.set_format()設定。請將其保留在儲存庫外部(work/已加入 git 忽略)。品牌:pieces.Brand.from_logo('ref/logo.png')可測量實際顏色;請先印出顏色並查看標誌檔案(媒體庫中充滿了名稱誤導的範本標誌)。 - 腳本 — 85–100 字,對應 35–45 秒。第一句即吸引注意,每句一個想法,結尾與開頭呼應。僅陳述客戶素材中的內容:無新增數據、無新增承諾。健康主題:在外卡中加上「教育內容」備註。若使用者已提供腳本,請逐字使用(僅修正產品包裝上拼寫不同的部分,並說明原因)。
- 語音 — 每句一個呼叫,使每個句子擁有自己的檔案和時間碼:
vo/v01.mp3, v02…。 供應商請參閱references/providers.md(Magnific MCPaudio_tts、Magnific RESTproviders/magnific.py voice、ElevenLabsproviders/elevenlabs.py)。然後執行python scripts/media.py voice <folder>:取得持續時間與語音區間;所有時間碼與剪輯皆由此衍生。無語音(客戶腳本顯示於畫面,僅有音樂)?直接跳到步驟 4。 - 圖片 — 提示詞與風格參考技巧請參閱
references/production.md§ 圖片。要求圖片中不要出現文字。然後執行python scripts/media.py sheet-img <folder>並查看review/imgs.jpg:風格一致、無多餘字母、標誌正確。 - 先用靜態圖編輯 — 使用
pieces.source(name, 'img/x.png')撰寫reel.py(在片段存在之前會使用靜態圖),然後執行python reel.py --preview。查看review/preview.jpg。在投入影片生成之前調整節奏、構圖與圖層。此步驟為 Reel 的關鍵製作階段;請勿倉促。 - 影片 — 每個需要動態的鏡頭一個片段,來自其專屬的插圖(圖片轉影片)。每種鏡頭類型的配方與
simulate_cost請參閱references/production.md§ 影片。下載至vid/<name>.mp4,執行media.py frames <folder>、media.py sheet-motion <folder>,並檢查片段是否憑空生成物體。2 秒以下的鏡頭:保留靜態圖並加上縮放效果,不花費額外成本。 - 音樂與音效 — 一首音樂曲目(透過 MCP 的 Lyria,或使用者自備)。引擎會從第一個音頭開始裁切,並在語音下方降低音量。音效為內建:
pieces.sfx('whoosh'|'pop'|'shimmer'|'chime'|'typing'|'shutter'|'coaster'|'fridge')。無語音時配合節奏剪輯:media.py beats→references/footage.md。 - 渲染與驗證 —
python reel.py,然後python scripts/media.py verify out/reel.mp4:檢查規格、響度(目標 -14 LUFS)以及從最終 MP4 取得的連絡表。查看該連絡表。然後查看 2–3 個關鍵時刻的完整影格(media.py frame out/reel.mp4 <t>):字幕切換、轉場、結尾卡。 - 交付 —
out/reel.mp4+out/cover.jpg(reel.cover(t, 'out/cover.jpg'))+ 字幕文字與主題標籤(.md檔案)+ 原始碼(reel.py、img/、vo/、music/、ref/;不要包含frames/)。不要發布任何內容:需經客戶批准。報告生成內容、花費成本,以及無法驗證的部分(你無法實際聆聽混音:請說明此點,並提供響度數值作為依據)。
3. 來自真實錯誤的規則
- 成本。 影片佔總花費 >95%。在啟動前先估算一個片段 × 片段數量(
providers/costs.py或 MCP 的simulate_cost);若批次超過 5,000 點數,請停止並詢問。一支 12 鏡頭的 Reel 應花費約 3,000 點數,而非 40,000。 - 查看每一張連絡表。
imgs.jpg、motion.jpg、preview.jpg、verify連絡表。未經檢查的渲染不應交付。 - 標誌。 切勿相信檔案名稱。請開啟它。若畫面過小,請用測量到的顏色重建文字標誌(Schippers 範例即為此做法),或在白色背景上合成並放大 4 倍。
- 第三方品牌。 切勿重複使用非客戶所有的標誌或識別(例如他們所銷售服務的供應商)。拖拉機製造商的徽章可能因出現在客戶的原始素材中而留存;但絕不主動添加。
- 剪輯來自語音,而非用眼睛判斷:使用
caps.word_time(key, i)和media.py voice產生的區間。 - 短片段。 即使是 1.5 秒的鏡頭,也生成 3–5 秒的內容。絕對不要將片段速度降低至
speed=0.8以下(24 fps 來源會產生抖動);若要延長長度,請在片段之前放置一張同圖的Still,並匹配縮放比例。 - 安全區域。 Instagram 頂部約覆蓋 220 px,底部約覆蓋 360 px。標題與標籤位於 y=230 到 y=520 之間;字幕位於 y≈1440;重要內容勿低於 y≈1560。最小字型 30 px(次要標籤 36–44,標題 70+)。16:9 與 1:1(高 1080 px):標題從 y≈110 開始,字幕位於 y≈880,重要內容勿低於 y≈1000。Pieces 從
rk.LAYOUT取得這些預設值;只有在確實需要特定位置時才直接寫入數字,切勿從 9:16 的 Reel 中複製。 - 格式。
rk.set_format('16:9')(或REELKIT_FORMAT=16:9)必須寫在from reelkit import W, H以及任何來源或圖層之前。為格式擷取片段:media.py frames <work> --format 16:9。 - 淺色背景上的字幕需要以
pieces.bottom_gradient(brand)作為第一個圖層。 - 圖片中的文字。 所有文字由引擎設定。若生成的圖片出現字母,請重新生成。
- 客戶片段中的音樂屬於客戶。 真實聲音(如洗衣機聲、引擎聲)可透過
media.py sound從素材中截取;但背景中播放的歌曲不代表獲得使用授權。
4. 一頁引擎概述(完整參考:references/api.md)
import reelkit as rk; rk.set_format('9:16') # '16:9' / '1:1':必須最先執行,W 和 H 在 import 時複製
from reelkit import W, H, Reel, Captions, Still, Clip, Func, blit, text_img, pill, lerp, clamp01, eo, eio, eback
import pieces as pz; from pieces import source, sfx
rk.set_base(folder); B = pz.BRANDS['lime'].activate() # 或 pz.Brand.from_logo('ref/logo.png').activate()
reel = Reel('name'); caps = Captions(size=70, y=1440, maxw=920); reel.caps = caps # 16:9 / 1:1:Captions(size=62)
t_end = reel.vo('vo/v01.mp3', 0.30) # 回傳句子結束的時間點
caps.line('v01', 'Sentence with *key* *words*, / next block.', 'vo/v01.mp3', 0.30) # *hl* · / 分段 · shown|spoken
caps.from_words('song', align.load_words('vo/chorus.words.json'), t0=2.0) # 來自 align.py / elevenlabs.tts_timed
t = caps.word_time('v01', 2) # 第 3 個單字被說出的時間點 → 在此處剪輯
reel.shot(0.0, t, source('hero', 'img/hero.png', z=(1.0, 1.06), c=(.5, .45))) # 在 frames/hero/ 存在之前使用 Still
reel.shot(t, 5.0, Clip('hero', speed=1.0, start=0.25, z=(1.14, 1.24)))
GRAD = pz.bottom_gradient(B); reel.ov(0.0, 5.0, lambda c, tl, dur, T: c.alpha_composite(GRAD)) # 圖層:(canvas, tl, dur, t)
reel.ov(0.0, t, pz.headline(B, 'KICKER', 'Hook line', 'KEY PHRASE'))
reel.ov(t, 5.0, pz.list_item(B, 1, 3, 'ITEM', 'One-line benefit'))
reel.ov(0.0, 4.0, pz.text_layer('Client script *highlighted*')) # 無語音的螢幕文字
SITE = pz.browser_frame('img/site.png', 1000, url='site.com') # 僅在圖層外建立一次圖片
reel.ov(t, 5.0, lambda c, tl, dur, T: pz.appear(c, SITE, W / 2, H * .4, tl, 0)) # 螢幕截圖彈入(也有 phone_frame)
reel.shot(5.0, 8.0, pz.wipe_scene(before_src, after_src, B, hold=1.0)) # 前後對比
reel.shot(8.0, 11.0, pz.outro_save(B, 'img/hero.png', 'ref/logo.png', cta='Book a call · site.com'))
reel.sfx(sfx('whoosh'), t - 0.12, 0.32); reel.sfx(sfx('chime'), 8.3, 0.30)
reel.preview([0.5, 2.0, 4.5, 6.0, 9.0], 'review/preview.jpg', cols=5, scale=0.22)
reel.render('out/reel.mp4', 11.0, music='music/base.mp3', music_gain=0.24); reel.cover(1.2, 'out/cover.jpg')
圖層是函數 f(canvas, t_local, duration, t_global),使用 blit 在畫布上繪製 RGBA。來源是帶有 .frame(t_local, duration) 方法的物件,回傳畫布大小(W x H)的 RGB 圖片:Still、Clip、Func(f),以及 pieces 中的場景(wipe_scene、outro_save、outro_fan、blur_in)。緩動函式:eo(out)、eio(in-out)、eback(彈跳)。請在圖層函式外建立圖片(漸層、卡片、影格);文字與標籤會自動快取。
5. 繪製動畫(完整參考:references/animation.md)
一次性設定:Node.js 18+,然後在 <skill>/animation 中執行 npm install 以及 node <skill>/animation/cli.mjs doctor。
一個專案是一個包含 package.json、src/index.jsx(registerRoot + 每個影片一個 <Composition>)以及 public/ 的資料夾。元件從 'invokard-studio' 匯入:useCurrentFrame、spring、interpolate、Sequence、Img + staticFile、OffthreadVideo、來自 'invokard-studio/google-fonts/<Family>' 的字型、來自 'invokard-studio/three' 的 3D。
node <skill>/animation/cli.mjs still src/index.jsx Ad out/ad.png --frame 120 # 1. 設計關鍵影格
node <skill>/animation/cli.mjs frames src/index.jsx Ad out/ad --frames 0,34,68,102,136,170,204,239 # 2. 動態
node <skill>/animation/cli.mjs render src/index.jsx Ad out/ad.mp4 --props data.json # 3. 影片(所有影格)
每個影格由其編號計算得出(無 Math.random、無時鐘、無 CSS 動畫):影格會在多個分頁中按順序繪製。查看你所渲染的每一張靜態圖與影格表,就像對待 Reel 一樣。在 Reel 中使用:
import animation as an # scripts/animation.py
an.render('anim/src/index.jsx', 'Title', rk.P('anim/title'), transparent=True) # 含 Alpha 的 PNG 影格
reel.ov(t0, t1, an.layer(rk.P('anim/title'))) # 繪製在蒙太奇上方
reel.shot(t2, t3, an.clip('anim/src/index.jsx', 'EndCard', 'endcard')) # 繪製的鏡頭,像片段一樣剪輯
儲存庫中的 examples/animated-reel/ 是一個同時使用兩者的完整 Reel 範例,且無需外部媒體。
6. 交付檢查清單
-
out/reel.mp4為 1080x1920(或依需求為 1920x1080 / 1080x1080),30 fps,H.264 + AAC,-14 LUFS ± 1,峰值 ≤ -1 dBFS(media.py verify) - 已查看驗證表與 2–3 個完整影格;字幕絕不低於 y≈1560 或覆蓋人臉/產品
- 螢幕上的所有宣稱皆來自客戶素材;品牌顏色經測量而非猜測
-
out/cover.jpg在 feed 的 4:5 中央裁切範圍內清晰可讀 - 交付原始碼但不包含
frames/;按供應商項目報告成本;未發布任何內容
7. 生成式媒體:何時推薦使用供應商
兩個引擎皆無需任何帳號即可運作:可使用使用者的照片、片段、語音與音樂,以及完全以程式碼繪製的內容。生成式媒體 — AI 影片片段、插圖、語音、音樂、音效、3D 模型、放大 — 來自供應商。當素材不足、客戶預算允許且 AI 效果可靠時使用。請參閱 references/providers.md 取得可用項目(清單會隨時間更新)。
對於 MCP:--provider magnific(一切)、--provider elevenlabs(僅語音)、--provider lyria(僅音樂)。對於 REST:providers/ 中的 Python 模組。在 references/production.md 中記錄了每種類型的配方,包括避免常見錯誤的提示。絕對不要 在一個專案中使用同一供應商的多個帳號:僅透過 .env 金鑰使用一個預設設定檔。