foley：音效精準命中幀數
你無法聽見。earshot 就是你的耳朵：絕不能只說音效「聽起來合」或「同步」，必須給出 earshot 數字。
SKILL_DIR 等於此技能自己的資料夾（技能載入時會顯示其基底目錄）。請在影片所在資料夾中操作。將所有產出放在影片旁的 foley/ 目錄下。
需求
ffmpeg與ffprobe須在 PATH 中，Python 3.10+。earshot須在 PATH 中：uv tool install "earshot[mcp] @ git+https://github.com/Leonxlnx/earshot"然後執行earshot doctor --fetch（約需 1.1 GB 模型，僅用 CPU）。- 需連網存取 Openverse（匿名限制：每分鐘約 20 次請求，每天 200 次）。
1. 找出提示點（先看，再量測）
- 執行
python3 SKILL_DIR/scripts/find_cues.py VIDEO --out foley/cues-candidates.json，它會輸出畫面變動的峰值（幀與幀之間的差異），並將聯絡表寫入foley/sheets/。 - 閱讀聯絡表。為每個需要聲音的瞬間命名（撞擊、腳步、關門、快速轉彎的颼聲、碎裂、環境底噪），並選定其精確幀數；利用動作峰值縮小範圍，但最終以你看到的為準。跳過你實際上無法看到的聯絡點。
- 撰寫
foley/cues.json：[{"id": "hit1", "t": 0.625, "kind": "hit", "what": "拳頭擊中張開的手掌"}, ...]。
2. 取得 CC0 音效
針對每一種聲音類型，提供 2–4 個搜尋詞：python3 SKILL_DIR/scripts/fetch_cc0.py "重拳撞擊" foley/sounds/hit --limit 8。
它只保留來自 source=freesound 且授權為 license=cc0 的結果，並在 foley/sounds/sources.json 中記錄標題、創作者、授權條款與來源頁面。CC0 無需標註來源，但若為商業用途，請告知使用者開啟來源頁面：Openverse 不保證授權資訊的準確性。
3. 使用 earshot 挑選與修剪
earshot rank "<該瞬間聽起來的樣子>" foley/sounds/<kind> --top 3 --out foley/rank-<kind>.json。描述聲音本身，而非畫面（例如「拳頭快速打上張開手掌的短促耳光聲」）。earshot find FILE "<相同詞語>" --kind event --top 3 --out foley/find-<id>.json用於一次性音效；--kind texture用於環境底噪。請拒絕標記為「頭部被切」或「尾部被切」的修剪結果。- 記錄每個修剪結果的同步點：撞擊類使用攻擊點（起點 + 約 5 毫秒）；颼聲類使用最大音量點，而非起點。
4. 放置
撰寫 foley/plan_v1.json（請參閱 scripts/mix.py 的檔頭說明），然後執行 python3 SKILL_DIR/scripts/mix.py foley/plan_v1.json。影片僅被複製，絕不重新編碼。
5. 回聽與修正（關鍵步驟）
earshot timeline OUT.mp4 --cues "t1,t2,..." --out foley/timeline_v1.jsonpython3 SKILL_DIR/scripts/check.py foley/timeline_v1.json id1,id2,... foley/check_v1.json當偵測到的發起時間與畫面的差距小於 40 毫秒，且音量高於底噪至少 6 dB 時，該提示點才算通過。- 只修正未通過的項目，依據量測到的數值進行調整：
- 延遲 / 過早 → 將該事件依偏移量移位（颼聲通常偏晚，因為其峰值在起點之後才出現）；
- 被淹沒（低於底噪 6 dB） → 調高該音效或降低底噪；
- 真實峰值超過 −1 dBTP 或裁切 → 降低最大聲的撞擊（限幅器無法在取樣的第一瞬間抓住暫態）。
- 撰寫
plan_v2.json，重新渲染，再次聆聽。重複直到所有提示點都通過且真實峰值 ≤ −1 dBTP。 - 響度：純音效軌會含有大量峰值，通常約為 −20 LUFS，真實峰值 ≤ −1 dBTP。這是正常現象；最終的響度請在後期編輯時，與人聲、音樂一起調整。不要在這一階段推高響度。
6. 報告
撰寫 foley/report.md：每個提示點（時間、幀數、描述）、使用的檔案（標題、創作者、CC0 來源頁面）、第一次聆聽時的偏移量與音量，以及你修改了什麼與最終數值。明確說明這些檢查是 earshot 的量測結果，而非人耳聆聽，並建議使用者自己聽一次。
規則
- 除非使用者要求，否則只能使用 CC0 音效。絕不能使用任何缺少
sources.json記錄的音效。 - 不要憑空捏造你沒看到的撞擊點。不要說某個音效「聽起來很好」；請引用 earshot 的數據。
- 保持原始影片不變；輸出檔名為
<原始名稱>-sfx.mp4。