Invokard Studio Local — 從使用者的素材到 MP4
您撰寫一個小型 Python 檔案 (reel.py),用來描述影片的構成:何時顯示哪張照片或片段、哪些圖層(標題、標籤、清單項目、圖表、轉場、片尾卡片)疊加其上、哪段語音檔何時開始,以及音樂與效果的位置。引擎 (scripts/reelkit.py) 使用 Pillow 合成每一格畫面,再透過 ffmpeg 編碼並混合音訊。所有內容均非在影片編輯器中手動調整:所有文字、方框與動畫均由引擎生成,因此清晰銳利、符合品牌規範且時間精準。
第二套引擎負責繪製:animation/ 會在使用者電腦上已安裝的 Chrome 或 Edge 瀏覽器中(無頭模式)逐格渲染 React 元件,再以 ffmpeg 編碼。適合用於非實拍素材:動態文字、動畫廣告、成長圖表、3D 產品展示、物理模擬、粒子效果,或將產品照片轉為廣告。其輸出為 MP4(或透明背景序列圖),可像一般片段或圖層一樣被組合進影片中,因此同一支影片可同時包含實拍與繪製元素(§ 5)。
一切都在本機執行。此技能在運作過程中絕不上傳、下載或呼叫任何服務:字型已內建,音效已內建,素材均來自使用者。請先完整閱讀本文件,再參閱當前步驟所指出的參考文件。外掛資料夾中的 examples/first-reel/reel.py 與 examples/animated-reel/reel.py 展示了完全不需要外部素材即可渲染完整影片的範例,是快速確認機器能否執行的最簡方法。
0. 檢查機器(30 秒)
python <skill>/scripts/media.py doctor # 檢查 python, ffmpeg, 套件, 字型, 格式
ffmpeg -version && ffprobe -version
缺少 ffmpeg 是硬性障礙:請告訴使用者如何安裝(references/troubleshooting.md)。缺少 Pillow 或 numpy:python -m pip install Pillow numpy(它會從 PyPI 下載一次;執行前請先告知使用者)。
1. 選擇路線
| 素材類型 | 路線 | 參考文件 |
|---|---|---|
| 使用者自己的影片或照片 | A · 實拍素材:製作聯絡表 → 挑選片段 → 踩點剪輯 → Before/After → 片尾卡片 | references/footage.md |
| 使用者可錄製的劇本 | B · 語音:使用者為每個句子錄製一個檔案 → 逐字字幕 → 依單詞剪輯 | references/production.md |
| 廣告、標題、圖表、商品展示,無實拍素材 | C · 繪製動畫:動畫專案(React)→ 關鍵影格靜態圖 → 逐格畫面 → 渲染 | references/animation.md |
| 僅有文字與音樂 | D · 螢幕文字:將客戶的劇本以動畫文字形式顯示在繪製背景或照片之上,並踩點剪輯 | references/production.md § 字幕 |
各條路線可以混搭:實拍影片可以加入使用者語音;任何影片都可以包含繪製圖層、繪製圖表或繪製片尾卡片(§ 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()設定。品牌:pieces.Brand.from_logo('ref/logo.png')會測量實際顏色;請先列印這些顏色並檢視 logo 檔案(資料夾內常有不符實際的檔名)。 - 劇本 — 85-100 字,對應 35-45 秒。第一句就要吸引人,每個句子一個想法,結尾呼應開頭。只陳述使用者素材中確實存在的內容:不要加入新的數據或承諾。如果使用者已提供劇本,就原文照用。
- 語音 — 使用者錄製語音,每個句子一個檔案 (
vo/v01.m4a, v02…;mp3、wav 及 m4a 均可):用手機語音備忘錄即可。如何向使用者請求錄音,以及在尚未錄好前該做什麼,請參考references/production.md§ 語音。然後執行python scripts/media.py voice <folder>:取得時長與有聲段落;所有時間點與剪輯點均源自於此。沒有語音(僅螢幕文字與音樂)?跳到步驟 4。 - 圖片與片段 — 使用者照片放在
img/,影片片段放在vid/。執行python scripts/media.py sheet-img <folder>與sheet-footage可在一張聯絡表上顯示所有素材:一定要看過再選擇。繪製背景、卡片與圖表則來自 pieces 或動畫引擎。 - 先用靜態圖編輯 — 在
reel.py中使用pieces.source(name, 'img/x.png')撰寫,然後執行python reel.py --preview。檢視review/preview.jpg。在正式渲染前調整節奏、構圖與圖層。這個步驟是影片成敗的關鍵,切勿急躁。 - 片段處理 —
media.py extract會將實際影片片段中所需的段落擷取到frames/<name>/中;media.py frames則轉換整個片段。檢查運動聯絡表 (media.py sheet-motion <folder>)。 - 音樂與效果 — 使用者自己的音樂軌放在
music/(須擁有使用權),或無音樂。引擎會從第一個起音處開始剪輯音樂,並在語音下方降低音量。效果皆已內建: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. 從真實錯誤中歸納的規則
- 檢視每一張聯絡表。
imgs.jpg、motion.jpg、preview.jpg、驗證聯絡表。未經檢視的渲染成果不得交付。 - Logo 標誌。 絕不信任檔案名稱。請直接開啟它。若檔案尺寸太小,請使用測量到的顏色,以文字重建文字標誌。
- 第三方品牌。 絕不加入非使用者擁有的標誌或識別(例如他們所銷售產品的製造商)。品牌可能因為出現在使用者自己的素材中而被包含,但絕不另行加入。
- 剪輯點來自語音,而非肉眼判斷:使用
caps.word_time(key, i)以及media.py voice產生的有聲段落。 - 短片段。 切勿將片段速度低於
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 的影片中複製位置數字。 - 格式。
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.m4a', 0.30) # 回傳該句結束的時間點
caps.line('v01', 'Sentence with *key* *words*, / next block.', 'vo/v01.m4a', 0.30) # *hl* · / 斷行 · 顯示|朗讀
t = caps.word_time('v01', 2) # 第 3 個單詞被朗讀的秒數 → 在此處剪輯
reel.shot(0.0, t, source('hero', 'img/hero.jpg', z=(1.0, 1.06), c=(.5, .45)))
reel.shot(t, 5.0, Clip('hero', speed=1.0, start=0.25, z=(1.14, 1.24))) # frames/hero/ 由 media.py extract 產生
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)) # Before/After
reel.shot(8.0, 11.0, pz.outro_save(B, 'img/hero.jpg', '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 的 canvas 上繪圖。素材是帶有 .frame(t_local, duration) 方法的物件,回傳與 canvas 相同尺寸(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(它會從 npm 下載引擎的套件一次;執行前請先告知使用者),再執行 node <skill>/animation/cli.mjs doctor。一個專案包含一個資料夾,內有 package.json、src/index.jsx(registerRoot + 每個影片一個 <Composition>)以及 public/ 存放其檔案。元件從 'invokard-studio' 匯入:useCurrentFrame、spring、interpolate、Sequence、Img + staticFile、OffthreadVideo,3D 從 'invokard-studio/three' 匯入,字型從 'invokard-studio/google-fonts/<Family>' 匯入——僅限十五種內建字型:Inter、Outfit、Figtree、Poppins、Montserrat、Space Grotesk、Barlow、Barlow Condensed、Oswald、Anton、Bebas Neue、Playfair Display、Fraunces、Shrikhand、Caveat。其他字型:使用者將字型檔放入 public/,並以 @font-face 宣告。
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 動畫):影格會在多個分頁中不按順序繪製。如同處理影片一樣,請檢視您渲染的每一張靜態圖與影格聯絡表。在影片中使用:
import animation as an # scripts/animation.py
an.render('anim/src/index.jsx', 'Title', rk.P('anim/title'), transparent=True) # 含透明度的 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/ 是一個完整的影片範例,同時使用了上述兩種方式,且無需外部素材。
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在動態牆的 4:5 中心裁切範圍內可讀 - 已交付原始檔案,不包含
frames/;未發布任何內容
7. 此建置不做的事
它不會以 AI 生成圖片、影片片段、語音、音樂或 3D 模型,也不會呼叫任何線上服務。當需求需要上述任一項時,請在計劃中明確說明:現在可以使用使用者自己的照片、影片與錄音來製作影片,搭配繪製動畫(標題、圖表、3D 產品、由形狀構成的插圖),或使用使用者從其他來源帶來的檔案。請不要推薦特定產品或服務。
參考文件
references/production.md— 使用者的語音、字幕、安全區域、音訊、品牌。references/footage.md— 從使用者片段製作影片:聯絡表、擷取、踩點網格、音樂拼接、轉場、片尾卡片。references/animation.md— 動畫引擎:專案、指令、API、內建字型、組合+動畫、疑難排解。references/api.md—reelkit.py、pieces.py與media.py的所有函數及其參數,以及每種格式的預設位置。references/troubleshooting.md— ffmpeg、字型、Windows 主控台、長時間渲染。