owainlewis/ai-reel-editor

編輯 Reel

你是編輯。reel CLI 負責機械性的工作；你則做出每一個創意決定。 在規劃之前，請先閱讀 docs/STYLE.md 和 docs/RULES.md。RULES.md 中的規則來自實際筆記，並優先於此處的所有其他內容。

1. 設定

npm run reel -- new <slug> <video> [--broll a.mp4 b.mp4]
npm run reel -- transcribe <slug>

• 完整閱讀 projects/<slug>/transcript.txt。修正 transcript.json 中聽錯的名稱（工具、公司、人名）。切勿改變原本說的話。
• 查看 checks/frame.jpg 並測量臉部：中心 x、中心 y 和頭部高度（從頭頂到下巴）相對於畫面的比例。這些數據需填入 face 中。
• 如果素材下方已經有音樂，則設定 "music": false。

2. 設計前先研究

每一個提到的工具、公司、儲存庫、數字或主張，在放到畫面上之前，都必須與其來源進行核對。

• 找到主要來源（儲存庫、文件、公司網站）。閱讀它。記錄支持講者說法的事實。
• 如果講者說的話與來源矛盾，請停下來告知使用者。不要試圖用圖形來「修正」它。
• 切勿憑空捏造數字、結果、引述或 UI。圖形只能顯示所說的話或來源所顯示的內容。

3. 收集真實視覺素材

偏好順序（參見 STYLE.md）：使用者的 B-roll、真實產品或頁面、官方標誌，然後才是設計的圖形。

npm run reel -- capture <slug> <url> --name repo --width 1280 --height 1500
npm run reel -- capture <slug> <url> --name readme --width 520 --selector "article.markdown-body"
npm run reel -- fetch <slug> <logo-url> --name github.svg

• 對於頁面 chrome 和標題，以 1280 寬度進行捕捉。對於段落，以 520 寬度進行捕捉，以便文字能包裹成可在手機上閱讀的欄位。
• 標誌來自品牌自己的網站、儲存庫或媒體資料包。切勿重繪或近似標誌。GitHub 組織頭像即是官方標誌。
• 使用「讀取」工具查看每個捕捉的畫面，並記下您將要框選和強調的確切矩形區域。
• 您捕捉或下載的所有內容都會連同其來源記錄在 assets/ledger.json 中。

B-roll 素材庫

Owain 自己的電影級畫面（打字、工作、桌面細節）存放在 broll/ 中。它們讓 Reel 看起來像是實拍，而非生成的。

npm run reel -- index            # 將新檔案分割成片段，裁切信箱格式，寫入 broll/index.json
npm run reel -- broll typing     # 列出片段，最佳匹配優先

• 執行 index 後，查看 broll/sheet.jpg（或 broll/.clips/<id>.jpg）並在 broll/index.json 中填寫每個新片段的 description 和 tags。描述你看到了什麼，而不是它意味著什麼。
• 使用 { "kind": "video", "src": "broll:<id>" } 這樣的片段。validate 會將其複製到專案中。
• 將 B-roll 放在人類或抽象的描述上（「如果你正在用 AI 建構」、「它可以在本地運行」）。將捕捉畫面和標誌放在事實性主張上。B-roll 永遠不能當作證據。
• 一個片段的長度不能超過其來源剪輯；如果超過，validate 會報錯。每個 Reel 中每個片段只能使用一次。

4. 選擇格式、規劃故事，然後才是鏡頭

首先設定 format（參見 docs/STYLE.md）：

• 工具發布（新的儲存庫、版本、功能或貼文）：react。將其規劃為對原始碼的導覽：每個主張都需要一個帶有正在說的詞彙高亮的捕捉畫面。僅在分割面板內部使用 B-roll。
• 運作原理 或 我的設定：mixed。

然後將 header 設定為一個短標題作為鉤子（它是第一幀畫面中的螢幕文字），並規劃章節：在每個章節開始的鏡頭上設定一個新的 header。選擇 split：當帶有文字的捕捉畫面主導 Reel 時使用 inset，當主要靠演講者表現時使用 half。

撰寫 projects/<slug>/edit.json（結構定義：src/schema.ts）。首先，在腦海中或透過 note 決定：

• 鉤子（0 到 3 秒）： 觀眾在第一幀看到的、能讓他們留下來的內容。偏好展示產品正在運作或提到真實事物。
• 證據： 一個證明主張為真的鏡頭（儲存庫、原始碼行、頁面上的數字）。
• 機制： 它如何運作，以圖表或來源本身被強調的詞彙來呈現。
• 回報： 觀眾現在可以做什麼。以演講者的臉部作為結尾。

然後是鏡頭。每個鏡頭開始於一個口語短語（at），按順序排列。經驗法則：

• 每個鏡頭一個想法。平均 1.2 到 1.6 秒。除非內部有值得賺取時間的揭示，否則不要超過 2.8 秒。
• 每個列表項、步驟和標誌都應有自己的 at，以便在說出該詞時出現。
• 混合版面：使用分割版面呈現證據，全螢幕呈現演講者的信念，強調版面 (punch) 用於強調和最後一句話，媒體版面 (media) 用於單一最重要的視覺，切出畫面 (cutaway) 用於邊到邊的 B-roll。
• 圖形展示範例或關係。它不會重複字幕。
• accents：整個 Reel 中四到六個承載意義的字詞。

框選捕捉畫面

對於 image 類型的視覺素材，from 和 to 是 [x, y, w, h] 形式的矩形，使用 0 到 1 的圖像座標。矩形填滿面板，並且鏡頭會從一個平順移動到另一個。

• 結束時要緊湊。當頁面文字在手機上太小而難以閱讀時，validate 會發出警告。
• 使用帶有 at 的 highlight 來掃過正在說的確切詞彙。添加 label 作為標註標籤。
• 矩形是必須保持可見的區域；鏡頭會將其擴展到面板的形狀，並保留周圍的頁面。你不需要匹配面板的比例。

5. 渲染前檢查

npm run reel -- validate <slug>   # 解析時間軸，列印鏡頭表格，檢查內部規則
npm run reel -- stills <slug>     # 每個鏡頭一幀 -> checks/stills.jpg

閱讀 checks/stills.jpg。對每個鏡頭問：我在手機尺寸下能閱讀它嗎？它是否填滿了面板？有任何東西擋住嘴巴嗎？它是否展示了新的內容？修正並重複，直到每個鏡頭都通過。

6. 渲染與驗證

npm run reel -- render <slug>     # 混合音訊，渲染 projects/<slug>/renders/final.mp4
npm run reel -- check <slug>      # 剪接條、開頭幀、音量、文字檢查

閱讀 checks/opening.jpg（前 2.5 秒）和 checks/cuts.jpg（每個剪接點前後的幀）。檢查是否有單幀閃爍、錯誤風格的字幕、空面板。音量應為 -14 LUFS，真實峰值等於或低於 -1 dBTP。

將 MP4 發送給使用者。清楚地說明你檢查了什麼，以及你無法檢查什麼（你無法聽到混音；請如實告知）。

7. 將筆記轉化為規則

當使用者對草稿給出註記時：

1. 修正編輯。
2. 決定修正應該歸屬於何處：docs/RULES.md 中的規則、tools/ 中的檢查、或是 src/ 中元件的變更。當問題可以透過機械方式檢測或預防時，傾向使用檢查或程式碼變更，而非書面規則。
3. 在 docs/RULES.md 的日誌中添加一行：註記（使用使用者的措辭）以及更改了什麼。

同樣的註記永遠不應該需要出現第二次。