1mxffe/editor-reels

Reel 編輯器 — Gutmann & Silva

完整流程。從儲存庫根目錄執行；所有 Python 指令使用 python3 -I。格式與安全區域請參考 references/formatos-reel.md；字幕規則請參考 references/legendas.md；圖表卡片請參考 references/graficos.md。

不變的規則

• 文字屬於事務所。 事務所在錄製前已審核過文字；此工具不檢查 OAB 規則。口白、字幕、卡片及封面均以使用者批准的內容為準。
• 靜態字幕，逐句顯示。 不使用彈跳或逐字效果（僅允許最多 150 ms 的淡入/淡出）。
• 剪輯是可逆的。 原始檔案 entrada.<ext> 絕不會被修改；剪輯決策儲存在 cortes.json 中，可編輯並重新套用。
• 品牌資訊僅來自 brand/brand.json。 顏色、字型與 @ 帳號均由此檔案決定。切勿自行發明品牌值；若缺少，請進行訪談。

開始之前

執行 python3 -I scripts/doctor.py 並依照最後一行輸出處理。腳本需要 Python 3.11 或更新版本（macOS 自帶的 python3 是 3.9：請執行 brew install [email protected]）；doctor 腳本可在舊版 Python 下執行，僅用於提示此需求（python >= 3.11）。

• READY：可直接進行。
• READY WITH LIMITS：僅缺少選用項目。若缺少 faster_whisper，請告知自動轉錄不可用：要求執行 pip install -r requirements.txt 或提供已完成的 transcricao.json，然後繼續。若缺少圖表相關套件（chromium + playwright）或缺少 node，則在不使用卡片的情況下繼續，並告知如何安裝（請參考 references/graficos.md）。若缺少 Pillow 或 node，則自動封面（步驟 9 與 10）無法執行：要求執行 pip install -r requirements.txt / 安裝 node，或者改用 Figma 路徑。
• MISSING：停止。列出帶有 ✘ 的項目（python、ffmpeg、ffprobe、磁碟空間），並告知如何安裝；請勿嘗試渲染。

品牌訪談

僅在 brand/brand.json 缺失、不完整或含有無效值時執行（python3 -I scripts/brand.py check brand/brand.json 會回傳錯誤）。

1. 僅在 brand/brand.json 完全不存在時才產生種子檔案： python3 -I scripts/brand.py seed brand/brand.json。種子資料來自 brand/guia-visual.md（深海軍藍 #001931、Poppins 字型、靜態字幕）。 seed 僅用於檔案不存在的情況，絕不覆蓋現有檔案（它會拒絕）；若檔案存在但不完整或無效，請修正 check 指出缺少的鍵值，不使用 --force。
2. 一次只問一個問題，每次均提議種子值，並等待使用者回答後再問下一個：(a) 調色盤、(b) 字型、(c) 字幕樣式、(d) 官方社群 @ 帳號。
3. 將每個回答記錄到 brand/brand.json 中，並用 brand.py check 確認。@ 帳號沒有種子值：切勿自行發明；在使用者提供之前，將 handles 保留為空。當使用者提供時，請用 python3 -I scripts/brand.py set-handles brand/brand.json @使用者 [@使用者2] 記錄。

流程

1. 建立 projects/<slug>/ 目錄（slug 為主題的簡短代碼），並將影片複製到 projects/<slug>/entrada.<ext>。

2. python3 -I scripts/transcribe.py projects/<slug>/entrada.<ext> projects/<slug>/transcricao.json 若 doctor 回報 READY WITH LIMITS（缺少 faster-whisper）：請在轉錄前執行 pip install faster-whisper 安裝，或要求提供一個已完成的 transcricao.json。無音訊的影片會在此步驟失敗：請要求更換檔案。

3. python3 -I scripts/cut.py detect projects/<slug>/transcricao.json projects/<slug>/cortes.json

4. 向使用者顯示剪輯清單（id、開始–結束、類型：靜默、口頭禪、重複）以及總節省時間。若使用者拒絕某個剪輯，請將 {"cuts_removed": ["c3"]}（被拒絕的 id）記錄到 projects/<slug>/decisions.json，然後執行 python3 -I scripts/review_apply.py apply projects/<slug> projects/<slug>/decisions.json （被拒絕的剪輯仍會保留在 revisao.json 中，可隨時恢復）；請勿手動編輯 cortes.json。

5. 圖表（選用）： 若某張卡片有助於理解口白內容（如期限、條件、步驟），則最多每約 8 秒提出一張，在使用者同意後，依照 references/graficos.md 的格式將資料寫入 projects/<slug>/graficos.json（標題最多 60 字、內文最多 140 字、at 為剪輯後時間軸上位置、持續 1–6 秒，若有 materiais/ 中的圖片則可使用）。若無卡片，跳過此步驟。

6. python3 -I scripts/render.py projects/<slug> preview 並提供 projects/<slug>/saida/preview.mp4（540×960）的路徑。

7. 審閱： 預覽完成後，在 Chromium 瀏覽器中開啟審閱頁面 — 在 macOS 上使用 open -a "Google Chrome" review/review.html（單純的 open 可能開啟 Safari，無法存取資料夾）；在 Linux 上若預設瀏覽器是 Chromium/Chrome 則使用 xdg-open review/review.html，否則使用 google-chrome review/review.html — 並請使用者選擇 projects/<slug>/ 資料夾。在此之前，請先產生閱讀用視圖：python3 -I scripts/review_apply.py build projects/<slug>。詳細資訊請參考 references/revisao.md。

8. 「套用審閱」 → 依序執行： python3 -I scripts/review_apply.py apply projects/<slug> projects/<slug>/decisions.json、 python3 -I scripts/review_apply.py build projects/<slug> 以及 python3 -I scripts/render.py projects/<slug> preview；告知使用者按下「重新載入 review.json」。若 apply 失敗（回傳碼 1），表示未寫入任何資料：請讀取錯誤訊息並修正決策。若無法使用審閱頁面（瀏覽器無法存取資料夾且無替代方案），請直接在對話中進行審閱，並以相同格式記錄 decisions.json。

9. 封面 — 選擇畫面（在預覽獲得批准後）：從原始影片中抽取候選畫面， python3 -I scripts/cover_frames.py video projects/<slug>/entrada.<ext> projects/<slug>/capa （可選參數 --n 3；每行輸出一張圖片路徑），或者，若使用者提供照片，則執行 python3 -I scripts/cover_frames.py photo <照片路徑> projects/<slug>/capa （會儲存為 capa/foto.png）。向使用者顯示 capa/candidato-N.png 檔案，並詢問哪個畫面呈現了他想要的微笑：由使用者選擇，工具僅負責選取清晰且分布均勻的畫面，不具備微笑偵測功能。若沒有任何畫面符合需求，請要求提供照片或使用不同的 --n 重新執行。詳細資訊請參考 references/capa.md。

10. 封面 — 合成（在選擇畫面之後）。詳細資訊請參考 references/capa.md。 (a) 強制要求 @ 帳號： 若 brand/brand.json 中的 handles 為空，請詢問一次 @ 帳號，並使用 python3 -I scripts/brand.py set-handles brand/brand.json @使用者 記錄；切勿自行發明。 (b) 詢問鉤子（最多 28 個字元，例如「3 大迷思」）、標籤區域（最多 28 個字元）以及副標題（最多 90 個字元；最後一個換行之後的部分會以淺藍色顯示）。 (c) Figma 路徑（首選，若 Figma 連接器可用且已授權）：在使用 use_figma 之前先載入 figma-use 技能，複製 POSTS-OUTUBRO 檔案中的 272:2 框架，替換照片和文字，加上 @ 帳號，並以 1x PNG 匯出至 projects/<slug>/capa/capa.png（詳細步驟請參考 references/capa.md）。 (d) 無 Figma 或匯出失敗時： python3 -I scripts/cover_compose.py projects/<slug>/capa/candidato-N.png brand/brand.json projects/<slug>/capa/capa.png --hook "3 大迷思" --area "IR 豁免" --subtitle "白色行 突出行" （或使用 capa/foto.png）。回傳碼 1 表示未寫入任何資料；請讀取錯誤訊息（缺少 @、照片太小、鉤子超過 2 行、文字過長、輸出路徑與輸入檔案相同、缺少 Chromium）。 (e) 向使用者顯示 capa.png 並請求批准；若使用者要求調整，請修改後重新產生。

若任何腳本失敗（回傳碼 1）：請讀取錯誤訊息，修正原因（品牌資訊缺失或無效、轉錄中無口白、缺少檔案、卡片無效或缺少圖表渲染器 — 錯誤訊息會指出具體是哪張卡片），然後重複執行。請勿遺留部分完成的檔案。

觸發條件

• 「build preview」/「montar preview」 → 執行 python3 -I scripts/render.py projects/<slug> preview。
• 「final」/「versão final」 → 執行 python3 -I scripts/render.py projects/<slug> final （1080×1920，輸出為 saida/final.mp4）。僅在交付預覽之後才可執行；使用者的「final」即代表預覽已獲批准，因此請直接渲染，無需再次請求確認。

目標時長

Reel 快速版：12–15 秒；深入版：30–45 秒。計算已剪輯後影片的時長（原始長度減去所有剪輯的總時長）。若時長落在這兩個區間之外，請告知並建議調整方式（例如進一步剪輯，或保留更多片段）。不要封鎖流程。

尚未實作的功能

頁面審閱、素材標籤（步驟 7 與 8）、圖表卡片（步驟 5）以及封面（步驟 9 與 10：畫面選擇、透過 Figma 或 scripts/cover_compose.py 合成）皆已實作。尚未實作發佈功能：不會自動將內容發佈到 Instagram。不具備微笑偵測功能（由使用者選擇畫面），且 assets/fonts/ 中僅有 Poppins-Bold.ttf 檔案：字幕將以 Poppins Bold 渲染，卡片與封面中的所有文字也使用相同字重（透過 Figma 製作的封面才會使用精確的字型設定）。若需完整的品牌字型，請將 Poppins-Regular.ttf、Poppins-SemiBold.ttf 與 Poppins-ExtraBold.ttf 也放入 assets/fonts/ 目錄中（SIL OFL 授權，可放入儲存庫）。影片與字幕僅透過 render.py 輸出（其他會輸出影片或字幕的腳本僅為除錯用途）。