soundcheck 是做什麼的？
AI 影片在聽覺上完成之前，看起來早就完成了。TTS 片段以不同的音量黏合在一起，背景音樂（music bed）從未進行側鏈壓縮（ducking），混音被推向限制器以聽起來「大聲」，而 AI 語音則持續保有 6-10 kHz 的嘶聲和 100-300 Hz 的轟鳴聲。
soundcheck 將這些問題轉化為數字，修復它，並證明修復結果。
執行方式
python scripts/soundcheck.py analyze <file> [--target youtube] [--music music.wav] [--json]
python scripts/soundcheck.py fix <file> [--target youtube] [--music music.wav] [--out out.wav] [--level] [--naturalize]
python scripts/soundcheck.py demo
fix 需要在 PATH 中有 ffmpeg。analyze 和 demo 只需要 Python 3 + numpy（若已安裝 scipy，將用於更快的濾波）。
給 fix 一個影片，它會回傳一個影片：修正後的音訊會被嵌入（mux）到原始影片串流（僅複製，從不重新編碼）。若未使用 --out，它會在來源檔案旁寫入 <name>.soundcheck.mp4。
--level 在母帶處理之前匹配獨立口語片段的音量。適用於逐行錄製或合成的對話；請勿用於以音樂為主的内容，因為音樂中的漸強或漸弱是編曲的一部分，而非缺陷。analyze 會列印出最大段落跳躍的時間戳記，供您判斷。
在信任之前先驗證
python scripts/verify.py # 20 項檢查，exit 0 = 全部通過
該測試套件會檢查：我們的儀表與 ffmpeg 的 ebur128 一致、fix 僅在每一項特徵都通過時回傳 exit 0、交付檔案以獨立儀表重新測量、動態範圍未被壓扁，以及靜音 / 短片段 / 單聲道 24 位元 / mp4 / 缺少檔案等情況的行為。若在您的機器上失敗，請先修復問題，再處理任何人的音訊。
當您處理真實素材時，務必進行 A/B 比對。通過測量是必要條件，而非充分條件。
工作流程
- 在觸碰任何東西之前先測量。 執行
analyze。永遠不要從猜測開始進行 EQ。 - 閱讀分數卡，而非分數。 分數是摘要；失敗的特徵才是需要處理的工作。
- 修復。 執行
fix --target <platform>。它會根據測量結果選擇修正 EQ 的深度，套用處理鏈，根據我們自己的響度測量計算靜態增益，進行限制，然後重新測量。 - 驗證。 當任何測量到的特徵仍在規格之外時，
fix會以非零退出碼結束。不要在非零退出碼時回報「完成」——改為回報剩餘的特徵。 - A/B 比對。 保留原始檔案。如果修正後的結果聽起來比問題還糟（過度 EQ、幫浦效應），請降低修正深度並重新執行。通過測量是必要條件，而非充分條件。
7 項 AI 音訊特徵
| # | 特徵 | 測量方式 | 目標值 | 常見原因 |
|---|---|---|---|---|
| 1 | 段落之間音量不匹配 | 語音頻段區域音量、相鄰差值 | <= 3 dB | TTS 片段分別渲染 |
| 2 | 無保留動態峰值 | 真實峰值 | <= -1 dBTP | 「讓它大聲」的母帶處理 |
| 3 | 人聲/音樂衝突 | 人聲 LUFS - 音樂 LUFS | >= 4 dB | 無側鏈壓縮 |
| 4 | 刺耳齒音 | 6-10 kHz / 1-4 kHz 能量比 | <= 0.45 | 合成的 /s/ 和 /sh/ 音 |
| 5 | 低中頻混濁 | 100-300 Hz / 300-3k 能量比 | <= 0.40 | 近距離轟鳴、大音量低頻背景 |
| 6 | 無環境、無空間感 | 噪聲基底 vs 節目音量 | >= 45 dB 以下 | 降噪假影、分層的環境聲 |
| 7 | 相位 / 直流問題 | L/R 相關性、直流偏移 | corr >= 0.2 | 拼接片段、重新取樣 |
特徵 3 僅在您傳入 --music 並提供獨立音樂素材時執行。當素材中沒有靜音段落時，特徵 6 會回報 n/a——安靜的音樂不是噪聲，誠實的「無法評估」不是通過。特徵 1 會報告最大跳躍發生的位置，以便人類聆聽判斷。
響度對照表
| 交付平台 | 整合響度 | 真實峰值 | 備註 |
|---|---|---|---|
| YouTube / TikTok / Reels | -14 LUFS | -1 dBTP | 平台會在此標準正規化 |
| Spotify | -14 LUFS | -1 dBTP | |
| Apple Music | -16 LUFS | -1 dBTP | |
| Podcast（立體聲 / 單聲道） | -16 / -19 LUFS | -1 dBTP | |
| 廣播（EBU R128） | -23 LUFS | -1 dBTP | |
| 短劇 / OTT（中國） | -24 LKFS | -1 dBTP | |
| 電影院 | -27 LUFS | -2 dBTP | 以對話為錨點 |
處理鏈順序（此順序至關重要）
高通濾波 70 Hz -> 減法 EQ（先處理混濁，再處理齒音） -> 輕柔壓縮 -> 限制器 -> 靜態增益 -> 限制器
- 修正 EQ 的深度是根據測量到的特徵值推導而出，而非來自固定的預設值。
- 壓縮刻意設定為輕柔模式（2.5:1，約 3-6 dB 增益衰減）。這是後期製作，不是聲音設計。
- 增益在修正鏈之後套用，並根據處理鏈輸出的測量結果設定，因此即使在 EQ 改變了響度之後，交付檔案仍能符合規格。
- 限制器設定在 0.79（-2 dBFS 樣本峰值），以便在 -1 dBTP 下承受樣本間過衝（inter-sample overshoot）。
護欄
- 在沒有重新測量的情況下，切勿宣稱成功。 腳本的退出碼是最終的真相來源。
- 不要對有損格式進行兩次編碼。 將 WAV 解碼一次，在 WAV 中進行處理，最後編碼一次。
- 不要為了偽造品質而升頻。 輸出 48 kHz；loudnorm 的 192 kHz 內部取樣率不是功能特點。
- 不要為了達到數字而壓扁動態範圍。 如果達到 -14 LUFS 需要超過 6 dB 的限制，請如實告知，並改以 -16 LUFS 交付——一個被壓扁的混音比一個安靜的混音更糟。
- 音樂素材要保持獨立。 對混合好的音軌進行側鏈壓縮（ducking）會破壞人聲；請要求獨立素材。
- 保留原始檔案。 始終寫入一個新檔案。
這個工具無法修復的問題
當來源音訊在 8 kHz 以上幾乎沒有能量時——這是 16/22 kHz 的 TTS 被通過 48 kHz 工程處理後的特徵——analyze 會列印警告。這種沉悶感不是母帶處理問題，任何 EQ 都無法恢復。如果觸發了警告，請如實告知而非宣稱「已修復」：使用神經網路 TTS 重新渲染語音，再進行母帶處理。
--naturalize 會加入一個小房間聲、呼吸/環境噪聲基底，以及一些高頻空氣感。它移除了「乾燥、數位化的寂靜」這個線索；但它無法創造韻律（prosody），也無法拯救機械化的來源。在音樂為主的内容上，請勿預設啟用它。
限制
- 「音樂背景」特徵需要獨立素材；若無則無法測量人聲/音樂平衡。
- 噪聲基底只有在有真正的安靜段落時才有意義。
- 真實峰值是 4 倍取樣；需要 8 倍取樣的廣播機構應使用自己的儀表進行驗證。
- 這是一個交付工具，而非創意混音。它無法讓糟糕的表演變好。