音效設計：為完成影片添加真實音效
目標：讓影片聽起來像是由擁有良好音效庫的剪輯師所剪輯。每個音效都是來自 EditAtlas 的真實檔案，放置在您已檢視過的影格上，並以可量化說明的音量級別呈現。
整個過程中，有兩件事始終成立，請據此規劃：
- 您無法聆聽。 您根據音效的描述和測量數據（
sounds.py info）來選擇，使用check.py檢查放置位置和音量，並提供一個簡短的時刻清單供人員聆聽。切勿說某個音效「聽起來不錯」；請說明測量了什麼以及哪些部分仍需要耳朵判斷。 - 您不得憑空創造。 僅針對人員提供給您的影片進行工作。如果沒有影片，請索取。如果某個時刻需要的音效不存在於圖書館中，請將其留為靜音並在報告中說明。
所有指令碼均位於 scripts/ 目錄下（需要 Python 3.9+、numpy、用於影格表的 Pillow、以及需在 PATH 中的 FFmpeg 與 ffprobe）。請在您自己的工作目錄（work/、result/）中執行它們，並傳入技能資料夾的路徑；切勿在人員的專案或此技能資料夾中寫入內容。
python SKILL/scripts/moments.py FILM.mp4 --out work/moments # moments.json, sheet.png, overview.png
python SKILL/scripts/moments.py FILM.mp4 --at 10.4 --out work/at # 在一個時間點前後每隔 0.1 秒的影格
python SKILL/scripts/sounds.py search "玻璃碰撞" --max-dur 2 # 從公開索引中獲取 ID
python SKILL/scripts/sounds.py info sfx-ID sfx-ID # 下載一次，SHA-256，測量數據
python SKILL/scripts/sounds.py sheet sfx-ID sfx-ID --out work/c.png # 候選音效的波形+頻譜圖
python SKILL/scripts/mix.py work/cues.json --out result/FILM_sfx.mp4 # MP4 + _track.wav + _resolved.json
python SKILL/scripts/check.py result/FILM_sfx_resolved.json --moments work/moments/moments.json --listen-out result/listen.wav
音效來自 https://raw.githubusercontent.com/EditAtlas/sfx/main/ 並快取在 ~/.cache/editatlas-sfx 中（可透過 EDITATLAS_SFX_CACHE 變更路徑）。如果您有 EditAtlas/sfx 的本地克隆，請傳遞 --mirror PATH（在 sounds.py 的子命令之前），這樣就不需要下載。
1. 檢視影片及其聲音
執行 moments.py。它會報告現有的音訊（has_audio、LUFS、靜音所佔比例），並根據像素差異找出三種時刻：cut（場景切換）、move（動作開始或達到峰值）、land（動作停止：物體穩定下來）。然後使用 Read 工具開啟 overview.png 和 sheet.png：這些數據可能會遺漏柔和的動畫（例如，在靜止的臉孔上放大的徽章不會產生 cut），並會過度報告攝影機晃動。在關鍵處，使用 --at T 繪製某個時間點周圍的影格，找出物體出現、停止或轉變的精確影格。
決定影片原始音訊的處理方式：
| 您在數據中聽到的和看到的內容 | 提示表設定 |
|---|---|
無音訊，或 silent_share 接近 1 | "keep_audio": false：音效支撐整部影片；將音量調整至約 -16 LUFS |
| 僅有音樂 | "keep_audio": true：音效約低於音樂 3 LU；儘可能在節拍上放置重音 |
| 有人在說話（字幕、臉孔、領夾麥克風） | "keep_audio": true, "under_voice": true：約低於人聲 8 LU；使用更少、更輕的音效 |
| 已混合在音軌中的合成嗶嗶聲 | 詢問：替換它們需要分軌音源；在其上疊加真實音效會造成雙重效果 |
如果不確定是否保留影片的音訊，請詢問人員。
2. 根據您的觀察編寫事件列表
每個值得添加音效的時刻一行：時間、發生什麼事、何種音效。像剪輯師一樣思考：
- 出現的東西（徽章、晶片、按鈕、標題卡）：短促的爆裂聲、滴答聲或柔和的叮噹聲，
anchor: start。 - 移動穿越或轉場：一個呼嘯聲，其最響點落在到達時刻，
anchor: peak。 - 有重量的東西停下（標誌、產品、郵戳）：在其停止的影格上使用撞擊聲或重擊聲，
anchor: peak。 - 螢幕上的真實物體（玻璃杯、冰塊、紙張、鑰匙、飲料）：使用匹配的 Foley 音效，而非 UI 音效。
- 成功/錯誤狀態：肯定的叮噹聲，否定的短促蜂鳴聲或警報聲。每部影片使用同一系列的介面音效。
- 逐漸累積的過程：一個上升音效，其結尾落在回報時刻，
anchor: end。
並非每個動作都需要音效。節奏和品味的量化規則寫在 references/taste.md 中；在撰寫首次提示表之前先閱讀它。
3. 選擇音效：閱讀、測量、比較
- 搜尋。如果 EditAtlas MCP 已連接，
search_sfx的排序效果更好（它也能理解越南語）；否則使用sounds.py search。標題故意避免使用其原始檔案中的詞彙（例如「相機快門」被稱為「鏡頭光圈滴答聲」），因此請根據聲音的本質進行搜尋，並嘗試同義詞和類別篩選器。 - 對 2-4 個候選音效執行
sounds.py info。閱讀：audible_s（實際可聽到的長度；檔案可能更長）、attack_s（0.0x = 瞬間爆發，0.3+ = 漸強）、peak_t_s、centroid_hz（低於 ~1500 為低沉，高於 ~6000 為明亮）、mono_loss_db（低於 -6 表示在手機上聲道會抵消；mix.py隨後會播放較大聲的聲道）。 - 當兩個候選音效的數據相同時，使用
sounds.py sheet：尖銳的垂直線是點擊聲，模糊的痕跡是呼嘯聲，底部的能量代表重量。 - 根據移動的物體和它接觸的對象來選擇，然後根據長度：0.3 秒的晶片爆裂聲不能是 1.8 秒的卡通爆裂聲。使用
max_len來截斷較長的檔案，並加上淡出效果。 - 同一種類型的重複時刻（例如三個晶片）應使用同一系列的不同版本（如 Tiny Plop 05、06、Empty Plop 06），而不是三次使用同一個檔案。
圖書館在某些方面還不夠豐富（測量日期 2026-11-07）：沒有液體傾倒或嘶嘶聲、沒有環境聲、沒有郵戳聲、水滴和重擊聲也很少。請選擇最接近的真實音效，並在報告中說明缺口，而不是強行使用不合適的聲音。
4. 編寫提示表並進行渲染
{
"video": "work/film.mp4",
"keep_audio": false,
"under_voice": false,
"cues": [
{"t": 0.30, "id": "sfx-988dafbd36", "role": "whoosh", "label": "標題落下"},
{"t": 0.62, "id": "sfx-mi630472", "role": "foley", "anchor": "start", "max_len": 0.9, "gain_db": -2, "label": "冰塊入杯"},
{"t": 8.30, "id": "sfx-fs339114", "role": "hit", "label": "瓶子著陸"},
{"t": 0.00, "id": "sfx-c7d271e90f", "role": "ambience", "bed": true}
]
}
t是時刻的影格時間（秒）。role設定音量和預設錨點（參見references/taste.md）。anchor：start將可聽到的起始點放在t，peak將最響點放在t，end將可聽到的結束點放在t。- 每個提示的屬性：
gain_db（相對於角色音量）、max_len、fade_in、fade_out、offset_in、pan（-1 到 1）。 "bed": true：在整部影片下方放置一個長而穩定的環境音，音量為 -54 dBFS（幾乎聽不到）。僅適用於音效獨立的影片；切勿放在人聲或音樂之下。如果影片很長，它會自行交叉淡入淡出。
執行 mix.py。它會列印每個音效的放置時間和峰值音量，並在時刻過早導致音效必須從檔案內部開始播放時發出提示。
5. 檢查、修正、再檢查
每次渲染後都執行 check.py；退出碼為 1 表示它標記了問題。它會讀取 mix.py 寫在 _resolved.json 旁邊的 WAV 音軌，因此當您複製結果時，請將這些檔案放在一起。它會根據自身波形在渲染音軌中找到每個音效，因此 sync 是真實的：任何偏離超過一個影格的時間點都是提示表中的錯誤。它還會測量每 10 秒的動作數、最長的空白間隔、強烈的撞擊聲、重複次數、數位靜音、主音量與真實峰值、單聲道折疊效果，以及有多少強烈的畫面時刻得到了音效。
對於每個標記的問題，要麼修正它（在空白處添加音效、更換重複的音效、移動提示點），要麼判斷它是正確的並在報告中說明原因（「7.8 秒的空白是說話段落，人聲可以覆蓋它」）。關於緩慢起音的備註是提示：如果該時刻是音效的峰值，則將該提示切換為 anchor: peak。進行兩到三輪的調整是正常的。
6. 交付
提供給人員：
FILM_sfx.mp4和FILM_sfx_track.wav（僅音效，完整長度，可放在他們自己的剪輯下方）。- 一個簡短的表格：時間、時刻、音效名稱和 ID、選擇該音效的原因。
check.py的數據（節奏、最長空白、LUFS、真實峰值）以及每個剩餘標記的含義。- 聆聽清單（
listen.wav將這些時刻合併成一個檔案）：「請用耳機和在手機上各聽一次」。 - 缺口：未被添加音效的時刻以及圖書館缺少的音效。
使用人員的語言撰寫報告。切勿聲稱您聆聽過。
可選：真實音效引擎
Clipwing 的 real-sfx 技能（MIT 授權指令碼，作者 Alexander Korbanov）使用更強大的引擎完成相同工作：類型化提示清單、合成層移除、節拍網格、9 軸評論。它可以將整個 EditAtlas 圖書館作為其主要音效包使用。請參閱 references/real-sfx.md 了解適配器和已驗證的內容。