Communitygithub.com

stage3d-shorts

製作一個垂直的動畫短片(1080x1920,30 fps),採用「黑色舞台」3D 風格,從附有字詞時間軸的腳本到完成的 MP4。適用於任何此風格的新短片,無論主題為何。此風格位於一個套件中,影片無法更改;一個影片就是一個計劃檔案。

stage3d-shorts 是什麼?

這個技能(stage3d-shorts)是一個專門的 AI 代理技能,旨在從提供逐字時間軸的腳本,自動生成具有獨特「黑色舞台」3D 風格的垂直動畫短片(1080x1920,30 fps)。此風格包含黑暗舞台、鏡面地板、扁平白色藥丸形人物、螢光線條道具以及戲劇性聚光燈,並配有隨時間移動的動態攝影機和逐字字幕。此技能並非獨立工具,而是與使用者的本機「kit/」資料夾搭配運作,該資料夾包含所有視覺元素和渲染腳本。使用者提供腳本、語音和音樂檔案,AI 代理則負責撰寫「計劃」(一個 JavaScript 檔案,定義舞台上發生的事件、時機和攝影機移動),然後透過一系列腳本(包括程式和品質保證檢查)來建置、預覽和渲染最終影片。此流程強調嚴格的工作流程:所有更改必須在套件層級進行(不允許一次性修改),每個渲染都必須經過自動化 QA 測試(檢查畫面缺失、格式和攝影機規則),且須遵守特定的攝影機動作規則,例如僅使用三種移動類型(鉤鏡、重新構圖、慢速),以及僅在想法之間使用甩鏡。此技能已針對短片段(10 秒、5 秒)驗證,但尚未用於完整長度的影片,並明確列出了已知的限制(例如,缺少長列表、圖表、近拍鏡頭和淡入淡出效果)。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Pimboto/claude-skills/tree/HEAD/skills/stage3d-shorts

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

stage3d 短片

一個帶有鏡面地板的黑暗舞台。扁平白色藥丸形人物、以螢光線條繪製的道具、聚焦於人物的劇院聚光燈、一個在真實 3D 空間中移動的攝影機,以及一次一個字的逐字字幕。此風格是透過測量參考影片(私人學習資料:絕不複製其內容、名稱或腳本)逆向工程而得,並經過改良。

狀態:v0.1。 已在一個 9.7 秒的兩個站點片段(pricetag_demo)和一個 5 秒測試(test5)上驗證。尚未在完整長度的影片上驗證。在承諾製作場景之前,請先閱讀「套件尚未具備的功能」。

概念

  • 套件即風格。 kit/src/ 包含顏色、光暈、鏡頭、地板、燈光、攝影機曲線、字幕。影片永不編輯它。
  • 影片即計劃。 kit/plans/<name>/plan.js 說明舞台上發生什麼、每個事件發生的時間以及攝影機如何移動。它僅匯入 kit/src/api.js。建置程序會拒絕嘗試存取套件內部的計劃。
  • 數字決定,而非意見。 每次渲染都由 scripts/qa.py 測量。未通過的影片不予交付。

套件存放位置

此技能僅為操作說明。負責繪製影片的程式碼和參考檔案位於 Pimbo 電腦的資料夾中: C:\Users\Pimbo\work\anymation\stage3d\skill(包含 kit/、references/ 和此檔案的副本)。此技能中的所有路徑都相對於該資料夾。

  • 資料夾 anymation 必須連接到對話中。如果沒有,請要求 Pimbo 連接它:沒有套件就無法製作影片,且不應憑記憶重建此處的任何內容。
  • Pimbo 不會手動執行腳本。由你來執行。他提供主題或影片資料夾,查看靜態圖片,然後批准。
  • 影片的輸入來自他自己的流程:anymation/v2/v8/<video>/(script.json、用於字詞時間軸的 asr_<lang>.json、用於語音和音樂的 premix_<lang>.wav、events_<lang>.json)。
  • 如果你能在他的電腦上執行命令,請直接在該資料夾中工作。如果你只有雲端工作空間:將 stage3d/skill 複製進去(排除 node_modules、out 和 dist),在 kit/ 內執行 npm install,在那裡撰寫計劃並渲染靜態圖片(沒有顯示卡時約 2 秒一張),向他展示靜態圖片,然後將完成的 kit/plans/<name>/ 寫回他的資料夾。
  • 最終渲染應在他的電腦上進行:他的顯示卡速度約為雲端機器的 20 倍。如果你無法在那裡執行命令,請在 stage3d/skill 中留下一個 .cmd 檔案,內容為從 kit 執行 node scripts\make_video.cjs <name> --gpu --workers=4,請他雙擊該檔案並貼上其輸出。在宣稱影片完成之前,請先閱讀 QA 的輸出內容。

不可協商的規則

  1. 永遠不要為了讓某個影片能夠運作而編輯 kit/src/。如果缺少某個道具或鏡頭類型,請將其作為可重複使用的部件新增到套件中(請參閱 references/PLAN_GUIDE.md 的「新增道具」一節),並在之後重新檢查 pricetag_demo。
  2. 計劃中的每個影格編號都必須來自真實音訊(字詞時間軸),絕不能來自猜測。
  3. 每個攝影機移動都必須有一個可以用一句話說明理由的原因。將該句話作為註解寫在移動動作的上方。
  4. 在渲染片段之前,先查看靜態圖片。要看圖片本身,而不是看退出碼。
  5. 說明哪些是測量過的,哪些是假設的。如果你沒有檢查某件事,請說出來。
  6. 在輸出影片之前,必須有人聽過音訊:這些腳本是根據數字來設定音量的。

流程

在 kit/ 內部工作。首次在某台機器上執行:npm install(three、esbuild、playwright-core;它會使用已安裝的 Chrome 或 Edge,不會下載其他東西)。渲染需要 ffmpeg 在 PATH 中;QA 需要安裝了 numpy 和 opencv 的 Python(pip install numpy opencv-python);音訊腳本需要 scipy。

步驟內容指令或檔案
1腳本與語音,附有每個字的時間軸此技能外部;結果:words.json = [{ w, t0, t1, line }],單位為秒
1b在錄製語音當天,檢查腳本的每個事實網路搜尋;在計劃旁撰寫 SOURCES.md(範例:plans/no_trick/SOURCES.md)
2將腳本分解為站點:每個句子或一個想法plan.js 頂部的註解
3撰寫計劃:建構、動畫、攝影機kit/plans/<name>/plan.js;從 pricetag_demo 開始
4音訊:基礎混音加上事件效果kit/plans/<name>/make_audio.py -> audio.wav
5檢查並建置node scripts/build.cjs <name>
6關鍵影格的靜態圖片;修正構圖;重複node scripts/render.cjs <name> stills 0,17,62,88
7在瀏覽器中開啟 kit/dist/<name>/preview.html 觀看動態效果並聆聽聲音在瀏覽器中打開
8一次完成渲染、編碼、QAnode scripts/make_video.cjs <name> --gpu --workers=4
9閱讀 QA 的輸出內容;FAIL 表示需要修正並重複kit/out/<name>/logs/qa.log、qa.json

步驟 8 會為每個步驟列印一行。在有顯示卡的 PC 上,5 秒的影片大約需要 10 秒;沒有顯示卡(省略 --gpu)時,每個影格大約需要 2 秒,因此只渲染你必須渲染的內容。

撰寫計劃,簡要說明

完整指南和部件列表:references/PLAN_GUIDE.md。實作範例為 kit/plans/pricetag_demo/plan.js。

  • 舞台是一排間隔 14 公尺的站點。每個句子或一個想法對應一個站點。攝影機在一個鏡頭中停留在一個站點上,並在句子之間甩鏡到下一個站點。
  • build(stage) 創建事物並放置它們:stage.station(i).add(thing)。人物會獲得聚光燈:stage.station(i).spotlight(figure)。
  • animate(f, o) 設定所有事物在影格 f 時的位置。它必須是 f 的純函數:影格會以任意順序並行渲染。影格之間不保留狀態,不能有 Math.random,不能有時鐘。
  • 事物會在它們對應的字詞出現時出現:pop(thing, f, wordFrame)。一個重要的數字會在被討論的期間內運行。某個落地的東西會獲得地板環(pulse)、短暫的 flare 和一個音效。
  • 僅透過名稱指定顏色。金色 = 有價值的東西。紅色 = 價格、成本、危險。白色 = 人物和中立標籤。
  • 會改變的文字(例如計數器)需要 maxChars,以便其盒子不會重新調整大小。

攝影機,簡要說明

包含測量數據的完整規則:references/CAMERA_RULES.md。

  • 一個鏡頭有一個移動,有時有兩到三個。移動之間攝影機保持靜止(套件會加上一個緩慢的微動)。
  • 只有三種移動類型存在:hook(開場推近,從影格 0 開始)、reframe(20-28 個影格,在兩個句子之間,在新的東西出現前幾個影格著陸)、slow(在整個鏡頭中進行的推近或環繞)。
  • 當圖形動畫播放時,攝影機保持靜止。列表會獲得一個平移;更廣泛的主張會獲得一個拉遠;一個需要長時間說明的物體會獲得一個緩慢的環繞。
  • 3/4 視角(偏航角約 35-40 度)最能展現深度。當第二個物體需要空間時使用它。
  • 甩鏡僅在想法之間使用。每個甩鏡都需要在音訊中加入一個「咻」的聲音,該聲音大約從 3 個影格前開始。

品質關卡

如果發生以下情況,scripts/qa.py 會判定影片未通過:影格缺失或凍結;背景不是提升的黑色;鉤鏡或重新構圖不是前置載入的;攝影機在移動之間沒有保持靜止;甩鏡沒有移動或沒有變暗;MP4 不是 h264 / yuv420p / BT.709,影格數錯誤,或其音訊缺失或長度錯誤。

它不檢查品味、影格邊緣的裁切,或字幕是否正確。這些是在渲染之前,透過肉眼檢查靜態圖片來確認的:沒有重要內容被影格邊緣裁切掉,字幕區域(畫面高度的 75-83%)沒有明亮線條干擾,人物介於畫面高度的 25% 到 85% 之間(鏡頭會拉伸邊緣附近的物體)。

在對 kit/src/ 進行任何更改後:重建 pricetag_demo,渲染影格 0、17、88、150、174、236 的靜態圖片,並與 references/frames/ 進行比較。在軟體渲染中,它們必須完全匹配;在有顯示卡的情況下,差異約在 1 個色階以內。

套件既有的功能

包括人物(戴耳機的藥丸人)、標籤藥丸、附有標籤和大數值的卡片、代幣、可以打開的寶箱(金色,或用於一群寶箱的普通灰色)、帶有指針的圓形指南針、類似遊戲畫面的指南針條帶、輪廓框(螢幕、縮圖)、骰子、播放按鈕、計數記號、虛線引導線、圖片(作為光線繪製的黑白 SVG 或 PNG)、地板環、虛線地面線條、漂浮微粒、帶有地板光暈和陰影的劇院聚光燈、彩色地板光暈、光環、光線、火花、帶有動態模糊的甩鏡、字幕、一個音效庫(咻、滴、叮、砰、哐啷、閃爍、嘶嘶聲)以及一個混音器,可以將語音檔案和音樂檔案混入其中。

有兩個計劃可以參考:pricetag_demo(10 秒,兩個站點,已批准的風格)和 no_trick(47 秒,五個站點,包含語音、音樂和來源的完整短片)。starts_clean(62 秒,六個站點)直到最後一個金黃色回報之前都是白色的,符合 Pimbo 的腳本規則要求。avatar 不是一個影片:它為大頭照製作靜態圖片。

套件尚未具備的功能

  • 沿著一排事物(例如列表、長條圖和折線圖)的平移。
  • 一個站點中有多個聚光燈:尚未嘗試(微粒最多同時被兩個聚光燈照亮)。一個站點中的多個人物確實可以透過一個聚光燈和其他人物變暗的方式運作(no_trick,站點 2)。
  • 淡入淡出或切換:唯一的轉場是甩鏡。
  • 特寫:攝影機需要在其主體下方看到地板,並且在距離小於約 2 公尺時會失去對焦。更近的畫面是從更寬的畫面中裁切出來的(plans/avatar)。
  • 除了上述三種移動類型之外的任何移動,以及任何攝影機翻滾。
  • 語音、音樂和字詞時間軸:這些來自外部(Pimbo 的 v2/v8 流程產生)。

以上每一項都必須先在套件中建置,並在真實影片上嘗試,之後計劃才能使用它。

檔案

路徑說明
kit/src/風格。api.js 是計劃唯一匯入的檔案
kit/plans/<name>/一個影片:plan.js、words.json、make_audio.py、audio.wav
kit/scripts/build.cjs、render.cjs、encode.cjs、make_video.cjs、qa.py
kit/audio/sfx.py音效和混音器
references/STYLE_BIBLE.md風格的每個數值,標記為測量值、我們的值或猜測值
references/CAMERA_RULES.md攝影機如何編輯,附有測量數據
references/PLAN_GUIDE.md如何撰寫計劃;api.js 的每個函數;新增道具
references/KNOWN_ERRORS.md已經犯過的錯誤,以及現在如何防止它們
references/frames/pricetag_demo 的目標影格

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能