brand-cut 是做什麼的？
公司 / 網址 / 儲存庫 -> 研究 -> 品牌套件 -> 產品時刻腳本 -> 分鏡 -> (VO) -> 原型建構 -> (混音) -> QA -> 渲染矩陣 -> 交付
在製作第一部影片前，請先閱讀 LEARNINGS.md。它記錄了所有導致影片被拒絕或渲染失敗的陷阱。
0. 規則（具約束力）
- 每個場景都必須是具體的產品時刻，並包含真實 UI。當 AI 出現時，螢幕上必須顯示真實的 AI 回答。不得使用抽象口號。
- 真實重於行銷。 從程式碼庫、文件和真實應用程式畫面建構；網站僅用於參考調性。每個畫面中的主張都必須能追溯至來源 (
qa/claims.py)。 - 使用精確的標誌，顏色取自來源，絕不近似。
- 不得有 AI 感。 禁止全大寫 /
text-transform: uppercase、表情符號、斜體襯線、紫色 AI 漸層、閃光、球體、粒子、鏡頭光暈、霓虹輪廓、假 UI、程式化手機或房屋。 - 閃光安全。 每約 8 秒最多一次全幀閃光，任 1 秒內不得超過 3 次閃光。
qa/flashcheck.py在最終檔案上必須通過。 - 音效。 每個螢幕上的 UI 動作都需有設計過的 SFX；音樂在 SFX 和 VO 下需降低音量；不得有節拍重擊。
- 格式 必須是安全區域內的原生版面，不得裁切。60 fps；1080 需以 4K 渲染再縮小。
- 未經使用者同意，不得發布、上傳或發表任何內容，也不得購買點數。
1. 佈局
SKILL.md, LEARNINGS.md 此檔案與陷阱清單
research/RESEARCH.md 階段 0：公司名稱 / 網址 / 程式碼庫 -> 品牌套件 + 真實主張 + 真實 UI 截圖
brand.schema.json 品牌套件結構定義
brands/demo/ "Tidewell"，一個虛構品牌；複製它以建立新品牌
archetypes/ CONTRACT.md + 30 個場景模板 (scene.html + README.md)
formats/ presets.json (尺寸、安全內縮、渲染預設、響度) + safe-*.png 疊加層
shared/ hf.js (執行時期：格式、挑選、種子隨機), phone.js (擬真手機), type.js, uikit/ (聊天、通知、
日曆、收據元件)
audio/ vo.py (ElevenLabs + 預算保護), mix.py, music.md, sfx/ (INDEX.md, INDEX.json, 檔案)
qa/ flashcheck.py, framecheck.py, safezone.py, claims.py, vo_diff.py, contact.py, run-all.sh
scripts/ new-film.sh, add-scene.py, set-format.py, set-brand.py, brand-css.py, render-matrix.sh,
save-ref.sh, index-refs.py, shazam.py, xcorr.py, beats.py, peaks.py
templates/ SPEC.md (影片合約), index.html, project/, structures/
reference/ PATTERNS.md (原型函式庫 + 法則), RESEARCH-digest.md, studies/ (18 個影片分解 + INDEX.md)
examples/ 完成範例影片及其品牌套件、SPEC 與靜態截圖
需求：Node 18+ (npx hyperframes)，Python 3.10+，ffmpeg，uv (uvx 用於在臨時環境中執行 QA 和音訊腳本)。選用：ELEVENLABS_API_KEY（用於語音旁白，若無則 audio/vo.py 會回退到開源 Kokoro TTS；詳見 audio/VOICE.md），音樂資料夾 ($MOTION_LIBRARY/music)。
可在任何具有 shell 的代理程式中運作。此文件提到「子代理」時，若您的代理程式沒有子代理，請依序執行步驟；「web 獲取」表示您代理程式的任何 fetch/browse 工具，或 curl。
2. 流程
- 研究 (
research/RESEARCH.md)。當您有儲存庫時使用程式碼庫模式（最準確），否則使用網站模式，兩者皆可時則同時使用。輸出：brands/<id>/brand.json、附有來源的truths、brands/<id>/assets/ui/中的真實 UI 截圖，以及 5-8 個產品時刻。 - 簡報。 目標觀眾、格式、長度、需有 VO 或純音樂或無聲、觀看者必須理解的唯一重點。
- 品牌套件。 複製
brands/demo/，填入色票（9 階 glowRamp）、含檔案的字型、標誌、UI 截圖、故事、真實主張、調性。針對brand.schema.json進行驗證。 - 建立骨架。
scripts/new-film.sh <brand> <dir> <format> [format...] [--palette id]-> 產生包含品牌區塊（字型、CSS 變數、window.BRAND）、film.json、SPEC.md、音訊存根的 index.html。隨時可更換主題：scripts/set-brand.py <dir> <brand> [palette]。切換格式：scripts/set-format.py <dir> <fmt>。 - 劇本。 SPEC.md 第 2 節：每個產品時刻一行（真實 UI、螢幕文字、VO 台詞、證明、嚴格的尺寸目標）。閱讀限制：<= 3 字/秒，每行 <= 42 個字元，最多 2 行。
- 先做 VO（有 VO 的影片）。
audio/vo/script.txt，每行一句 VO 台詞，然後執行python3 audio/vo.py say <dir> --voice <id> --take <name>。它會發出一個包含時間戳記的請求，根據對齊結果分割，移除填充詞並限制暫停長度。lines.json提供每句的持續時間。使用qa/vo_diff.py <dir> <take>檢查。預算保護會拒絕超過工作上限的任何調用。 - 根據 VO 和小節網格製作分鏡 (
scripts/beats.py <wav> <dur>)。SPEC.md 第 3 節：原型、入/出點、轉場（先排除閃光，PATTERNS 第 4 節）、SFX 事件。 - 音樂。 三種選項，對齊小節視窗（在揭露時綻放，在標誌處解決）；渲染選定的音樂。詳見
audio/music.md。 - 從原型建構。
python3 scripts/add-scene.py <dir> <archetype> <scene-id> <start> <dur> [--vars JSON]，然後進行客製化。使用子代理時：每個場景群組一個建構代理，各自只擁有自己的檔案；然後由獨立的評論代理檢視快照；最後進行修正。 - 混音。
audio/events.json（音樂、VO 台詞、來自audio/sfx/INDEX.md的 SFX 及其時間、音量降低）->python3 audio/mix.py <dir>->audio/mix.wav達到 -14 LUFS / -1 dBTP。 - QA。
npx hyperframes check零錯誤，進行草稿渲染，然後執行qa/run-all.sh <dir> <video> <fmt>（framecheck、flashcheck、safezone、claims、loudness、fps）。針對第 0 節檢查qa/contact.py <video> 10 <prefix>產生的比對表。 - 渲染矩陣。
scripts/render-matrix.sh <dir> [--4k 16x9]：針對每個格式，以 4K 捕捉並縮小至 1080，混合音訊，執行 QA 閘門。先檢查可用磁碟空間。 - 交付。 包含影片的資料夾、一個
index.html圖庫以及一份簡短的 REPORT.md（說明內容、使用的點數、音樂和語音替代方案、不足之處）。開啟資料夾供使用者查看。
3. 格式 (formats/presets.json)
| id | 畫布 | 安全內縮 (上/下/左/右) | 適用平台 |
|---|---|---|---|
| 16x9 | 1920x1080 | 108/108/192/192 | YouTube, LinkedIn, X, 網站 |
| 9x16 | 1080x1920 | 270/680/70/140 | Reels, TikTok, Shorts |
| 1x1 | 1080x1080 | 86/86/135/135 | IG/LinkedIn 動態 |
| 4x5 | 1080x1350 | 108/108/86/86 | IG/FB 動態 |
| banner | 1920x600 | 60/60/96/96 | README / 網站標頭條 (無聲循環) |
場景會讀取 window.BRAND.format 並根據格式分支版面 ([data-fmt="9x16"])。短邊始終為 1080 px，因此 px 尺寸可通用；在垂直格式中可放大主體。
4. 原型 (詳細內容在 reference/PATTERNS.md)
glow-field (A01，全片 WebGL 光效) | glass-slab (A02，顯示真實串流答案的 AI 面板) | glass-tile-click (A03) | word-blur-in (A04) | tracking-collapse (A05) | chip-marquee (A06) | status-stack (A07，參考實作) | wordmark-lockup (A08) | phone-tunnel (A09) | drum-wheel (A10) | card-carousel (A11) | network-lines (A12) | composer-send (A13) | card-burst (A14) | checklist-fix (A15) | orbit-chips (A16) | list-swap-toggle (A17) | object-launch (A18) | brutal-type (A19) | icon-ring (A20) | calendar-pick (A21) | product-hero (A22) | chat-thread (A23) | container-morph (A24) | notification-pile (A25) | docusign-sign (A26) | stripe-paid (A27) | logo-sting (A28) | branch-tree (A29) | counter-pill (A30) | logo-wheel (A31，循環「與…整合」輪播)。
影片結構 S1-S8（SaaS 解說、13 秒垂直、高級拋光清單、暗色電影風格、Figma 展示、漸層開場、手工製作片尾、證明板）位於 PATTERNS.md 第 5 節。合約：archetypes/CONTRACT.md（品牌無關的 CSS 變數、window.BRAND、每個實例的變數、格式原生、閃光安全、READ ME 中的 SFX 提示）。
5. 研究新的參考影片
scripts/save-ref.sh <url>使用 yt-dlp 下載影片並產生 2 fps 概覽 + 歌曲識別；scripts/index-refs.py為其建立索引。- 每 2 秒建立 10 fps 的片段，並在關鍵時刻建立原生 fps 片段；逐幀追蹤一個元素以命名其緩動；使用
scripts/beats.py產生小節網格；調色盤十六進位碼；逐幀亮度用於閃光輪廓。 - 撰寫
reference/studies/<id>.md：鏡頭列表、每個元素的建構方式、攝影機、緩動數值、轉場、字體、調色盤、深度、音效、文案結構、為何不像 AI、什麼會讓它像 AI、使用的原型。現有的 18 份研究即為範例。
6. 經過驗證的外觀
- 發光 (A01)： 一個 WebGL 著色器；標量場 -> 9 階色帶、噪波扭曲、抖色；uniform 來自一個由 GSAP 代理補間驅動的單調-Hermite 關鍵幀表。
- 玻璃：
backdrop-filter: blur(22px) saturate(1.5) brightness(1.15)，透過 mask-composite 產生漸變斜面、內部高光與陰影、接觸陰影、運動時一次光澤。 - 字體： 500 字重的無襯線字體，逐詞模糊漸入 14 -> 0 px，縮放 1.06 -> 1，power3.out，行重新置中，持續拉遠。
- 真實 UI： 從原始碼或截圖中，以 HTML/CSS 重現產品的元件（
shared/uikit/是起點）；HF.phone將畫面映射到擬真手機中。