editor-video

客戶專屬影片編輯引擎

用於像人類編輯一樣進行影片剪輯的引擎與流程：理解素材、精準剪輯、套用客戶風格、檢查與交付。引擎本身沒有預設風格：所有視覺元素皆來自 clientes/<CLIENTE>/look.py。

SKILL_DIR = 此技能所在的資料夾。工具：engine/reel.py，tools/{takes.py, words.py, media.sh}， templates/ 目錄下的範本，以及 looks/ 目錄下的初始風格。

系統需求（首次使用時請檢查；若缺少則安裝）

• ffmpeg、python3、node/npx · macOS：avconvert 和 sips（系統內建）用於 HDR→SDR 轉換和 HEIC 照片處理。
• HyperFrames（渲染引擎與音效庫）：npx hyperframes skills update general-video（也會安裝 media-use）。
• watch（用於觀看/轉錄影片以及使用 yt-dlp 下載 Instagram/TikTok/YouTube 連結）：來自 github.com/bradautomates/claude-video 的 watch 技能，使用本地 WhisperX 引擎（免費）：setup.py --engine local 和 --backend whisperx。
• whisper 命令列工具（用於驗證視窗）：uv tool install --python 3.12 openai-whisper --with setuptools。
• MFA（用於字詞對齊，精度 ±20 毫秒）：brew install --cask miniforge，conda create -n mfa -c conda-forge montreal-forced-aligner -y， conda run -n mfa mfa model download acoustic spanish_mfa 和 … dictionary spanish_mfa（其他語言請使用對應模型）。

資料夾結構（工作根目錄，例如 ~/Documents/VIDEOS/）

clientes/<CLIENTE>/
├── estilo.md      客戶風格指南（來自 templates/estilo.md）— 編輯前**務必**閱讀
├── look.py        將風格轉換為引擎選項（來自 looks/nativo.py 或 looks/datos.py）
├── refs/          參考影片 + 畫面格點陣圖 + 分析
├── marca/         標誌、顏色、字型、自有音樂
└── proyectos/<AAAA-MM-DD_nombre>/
    ├── crudo/     用戶提供的原始素材 — **切勿**修改或刪除
    ├── broll/     輔助鏡頭（可選）
    ├── guion.md   腳本或筆記（可選；對當前專案而言優先於 estilo.md）
    ├── trabajo/   media/（轉換後）、mfa/、gt/，以及每個影片專屬的資料夾，內含 config.py 和 takes.json
    └── final/     僅包含最終交付檔案：<cliente>_<tema>_v1.mp4 · 修正版本為 v2、v3，且不刪除前一個版本

用戶無需手動建立資料夾：只需說「為 開新專案，素材在 <路徑>」，系統便會建立 proyectos/<日期_名稱>/ 資料夾，並移動原始素材（若素材位於工作根目錄外且用戶不希望移動，請先詢問）。

流程

0 · 新客戶 → 分析參考資料並撰寫 estilo.md

1. 下載/讀取參考資料（透過 watch 工具使用 yt-dlp）到 refs/ 資料夾。理想數量約為 5 個。
2. 針對每個參考資料測量：鉤子（前 3 秒）、剪輯頻率（使用 ffmpeg -vf "select='gt(scene,0.3)',showinfo" 計算）、 字幕（字型或最接近的免費字型、大小、位置、顏色、高亮、動畫）、色彩/風格、卡片和動畫、聲音（音樂、音效、人聲）、 構圖、結構、CTA。畫面格點陣圖：fps=16/dur,scale=270:480,tile=8x2。
3. 撰寫 estilo.md（使用範本）僅包含在 ≥ 2 個參考資料中出現的模式；區分測量值和推斷值；不抄襲 他人語句或商標。若參考資料彼此矛盾，請詢問用戶優先遵循哪個。
4. 從最接近的初始風格建立 look.py，並根據指南進行調整。在編輯前，展示風格指南 + 測試靜態畫面並等待用戶批准。

1 · 理解原始素材

• 閱讀 estilo.md 和 guion.md。對每個檔案執行 ffprobe（檢查長度、旋轉方向、color_transfer）。
• 對每個原始素材執行 watch，設定 WATCH_WHISPERX_LANGUAGE=es 和 --out-dir trabajo/watch：了解說話內容、 哪些鏡頭可用、哪些需要重拍、絕對不要剪掉哪些部分。該轉錄文字是唯一的完整版本：將用於 MFA。
• 與腳本比對：腳本中哪些部分未拍攝或即興發揮 → 通知用戶。
• 對於多個無旁白的短片段（例如活動）：為每個片段建立畫面格點陣圖，按主題分類並建議分組方式 （每個主題一個影片 + 零散片段 + 一個總回顧）再進行剪輯。

2 · 準備媒體檔案

• media.sh video <原始素材> trabajo/media/<名稱>.mp4 [vertical|horizontal] — 將 HDR（iPhone/DJI）一次轉換為 SDR， 關鍵影格間隔 1 秒，30 fps。不要重複壓縮：每次壓縮都會損失細節。
• 照片：media.sh foto <照片> trabajo/media/<名稱>.mp4 2.5。用於對齊的音訊：media.sh audio。

3 · 字詞對齊（有旁白的影片）

• corpus/a.wav + corpus/a.txt（watch 工具輸出的純文字）→ conda run -n mfa mfa align --clean <corpus 絕對路徑> spanish_mfa spanish_mfa <輸出 絕對路徑> （必須使用絕對路徑，否則會失敗；不需要 --beam 參數）。words.py textgrid … words.json 和 words.py show words.json。
• 包含 ~ 的字詞（持續時間 > 1 秒）可能隱藏了暫停或重拍；長時間無文字的空白間隔可能是 watch 未能轉錄的重拍。 使用獨立的視窗驗證：從音訊中剪出 3–15 秒片段，執行 whisper --model small --language es --word_timestamps True，然後 words.py whisper … <偏移量>。在有噪音或重拍的片段中，MFA 可能偏差數秒。

4 · 選擇鏡頭 → takes.json → takes.py

• 針對每個句子選擇最佳鏡頭（通常是最後一個）；去除重拍、錯誤開始、填充詞（「呃」、「這個」）、 對編輯的指示（「這段我要做成另一個影片」）以及任何無助於達成目標的內容。務必符合最大長度限制。
• 時間範圍採用字詞起始時間：(第一個字的起始時間, 最後一個字的起始時間 + 0.2)。若結束時間早於最後一個字的起始時間， 則會吃掉該字。word_fix 用來修正 MFA 定位錯誤的字詞（使用獨立視窗中取得的時間）。
• 文字：phrases / words 用來修正 ASR 聽錯的內容（例如人名、品牌："Claude" 不是 "Klaus"，"IA" 不是 "ella"）。
• python3 $SKILL_DIR/tools/takes.py trabajo/<影片>/takes.json trabajo/<影片> → 輸出長度與最終文字。 完整閱讀輸出的文字：確保每段的最後一個字沒有遺漏，也沒有多餘的被截斷的字詞。

5 · 組裝影片

• trabajo/<影片>/：config.py（來自 templates/config.py），media → ../media（符號連結）， media.sh sfx trabajo/<影片>，hyperframes.json 最小內容為 {"paths": {"assets": "assets"}}。
• 在 edit(e) 中：卡片/POV/CTA、B-roll 和音效錨定到字詞上（e.word_t(None, "字詞")）。卡片放在邊緣： 若有縮放，臉部會變寬。每 ≤ 3 秒至少有一個可見事件（引擎會在不足時自動添加 auto-punches）。
• python3 $SKILL_DIR/engine/reel.py trabajo/<影片> → npx hyperframes check trabajo/<影片>（0 個錯誤； 「檔案過大 / 軌道密集 / 巢狀」等警告在此引擎中屬於正常現象）。

6 · 渲染前檢查

• npx hyperframes snapshot trabajo/<影片> --at <t1,t2,…> --no-end -o <絕對路徑>，針對每張卡片、鉤子和 CTA。 檢查：沒有元素遮擋臉部、文字沒有不美觀的斷行、顏色正確、字幕清晰可讀。
• 向用戶展示靜態畫面並等待批准（除非風格已獲批准且用戶說「直接渲染」）。

7 · 渲染與交付

• 在 trabajo/<影片> 目錄內執行 npx hyperframes render --quality delivery -o …/raw.mp4 → media.sh final raw.mp4 final/<客戶>_<主題>_v1.mp4（-14 LUFS）。僅刪除剛才產生的中繼 raw.mp4 檔案。
• 使用 watch --detail transcript 驗證：文字完整且無重複。若開頭「遺失」，請先使用 whisper 檢查前 3 秒 再下結論（完整轉錄有時會省略開頭）。

經驗教訓（請勿重蹈覆轍）

• 未轉換的 HDR 影片會顯得暗淡；請使用 avconvert 一次性轉換。
• 若需縮放效果，請使用 4K 解析度錄製：1080p 放大 13–22% 會顯得模糊。請告知客戶。
• 經過修正且包含更多字詞的句子不能平均分配時間：持續時間為 0 的字幕會卡住。
• 螢幕文字中的表情符號不一定能正確渲染：請避免使用。
• snapshot -o 使用相對路徑時會將檔案寫在專案目錄旁：請使用絕對路徑。
• 若同一個檔案在影片的兩個部分中使用，則必須在 takes.json 中使用不同的鍵（唯一 ID）。
• 請勿將音效庫上傳至任何儲存庫（media-use 的 Pixabay 授權）：請使用 media.sh sfx 將其按專案複製。
• 客戶對單一影片的修正（例如「第 07 段不要音效」）應在該影片的 config.py 中設定 （SFX = {"card": None, "broll": None, "cut": None} 以及卡片中的 sfx: None），不應編輯 index.html （否則重建後會遺失）。