EssouliAnas/blender-3d-short

逼真 3D 短片（Blender + Python）

每一幀都是 Claude 以 Python 構建的 Blender 場景的真實渲染。不使用 AI 影像或影片模型。 最終輸出：1080x1920，30 fps，H.264，碼率上限 30 Mbps。路徑：<skill> = 此資料夾。各集存放於 <project>/blender-shorts/<slug>/，下載的素材存放於 <project>/blender-shorts/assets/，頻道偏好存放在 <project>/blender-shorts/brand.json。使用 python <skill>/scripts/<name>.py 執行腳本。

請先閱讀：references/style.md（規則）與 references/traps.md（在發明任何修復方法之前）。

設定（每台電腦只需一次）

• Blender 5.x（會自動在 Program Files 下尋找；否則請設定 BLENDER=<blender.exe 的路徑>）。
• python -m pip install numpy opencv-python-headless pillow；ffmpeg 需在 PATH 中。
• 驗證流程是否正常運作：將 examples/test-cell/ 複製到 blender-shorts/test-cell/，然後依序執行 build、still、frames、finish。在 RTX 3080 筆電上，EEVEE 快速渲染 90 幀 1080x1920 約需 2 分鐘。

步驟 0：啟動問題（務必在開始任何工作前詢問）

使用 AskUserQuestion 工具提問，分為兩輪，每輪最多四個問題，然後第三輪根據語音答案提問。如果 blender-shorts/brand.json 已存在，先問一個問題：「與上次相同的設定？」（一行顯示設定內容），選項為「是」/「變更部分」。若回答「是」，則跳至第三輪的主題相關部分。 推薦選項優先。將每個答案儲存至 brand.json（頻道層級）以及該集的 episode.json。

第一輪：主題與語音方式

1. 主題：「為我建議 3 個」/「我有一個主題」（他們在「其他」中輸入）。建議：與身體或事物運作原理相關的問題，且適合用圖片呈現；需在 YouTube 上查核視角是否原創。
2. 語音：
   • ElevenLabs 語音（推薦）：使用庫存語音，根據腳本生成，附帶精確的字詞時間戳記。
   • 複製我的聲音（ElevenLabs）：他們上傳 1-3 分鐘的乾淨語音一次；之後每集都以他們的聲音說話。僅限他們自己的聲音，或已取得書面同意之人的聲音。
   • 我自己錄製：他們錄製腳本；Claude 清理音訊、找出字詞時間戳記，並據此建構畫面。
   • 無語音，僅字幕：腳本以穩定的 2.8 字/秒計時，字幕燒錄在影片中，並提供 captions.srt 讓他們稍後在自己的編輯器中以該精確時間點錄製或加入語音。
3. 片長：30 秒（首次製作建議）/ 45 秒 / 60 秒。以 2.8 字/秒計算，約為 ~80 / 120 / 165 字。
4. 參考影片：「不用，使用內建風格規則」（推薦）/「要，我會提供檔案或連結」（使用 measure.py 測量，僅供私下研究）。

第二輪：外觀

1. 外觀：工作室背景（推薦：單一標誌性顏色當背景，該類型常見的外觀）/ 真實世界照片背景板（體育場、街道、天空在 3D 物體後方）/ 混合（背景搭配真實地點用於「在哪裡」的場景）。
2. 背景顏色（若不使用背景則跳過）：桃色 #F2D7C9（目前我們的顏色）/ 薄荷色 #CFE8DF / 深海軍藍 #1F2A44 / 自訂（十六進位）。絕不使用參考頻道的顏色。
3. 主要角色：「是否有主要角色？」（references/characters.md）
   • 我會提供已綁定的角色：他們的 .blend / .fbx / .glb 檔案（來自 Mixamo、Character Creator 或商店）。
   • 幫我製作一個（若他們沒有，建議此選項）：在 Blender 中使用 MPFB 製作，無需帳號，衣服上印有我們的標誌。
   • 下載免費的已綁定角色：Claude 提議 2-3 個候選（來源、授權、外觀）；在需要帳號的網站（Mixamo、Renderpeople、Sketchfab）上，由使用者下載並提供路徑。
   • 無角色：僅有物件、身體部位與地點。 一旦主要角色存在（assets/host/host.blend），此問題變為「再次使用 <名稱>？」。
4. 渲染引擎：
   • 自動（推薦）：多數場景使用 EEVEE 快速渲染，僅對皮膚特寫、雲、玻璃或毛髮等無法通過評判的鏡頭使用 Cycles 快速渲染。
   • 僅 EEVEE 快速：最快，約 1 秒/幀。
   • 僅 Cycles 快速：約慢 2 倍，光線更柔和自然。
   • 高品質：使用 high 預設，比快速模式約慢 2-3 倍。

第三輪：取決於語音答案

• ElevenLabs 或複製：關鍵步驟。 檢查專案或上層目錄的 .env 檔案中是否有 ELEVENLABS_API_KEY=（絕不印出金鑰）。若存在，則說「找到您的 ElevenLabs 金鑰」且不詢問。若無，則詢問： 「加入您的金鑰：在此貼上，我會將其儲存至 .env，或自行將 ELEVENLABS_API_KEY=... 這行加入 .env（避免留在對話中）」。將貼上的金鑰僅儲存至 <project>/.env，絕不回顯、絕不放入任何其他檔案、提交或日誌。
• ElevenLabs：語音：冷靜旁白（sound.py 中的預設 ID）/「從我的 ElevenLabs 庫中挑選」（使用 GET /v1/voices 列出，僅顯示名稱）/ 語音 ID（他們輸入）。語音模型：eleven_multilingual_v2（推薦：穩定，字詞時間點最佳）/ eleven_v3（更具表現力，但較不可預測）。
• 複製：要求提供聲音樣本檔案的路徑，然後執行 sound.py <ep> clone <files> --name "<他們的名字> 的聲音"；語音 ID 會被儲存，並在之後的每集重複使用。
• 自錄：告知他們等待腳本批准，然後一次性錄製，手機距離一臂遠，在安靜的房間中，並提供檔案路徑。（按照批准的腳本錄音才能保持畫面與語音同步。）
• 主要角色，根據第二輪的回答：
  • 提供：要求提供檔案路徑（以及紋理資料夾（若分開））。
  • 製作一個：詢問年齡範圍、體型、頭髮與服裝風格（簡單詞語）；然後要求安裝 MPFB。
  • 下載：顯示 2-3 個候選（名稱、外觀、授權、是否需要帳號），讓他們選擇。
• 每種語音選項：字幕是否燒錄？ 是 / 否（無語音選項一定會有字幕）。
• 每個選項：音樂：無，僅限效果音與環境音（首次製作建議）/ 我自己的音樂軌道（檔案路徑，他們需確認擁有版權）/ YouTube 音訊庫的音樂軌道（他們下載並提供路徑）。

請勿詢問其他事項；以下所有內容都有預設值。「特定模型」問題：此流程中沒有任何 AI 影像或影片模型。類似模型的功能選擇是渲染引擎（第二輪）、ElevenLabs 語音模型（第三輪），以及執行此技能的 Claude 模型：使用高努力模式的 Opus 效果最佳。

引擎預設（使用者選擇的設定，請保留）

• EEVEE 快速（預設，b3d.EEVEE_PRESETS['fast']）：16 個樣本，半解析度光線追蹤與全局照明，1 條陰影射線。在 3080 上 1080p 解析度下約 0.9-1.2 秒/幀，與 high 預設的相似度為 99-99.9%。
• Cycles 快速（b3d.CYCLES_PRESETS['fast']）：32 個樣本，1 秒時間限制，OptiX 降噪器，2-3 次反射，快速全局照明近似，持久資料。約 1.7 秒/幀。若降噪器在特寫上造成模糊，則將該鏡頭的時間限制設為 2 秒。
• 渲染時使用 --quality draft | fast | high，無需重新建構。每個場景的引擎設定：使用 setup_render(engine=...)，或使用 B3D_ENGINE=CYCLES python render.py <ep> build 進行 A/B 測試（無需編輯）。只要背景與色調匹配，在同一個短片中混合使用引擎是可以的（從各自的 .blend 檔案渲染每個鏡頭的幀範圍）。

流程（每步驟後儲存；向使用者展示靜態圖片，而非大量文字）

1. 主題與事實。 計算每個數字，並將其與來源一同寫入 episode.json 的 science 欄位中。有爭議的著名數字使用「科學家估計」。與大頻道相同的主題是可以的，但不要使用他們的文字。
2. 測量參考（僅當第一輪回答「是」時）：measure.py <資料夾> --out <集>/reference.json。否則使用 style.md 中的預設值。
3. 腳本存放在 episode.json（examples/episode.template.json）：使用第二人稱，約 2.8 字/秒，選擇的長度，符合 style.md 中的節奏結構。顯示腳本並等待確認。確認後，繼續執行「直接做」直到產生靜態圖片。
4. 語音與時間點，根據第一輪的回答：
   • ElevenLabs / 複製：sound.py <ep> voice -> audio/voice.wav、words.json、captions.srt。
   • 自錄：等待他們的檔案，然後執行 sound.py <ep> own <檔案>（字詞時間點：若已安裝 faster-whisper 則使用之，否則若有 ElevenLabs 金鑰則使用其語音轉文字，否則根據靜音處估算；若估算不準確，則建議 pip install faster-whisper）。
   • 無語音：sound.py <ep> captions -> 以 "wps"（2.8）生成 words.json + captions.srt。 然後撰寫 shots.md：每個節拍，幀範圍（來自字詞時間點）、鏡頭運動（推近 / 保持並緩慢移動 / 拉遠 / 飛越）、以及在每個保持期間持續移動的物件。每約 7 個轉場最多一個硬切。
5. 先進行 9 秒測試。 在整個短片之前，先對一個節拍執行完整流程：使用 b3d 輔助函式執行 scene.py。渲染、完成、執行 measure.py，若有參考則執行 compare.py reference.json ours.json。差異列表就是待辦事項清單。 修正相機，直到抖動與橫向漂移符合（單軸，緩動關鍵幀）。
6. 世界與角色。 先處理角色，依 references/characters.md 中的路徑，始終透過 b3d.import_character(path, height=1.75) 匯入：它會將角色縮放到真實身高並將腳放在地面上，移除散落的攝影機與燈光，將有權重的部分綁定到骨架，並列印報告（骨架類型、未跟隨骨架的部分、面部形狀 x/52、缺失紋理）。修復報告中的每一項，然後生成一張旋轉展示的靜態圖片，並儲存 assets/host/host.blend。世界則來自 references/assets.md（列出下載項目、來源 + 授權 + 大小，詢問一次）。規則：若有真實的版本，就下載它，絕不建模。
7. 靜態圖片與評審。 對每個節拍執行 render.py <ep> still <幀數...> --pct 50。然後使用靜態圖片與 references/realism.md 生成一個獨立的代理（Agent 工具）；它會評分（滿分 10 分）並指出三個最明顯的破綻。修正、重新渲染、重新評審。僅在分數達到 8.5 以上時才渲染。 向使用者展示靜態圖片與分數。若引擎為「自動」，則在此處將未通過 EEVEE 捷徑測試的鏡頭切換為 Cycles 快速。
8. 渲染。 在使用者的終端機面板（run_in_terminal）中執行 render.py <ep> frames，以便他們觀看即時進度條（已完成幀數、秒/幀、預計完成時間）；讀取 <ep>/progress.json 以回答「目前進度？」。可恢復中斷的渲染。接著執行 render.py <ep> times；若速度太慢，則針對最慢的幀逐步套用 references/render-speed.md 中的方法。
9. 音效。 在 episode.json 中設定 beds（每個世界的環境音）與 sfx（每個音效對應其字詞，例如「骨骼敲擊」對應「bones」），然後執行 sound.py <ep> sfx（需要金鑰；若無金鑰，則跳過效果或使用使用者在 audio/sfx/<name>.mp3 中提供的檔案）以及 sound.py <ep> mix。混合規則：音樂 +3 dB，效果音量減半，語音保持不變。
10. 完成。 執行 finish.py <ep> --audio <ep>/audio/mix.wav [--captions] -> out/<slug>-final.mp4。以手機螢幕大小觀看。無語音的集數：同時提供 captions.srt，並告知語音需在那些時間點加入。
11. 報告：最終檔案路徑、評審最後一次評分、渲染分鐘數、ElevenLabs 點數（costs.json）、以及用於影片說明的鳴謝文字（assets.md 中的授權資訊）。絕不聲稱參考頻道使用了任何工具。

腳本

腳本	執行環境	功能
b3d.py	Blender	渲染設定與預設（EEVEE/Cycles、GPU、外觀）、背景 + HDRI、陰影捕捉器（Cycles 真實、EEVEE 偽造）、燈光、單軸緩動推近攝影機、材質、import_character（任何已綁定的 .blend/.fbx/.glb，會縮放、綁定、回報）、parent_to_bone、形狀鍵、合成器、碼表
render.py	shell	build、still、frames（即時進度條、progress.json、可恢復中斷）、times；--quality
sound.py	shell	voice（ElevenLabs）、clone、own（使用者錄音）、captions（無語音）、sfx、mix；每種語音模式都會寫入 captions.srt
finish.py	shell	幀序列 + 混音 -> 1080x1920 mp4、真實攝影機圖層、--captions 燒錄字幕
measure.py / compare.py	shell	任何影片的逐幀指標；參考 vs 我們的影片，附帶待辦事項清單

scene.py 以 blender -b --factory-startup --python scene.py -- <skill>/scripts <ep>/scene.blend 方式呼叫；從 examples/test-cell/scene.py 開始（在燈光之後呼叫 shadow_catcher）。