mohdkhatab/shorts-video-studio

Shorts Video Studio

產生一段 30-60 秒、1080x1920 的 MP4 + SRT + 腳本。所有內容皆以程序化方式產生（Python + OpenCV + PIL + ffmpeg），由基於提示的動畫引擎驅動，讓視覺效果精確對應到口說的每一個字。

此技能包含的檔案

• scripts/shorts_engine_template.py - 可運作的參考引擎（9 個場景、9 個背景、8 種轉場、音訊、語音同步）。請複製並編輯它，不要從頭重寫。
• scripts/tts_elevenlabs.py - 透過 REST API 生成語音旁白（需要 ELEVENLABS_API_KEY）。請先使用 --check 和 --list-voices。
• scripts/review_frames.py - 聯絡表 + QA 證據：時長、編碼、解析度、整合 LUFS、響度範圍、真實峰值。失敗時會以非零狀態碼退出。
• scripts/setup.sh - 建立 .venv、安裝依賴套件、檢查 ffmpeg 與字型。之後請執行 source .venv/bin/activate。
• assets/fonts/ - 15 個 OFL-1.1 字型檔案 / 12 個字型家族 + Noto Color Emoji（真實圖示）。包含授權檔案，索引在 assets/fonts/LICENSES.md。
• references/design-bible.md - 色板、字型、圖示詞彙、背景、轉場、特效、版面網格。設計場景前請先閱讀。
• references/script-and-voice.md - 腳本公式、Hinglish 規則、事實核查規則、語音與對齊細節。撰寫腳本前請先閱讀。

流程（請依序執行步驟）

1. 研究 - 如果主題是新聞/趨勢，請網路搜尋 3 個以上來源，收集附有日期和數字的事實（「截至 <日期>」）。切勿捏造數字。標記你無法驗證的主張，並軟化措辭（「report ke mutabik」）。
2. 腳本 - 120-140 字，長度約 45-50 秒，前 2.5 秒內要有鉤子，7-9 個簡短段落，最後是行動呼籲。詳見 script-and-voice.md。儲存為 script.txt（每個場景一個段落）。
3. 場景規劃 - 每個段落一個場景。針對每個場景決定：背景風格、色板、2 種字型、圖示（表情符號）、主體動畫、提示詞、下一個場景的轉場。套用下方的 VARIETY RULES。將計畫寫入 plan.md。
4. 語音 - 為整個腳本生成 一個 語音旁白錄音（使用 tts_elevenlabs.py 或 ElevenLabs MCP）。儲存為 voice.mp3。如果你無法下載音檔（受限於沙箱環境），請要求使用者上傳該檔案；同時以估計的時間長度進行建置。
5. 建置 - 將範本複製到 video.py，取代 SCENES 文字，撰寫 bgN/dN 函式，設定 HIT 和 TRANS。對於每個動畫的起始時間，使用提示詞查詢 C(scene_idx, "spokenword", occurrence, default_seconds)。
6. 測試渲染 - TEST=1 python video.py 會寫出 PNG 檔案（結束狀態、中間狀態以及每個轉場的一幀）。執行 review_frames.py 並檢查它們。修正 QA 關卡標記的所有問題。
7. 最終渲染 - VOICE=voice.mp3 python video.py。請以分離模式執行它（setsid nohup ... &）並輪詢日誌；前景呼叫可能會因工具超時而被終止。每 50 秒的影片在單一 CPU 上約需 1.5-3 分鐘。混音會自動標準化響度至 LUFS（預設 -16）。
8. QA 關卡（如下）針對最終的 mp4 執行，然後交付 video.mp4、captions.srt、script.txt、plan.md、qa_report.md。

VARIETY RULES（這是讓影片看起來像人製作的關鍵，而非 AI 製作）

違反任何一項都將導致 QA 關卡判定為 FAIL。

• 每個場景都有其自己的背景技術和色板（射線、合成波網格、半色調旭日、程式碼雨、漸層+污點、藍圖網格、警告條紋、雷達環、五彩紙屑...）。相鄰場景絕不能相同。絕不能使用單一全域顏色。
• 整部影片使用 >= 7 種不同的字型，混合不同類別：壓縮衝擊體、厚重顯示體、寬版顯示體、怪誕體、襯線體、斜體襯線體、等寬體、像素體、手寫體。一個場景內最多使用 2-3 種字型。
• >= 5 種不同的文字處理方式：漸層填色、粗外框+硬偏移陰影、發光、逐字母彈跳、打字機效果、貼紙/藥丸標籤、旋轉印章、手寫傾斜。
• 真實圖示，而非幾何形狀：使用彩色表情符號（Noto Color Emoji）作為圖示，並加入動畫（彈出帶 overshoot、旋轉進入、飄浮、繞軌、搖擺）。絕對不能有純文字場景。絕對不能使用品牌標誌（Adobe、GitHub octocat 等）；請使用通用圖示。
• 8 種以上不同的轉場，每個場景變換使用一種：故障、橫搖模糊、縮放穿越、虹膜+環、百葉窗擦拭、閃爍+震動、像素化、向上推擠。絕不能連續使用相同轉場。
• 衝擊時刻需結合多種效果：火花爆發+衝擊波環+攝影機震動+RGB 分離+轟隆音效。
• 標題：每次 2-3 個單字，大而粗體並帶有粗外框，當前單字以場景顏色突出顯示，每個區塊加入輕微的彈跳縮放效果。
• 所有元素皆有動畫：沒有任何東西是沒有動畫就出現的，也沒有任何東西會完全靜止不動（閒置搖擺/漂浮/慢速縮放 0 -> 3.5%）。

版面與安全區域（720x1280 工作畫布，放大至 1080x1920）

• 上方 0-130 px：保持淨空（平台 UI）。標籤晶片僅可位於 y~62。
• 內容區域 y 150-830。標題區域中心 y = 950（H-330）。下方 250 px：淨空（平台 UI）。
• 寬度預算 640 px。任何可能溢出的行請使用 TXF(text, size, font, maxw)。估計寬度 = 字元數 x 0.55-0.75 x 大小，視字型而定（寬版顯示字型約為 0.75）。
• 計數器：固定字型大小，計數時絕不自動縮小（避免抖動）。

語音 + 同步（摘要；詳情請見參考文件）

• 一次錄製，然後對齊：apply_voice_peaks 會偵測音節能量峰值，並以 DP 匹配方式對應到腳本的音節（穩定度約在 0.2 秒內）。ALIGN=pauses 是針對語速較慢、停頓明顯的語音的備用方案。
• 提示詞使用第一個轉為小寫、去除標點符號後的字串開頭與記號相符的單字（數字：精確比對）。重複的單字請使用 occurrence。
• 場景開始 = 場景的第一個單字 - 0.45 秒。總時長跟隨語音（加上 1.2 秒的結尾）。
• 音樂為合成產生（襯墊 + 大鼓 + 鈸 + 貝斯 + 琶音），在語音下閃避約 55%；語音經過高通濾波 + 壓縮 + loudnorm（-15 LUFS）。每次轉場有呼嘯聲，衝擊時刻有轟隆聲，打字機音效，計數器有叮咚聲，行動呼籲有啵聲。

QA 關卡（裁判/QA 代理需通過所有檢查才能交付）

0. python scripts/review_frames.py out/video.mp4 out/contact.png 12 必須輸出 PASS（否則會以非零狀態碼退出）。響度與峰值由此工具提供，而非來自 volumedetect。
1. 時長 30-60 秒，解析度 1080x1920，編碼 h264+aac，整合響度約 -18 至 -13 LUFS，真實峰值 < -1 dBTP（無削波）。
2. 聯絡表需包含 >= 9 幀 + 每個轉場的一幀，並檢查：沒有文字被裁剪/溢出、沒有重疊元素、頂部 130 px 或底部 250 px 內無內容（標籤/標題除外）、標題在每個背景上都清晰可讀。
3. 滿足多樣性規則（在 plan.md 中列出實際使用的字型、色板、背景和轉場）。
4. 事實：腳本中的每個數字/日期/名稱皆可追溯到 plan.md 中註明的來源；未經驗證的主張已軟化措辭；除非有來源佐證，否則不使用「copy」/「stole」等措辭；相關時說明 alpha/限制。
5. 同步抽查：選取 5 個提示詞（鉤子詞、一個數字、一個名稱、一個轉場、行動呼籲），確認視覺效果在口說單字後的 0.25 秒內開始（將 SRT/SW 時間與畫格時間戳記進行比對）。 如果任何檢查失敗：修正、重新渲染、重新執行關卡。誠實回報已知的剩餘問題。

已遇過的陷阱（請避免）

• 在現代 Debian/Ubuntu 上將 pip install 安裝到系統 Python 會失敗（externally-managed-environment，PEP 668）。請使用 scripts/setup.sh（建立 .venv）和 source .venv/bin/activate；不要使用 --break-system-packages。
• 將 ffmpeg volumedetect 的 mean_volume（未加權的 dBFS）與 LUFS 目標進行比較是無意義的，並且曾導致早期建置無法通過其自身的關卡。請務必使用 ebur128 進行測量（review_frames.py 已採用此方法）。
• 對 PIL 影像或非連續裁剪區域使用 Image.fromarray 會導致 TypeError: expected string or buffer。請將精靈圖保持為連續的 numpy 陣列；rcard() 返回的是 PIL 影像，而非陣列。
• 將空陣列切片傳入 cv2.add 會導致斷言錯誤；在切片頻帶前請確保 b > a。
• 未使用 setsid nohup 啟動的背景程序會在工具呼叫返回時終止。
• 沙箱環境下的音訊生成（MCP）無法由沙箱下載：請要求使用者上傳 mp3/wav 檔案。
• 基於停頓的同步在快速的 AI 語音上會失敗（在 -35 dB 下僅找到 4 個停頓）；基於峰值的對齊是預設方法，原因在此。
• 重疊的提示詞視窗：如果兩個元素共享一個口說單字，請將第二個元素偏移 0.2-0.4 秒。
• 帶有變異選取器的表情符號（例如盾牌、警告）在啟用 embedded_color=True 時可正常渲染；縮小時使用 INTER_AREA 內插法，放大時使用 INTER_CUBIC 內插法。
• 缺少的字型會靜默地回退到 DejaVu/Liberation，並帶有一行 [warn] 訊息 - 在責怪版面配置之前，請先檢查渲染日誌中是否有 [warn]。