Reel — 故事編輯（全畫面動感）
Speaker 保持全螢幕。故事透過以下方式講述：創作者自己的片段穿插、在口語詞彙上彈出的貼紙/卡片/widget、一個反應吉祥物，以及深度時刻——巨大的文字或有品牌的背景出現在 speaker 身後（人物遮罩）。工作範例：examples/story/story_stoodi_inviteraw.py。
引數：$ARGUMENTS
預設值（只有當使用者特別要求時才更改）
首先讀取 reel.config.json（若無則回退到 reel.config.example.json）。
| 項目 | 預設值 |
|---|---|
| 字幕 | 無。 關鍵詞圖形可以；絕不顯示連續轉錄文字 |
| 音訊 | 使用片段本身的混音，不經修改——由 finish.py 重新混流。無音效，無背景音樂 |
| 片段 | 假設已經裁剪、調色、加入音樂→不要裁剪或調色。原始/未剪輯→先詢問 |
| B-roll | 來自設定的 broll_dir；描述在 work/_catalog/<folder>/NOTES.md 中 |
| 品牌 | 來自設定的 brand + palette。無吉祥物檔案→無吉祥物場景 |
| CTA | 評論關鍵詞以大字顯示在畫面上；追蹤卡片 = 僅 @<creator.handle> 文字，絕不使用人臉裁剪 |
| 語言 | 來自設定的 language（Whisper + 要使用的文字類別） |
輸入
片段名稱 + 主題來自引數。僅在一次訊息中詢問一次缺失的資訊：片段是否已裁剪/調色/加入音樂；評論關鍵詞；Whisper 可能聽錯的名稱或術語；他們想要包含或排除的片段。
管道
PY = .venv/Scripts/python.exe -X utf8（Windows）或 .venv/bin/python -X utf8（macOS/Linux）。長時間步驟在背景執行。
| # | 步驟 | 指令 / 動作 | 檢查 |
|---|---|---|---|
| 1 | 查看 | ffprobe 片段；聯絡表 ffmpeg -i raw/<take> -vf fps=1/5,scale=216:384,tile=9x2 -frames:v 1 work/<take>/sheet.jpg 並查看 | 頭頂上方空間、文字在畫面中是否鏡像？、是否已調色？ |
| 2 | 轉錄 | $PY tools/transcribe.py <take> --prompt "<名稱, 術語>" | 校對名稱；單詞間隔 > 3 秒→重新轉錄該視窗 |
| 3 | 臉部 | $PY tools/face_track.py <take> | 輸出 FACE = (x, y) 和頭頂位置 |
| 4 | B-roll | $PY tools/story_assets.py <take> catalog；讀取 NOTES.md；查看尚未描述的片段條目，並將它們的行新增到 NOTES.md | HDR / 鏡像 / VFR 標誌 |
| 5 | 節奏表 | 撰寫 work/<take>/beats.md：`time | words |
| 6 | 遮罩 | 如果有任何深度時刻：$PY tools/story_assets.py <take> matte（80 秒片段約 8 分鐘 CPU，背景執行，無平行 ffmpeg） | work/<take>/matte/fg.webm |
| 7 | 片段模組 | 複製 examples/story/story_stoodi_inviteraw.py → tools/story_<slug>.py（slug：片段名稱，非字母數字字元 → _）；設定 NAME、FACE、BROLL、TILES、MIRRORED、場景、SCENES（DUR 可選——會自動探測）。吉祥物名稱 = assets/mascot 中的檔案（小寫，空格 → -） | |
| 8 | 資產 | $PY tools/story_assets.py <take> all（吉祥物、標誌、B-roll 剪輯、磁磚） | |
| 9 | 建置 | $PY tools/story_build.py <take>；在 work/<take>/sc 中：npx hyperframes lint public → 0 個錯誤（nested_structure 警告是預期的）；npx hyperframes snapshot public -o ../snaps --no-end --describe false --at <every beat>；讀取聯絡表，修正，重新建置 | |
| 10 | 快速渲染 | $PY tools/finish.py <take> --seconds 12；讀取 work/<take>/sc/quick_sheet.jpg | 疊加層進入並離開；顏色不暗淡 |
| 11 | 完整渲染 | $PY tools/finish.py <take>（80 秒約 12 分鐘，背景執行）→ final/<take>/，驗證，qa/sheet.jpg | 逐幀讀取聯絡表 |
| 12 | 報告 | 路徑、長度、節奏、使用的片段、任何翻轉/色調映射的內容，驗證結果。如果學到了新東西，將其添加到這個技能中 |
節奏規則
- 每 2-4 秒必須有變化；絕不能有超過約 5 秒的純 speaker。
- 混合不同模式：speaker + 貼紙 · B-roll 穿插（約 25–30% 的運行時間）· 深度時刻（每個 Reel 4–6 次）· 全螢幕圖形且 speaker 作為 facecam 氣泡（最多 1–2 次）。
- 提示點 =
transcript.json中口語單詞的開始時間。每個元素在下一個節奏之前離開。 - 深度文字位於頭頂上方（來自步驟 3 的頭頂位置）：一次一個大字，前一個字飛出。堆疊的行最終會隱藏在頭部後面。
- 安全區域：在 y 150（Instagram 標題）上方或 y 1560（字幕）下方無文字；在 y 1100–1650 之間，保持 x < 960（喜歡/評論按鈕）。
- 作為事實顯示的數字必須來自片段。說明性標籤是可以的。
- 波斯語 / 阿拉伯語文字：
.fa類（RTL 作用域在元素內——絕不在<html>上使用dir="rtl"，它會渲染成黑色），letter-spacing: 0，數字透過fa()函式處理，大零使用拉丁文0（波斯零是一個點）。拉丁文文字：.en；巨大的顯示文字：.blk。
引擎契約——已修復的錯誤
- 場景 =
def scene(c: Comp)：c.clip(layer, id, start, end, html, track)、c.broll(name, a, b, mstart)、c.matte(n, a, b)、c.j(js...)。圖層：under（氣泡後方）、tiles、behind（片段與遮罩之間）、fw、broll、over、fx。 - Clip div 獲得 id
k-<id>；動畫化#<id>-i或內部 id——永遠不要動畫化.clip本身。 - 任何從畫面外滑入的元素在其 from 狀態都需要
autoAlpha:0，否則會提前露出。 - 元素的第一個 tween 會設定其初始狀態（
fromTo立即渲染）；後續的 tween：使用.to或immediateRender:false。 - 永遠不要使用
from:"random"的 stagger 或Math.random——在 Python 中使用random.Random(seed)來打亂 DOM 順序。 - 相同屬性、相同元素：一個 tween 必須在下一個開始之前結束（lint
overlapping_gsap_tweens）。 #cam的 scale/x/y/clipPath/borderRadius 驅動推進、氣泡和馬賽克效果。遮罩存在於#cam內部，因此深度時刻在任何相機縮放比例下都能保持對齊。- 包含可讀文字在畫面內的前置相機 B-roll → 加入到
MIRRORED。永遠不要翻轉主要片段。 - HLG/HDR 來源由
story_assets.py進行色調映射。如果finish.py停止在「HDR auto-promotion」，則表示某個來源未經此路徑處理。 hyperframes snapshot並非渲染的證明——步驟 10 才是這個用途。