Seagey/edit-reel

編輯 Reel

一切都在用戶自己的 Mac 上執行。無需付費服務。執行實際工作的單一腳本是 存放庫根目錄的 scripts/edit.sh，它會呼叫與此檔案同目錄的 scripts/edit_reel.py。

用戶不具備技術背景。請使用淺顯的澳洲英文、簡短句子，避免專業術語。在執行前先告知你即將要做的事，然後說明結果。絕不要使用長破折號或短破折號。

目錄

• 快速路徑
• 取得影片
• 一次編輯的內容
• 用戶可要求更改的設定
• 交給用戶前的檢查
• 向用戶回報結果
• 可能發生的問題
• 嚴格規則

快速路徑

1. 檢查設定是否完成：scripts/setup.sh --check。如果顯示 NOT READY，請遵循 CLAUDE.md（入門指南），不要自行嘗試安裝。
2. 取得影片（見下方），然後執行：
   • 單一命名檔案：scripts/edit.sh "<影片路徑>"
   • Inbox 資料夾中最新的 N 個：scripts/edit.sh --latest 3
3. 執行下方檢查，查看圖片，閱讀字幕，然後回報。

一段 30 到 60 秒的片段在 Apple 晶片 Mac 上約需一到兩分鐘，較舊的 Mac 則需更久。

取得影片

依此順序嘗試，使用第一個成功的方法：

1. 用戶命名或拖入的檔案。 在原地使用它。絕不移動或刪除用戶的原始檔案。
2. Inbox 資料夾。 用戶透過 AirDrop 或拖入 Inbox/（在存放庫資料夾內）的任何內容。
3. iCloud Photos。 僅當 iCloud 已設定時（docs/ICLOUD.md）。用戶的 Apple ID 電子郵件位在 config.json 的 icloud_apple_id 下。執行 scripts/icloud-fetch.sh <apple id> 30。
   • 成功時會顯示 ICLOUD_FETCH_OK。最新的影片會放入 Inbox/。
   • 若登入已過期（約持續兩個月）或從未設定，則會顯示 ICLOUD_FETCH_FAILED。請勿自行嘗試修復：告知用戶，並引導他們依照 docs/ICLOUD.md 的「重新登入」步驟操作。用戶需在他們自己的 Terminal 中輸入密碼和 6 位數驗證碼，絕不能輸入到對話中。
   • 「最新」指的是最近拍攝的。剛拍攝的影片可能需要幾分鐘才會出現在 iCloud 中，所以如果用戶指的影片找不到，請告知用戶，並提議一分鐘後再試。
   • 在編輯前，列出最新影片及其長度（使用 ffprobe 查看持續時間），如果有任何疑問，請確認用戶指的是哪一個。
4. 無效。 提供備用方案：請用戶透過 AirDrop 將影片傳送到 Mac，或拖入 Inbox 資料夾。

一次編輯的內容

依序執行：

1. 以音訊為基礎進行裁切。 根據音訊音量找出語音真正開始和結束的位置，而不是根據字幕時間（片段開頭的語音轉文字時間可能落在靜音中，掩蓋了無聲片段）。修剪開頭和結尾的靜音，並縮短過長的停頓。裁切點選在附近最安靜的時刻，每個接合處有 15 毫秒的淡入淡出，因此不會切到任何字詞。句子保持完整；只移除無聲的片段。
2. 鏡像檢查。 前鏡頭片段通常會鏡像。使用 OCR 讀取畫面中的任何文字（標誌、螢幕、衣服），比較正常與翻轉後的字詞，僅在翻轉後能正確讀出真實文字時才翻轉影片。絕不靠目視判斷。如果沒有可讀文字，則保留影片原樣，並在報告中說明。
3. 裁切為 9:16 並縮放至 1080x1920（橫向片段裁切中間部分）。
4. 調色。 測量數個影格，套用小幅的曝光、對比和飽和度校正，並設定上限以避免過度處理，同時產出前後對照圖。HDR iPhone 片段會先對應到標準色彩。
5. 錄音室音質。 降噪、語音等化器、去齒音、壓縮器、限制器，然後將音量調整至 -14 LUFS。這些參數經過測量調整。由聽覺決定：如果聽起來刺耳、單薄或過度處理，請將 audio.strength 設為 light。
6. 字幕。 轉錄處理後的音訊，然後使用 Pillow 繪製字幕。放在手機安全區域內（x 90 到 960，y 250 到 1520，以 1080x1920 影格為準），這樣按鈕和應用程式本身的文字才不會遮蓋字幕。正在朗讀的字詞會變色。外框保持深色。字詞後方沒有顏色方塊，因為它們在人臉上會變得模糊。
7. 輸出。 輸出至 Edited/<名稱>-edited.mp4，並在 Edited/checks/<名稱>/ 中輸出：contact-sheet.jpg、colour-before-after.jpg、caption-frame.png、captions-words.txt、report.json。

用戶可要求更改的設定

所有設定都在存放庫根目錄的 config.json 中（由 config.default.json 建立，此檔案絕不修改）。用戶不會觸碰該檔案。他們用白話文提出要求，你負責修改設定、重新執行編輯，並向他們展示結果。完整的字詞與設定對照表：docs/STYLE.md。

範例：

• 「把字幕變成黃色」設定 captions.highlight_color（正在朗讀的字詞）或 captions.color（所有字詞）。如果不確定，詢問是哪一種。
• 「字幕放大一點」將 captions.size 提高約 12（預設值 78）。確保結果仍在安全區域內：腳本會報告 inside_safe_zone。
• 「把字幕往上移」將 captions.position 設為 middle 或 upper。
• 「一次顯示一個字」將 captions.style 設為 word。「用一行顯示」則設回 line。
• 「不要字幕」將 captions.enabled 設為 false。
• 「顏色淡一點」將 grade.strength 降低 0.2。「不要調色」將 grade.enabled 設為 false。
• 「剪緊湊一點」將 cuts.tightness 設為 tight。「留多一點呼吸空間」：設為 gentle。
• 「聲音太加工了」：將 audio.strength 設為 light。
• 「臉靠近一點」：framing.zoom 設為 1.15（最大合理值 1.4）。
• 字幕中的名字拼錯：將其加入 vocabulary（幫助語音辨識正確拼寫），如果仍然錯誤，則加入 replacements 作為 {"heard": "正確拼寫"}。

更改設定後，對同一部影片重新執行編輯，並展示新結果。使用 Edited/ 中的檔案；重新編輯會取代同名舊編輯。

交給用戶前的檢查

腳本會輸出摘要並寫入 report.json。你仍需親自檢查。

1. 數據。 loudness_ok、start_ok、end_ok 都應為 true。開頭靜音應 ≤ 0.45 秒，結尾靜音應 ≤ 0.75 秒。如果不是，請告知用戶並使用 --tightness tight 重新執行。
2. 查看圖片 使用「讀取」工具：contact-sheet.jpg（臉部是否在畫面中、畫面是否自然、字幕是否在螢幕內），colour-before-after.jpg（左側為原始畫面，右側為調色後：膚色自然，不偏橘或灰，亮部未過曝，暗部未全黑），以及 caption-frame.png（以完整尺寸閱讀每個字詞，確認每個字在背景上是否清晰可讀）。
3. 閱讀字幕。 開啟 captions-words.txt。語音轉文字可能會誤認姓名和地名（例如品牌名稱）。使用 vocabulary 和 replacements 修正，然後重新執行。檢查報告中的 caption_vs_sound_match：低於 0.9 表示有問題，請調查。
4. 鏡像。 查看 report.json 中的 mirror。如果 decision 為 unknown 且畫面中有文字（標誌、螢幕），請查看一個影格，確認文字是否正確可讀。如果是反的，將 framing.mirror_fix 設為 always 並重新執行。
5. 以音訊判斷無聲片段。 腳本會對最終混音執行 silencedetect。不要依賴字幕時間來判斷。

你無法聽聲音。請誠實告知：聲音已經過調整和測量，但最終由用戶的耳朵決定。

向用戶回報結果

簡短、淺顯，格式如下：

• 檔案位置，以及如何開啟（Finder，Reel 編輯器資料夾內的 Edited 資料夾）。
• 裁切了哪些部分（「從開頭移除了 1.1 秒的靜音，縮短了兩個過長的停頓，從 36 秒縮短到 33 秒」）。
• 畫面是否翻轉及原因。
• 現在的音量測量值（「大約 -14，是 Instagram 和 TikTok 的常用音量」）。
• 字幕：字型、顏色，以及任何你修改的字詞。
• 任何你無法修正的問題，以及用戶可以如何要求更改。

然後詢問用戶想要更改什麼，並從上方設定列表中提供一兩個建議。

可能發生的問題

• 「找不到語音」：片段是靜音或只有音樂。請告知用戶。
• 字幕位置錯誤或截斷：檢查報告中的 inside_safe_zone；調降 size。
• 找不到字型：腳本會備援使用 Arial Black 並顯示提示。提供內建字型之一（docs/STYLE.md），或下載免費字型（來自 fonts.google.com 的 .ttf 檔案）至 ~/.reel-editor/fonts/，並將 captions.font 設為不含 .ttf 的檔案名稱。
• 缺少設定工具：執行 scripts/setup.sh。如果缺少 Homebrew，請遵循 CLAUDE.md。
• 編輯時間過長：超過 3 分鐘的 4K 片段較耗資源。請告知用戶並讓它繼續執行。

嚴格規則

• 絕不刪除或修改用戶的原始影片。
• 絕不在對話中要求或接受密碼或 6 位數驗證碼。
• 不使用付費服務，也不將用戶的影片上傳至任何地方。所有處理都留在這台 Mac 上，從 iCloud 下載除外。
• 除非用戶要求，否則不加入「滑動提示」或「追蹤我」等覆蓋層。
• 不添加用戶未說過的內容：字幕僅顯示實際說出的話語。