使用 AudioFX 進行音效設計
AudioFX 將音效設計效果轉換為 ffmpeg filtergraph。每個效果都是一個字串，可直接插入 ffmpeg -af，或透過 CLI 應用於檔案。您在網頁工作室聽到的聲音，就是渲染後的輸出結果。
命令
在本文件中，sfx 代表：
node {{AUDIOFX_DIR}}/bin/sfx.mjs
如果此機器上 sfx 不是一個命令，請使用完整路徑。它可以從任何資料夾執行。如果因為 ffmpeg 問題而失敗，請執行 sfx doctor。
| 您需要的功能 | 命令 |
|---|---|
| 效果目錄 | sfx list (或 --json) |
| 參數、範圍與使用時機 | sfx describe <effect> |
| 處理音訊或影片檔案 | sfx apply <input> <output> <step...> |
| 為自己的 ffmpeg 產出 filtergraph | sfx graph <step...> |
| 測量響度與峰值 | sfx analyze <file> |
| 取得影片長度與硬剪輯點 | sfx cuts <video> |
| 尋找歌曲高潮（drop 候選）與低谷 | sfx sections <file> |
| 在時間軸上混合人聲、音樂與音效，音樂自動閃避人聲 | sfx mix <output> --voice v.wav --music m.wav [--sfx hit.wav@6] [--video cut.mp4]，或 sfx mix project.json <output> |
| 保留並層疊錄製的樣本 | `sfx sample add <file |
| 產生新的人聲、音效或歌曲（已處理） | `sfx generate <sfx |
| 讓使用者聆聽並調整 | sfx studio (開啟 http://127.0.0.1:5177) |
一個步驟的寫法是 effect[:param=value,param=value][@from-to]：
sfx apply voice.wav voice-phone.wav telephone
sfx apply clip.mp4 clip-fx.mp4 "underwater:[email protected]" --fade 0.4
sfx graph "reverb:space=cathedral,mix=0.4" "fade:in=0,out=2"
- 步驟按順序執行。
@3.2-7將效果限制在該時間視窗內，並在原始訊號與處理後訊號之間使用--fade秒的交叉淡變（預設為 0.25）。@3.2-表示從 3.2 秒開始到結尾。- 如果輸出檔案是
.mp4、.mov、.mkv或.webm，則影像部分會直接複製而不重新編碼，僅替換音訊。 - 如果您輸入了錯誤的參數，CLI 會列出有效的參數。不要猜測：執行
sfx describe。
工作流程
- 閱讀腳本或剪輯，標記需要處理的時刻：例如透過電話傳來的人聲、攝影機潛入水中、一段回憶、一個高潮點、一個喜劇剪接。
sfx cuts video.mp4會輸出影片長度及其硬剪輯點（較低的--threshold，預設 10，可捕捉較不明顯的剪輯點）。以秒為單位記下時間。 - 從下方表格選擇效果。 不確定時，使用
sfx list和sfx describe。從預設值開始：它們經過調校，聽起來清晰且不會過度。 - 在混合之前，分別處理每個音軌。 時代、角色和空間效果應作用於人聲或特定效果上，而不是整個混合。唯一的例外是會影響所有聽覺的敘事手法（如水下、爆炸後耳鳴、夢境）。
- 使用時間視窗來處理剪輯內部的變化 (
@from-to)，而不是裁剪和拼接檔案。 - 最後進行混合與標準化，使用
sfx mix（參見「混合」章節）：它會將音樂在人聲之下閃避，並將主輸出標準化至 -14 LUFS（適用於社交媒體和 YouTube，--loudness -16用於 Podcast，-23用於廣播）。對於單一檔案，在其效果鏈末端加上loudness可達到相同效果。然後使用sfx analyze檢查響度是否接近目標，且真實峰值保持在 -1 dBTP 或更低。 - 您無法聆聽。 請說明您應用了哪些效果以及應用的時間，並提供
sfx studio讓使用者可以透過耳朵調整。如果他們回傳新的數值，工作室會提供他們確切的命令來複製。
電影時刻：什麼讓剪輯吸引人
發布影片聽起來「有電影感」並非因為對人聲應用了濾鏡，而是因為 在正確的瞬間放置了元素：在剪輯點前一個上升音、一段沉默的空白，以及產品出現時伴隨低頻的撞擊音。這些效果在同一個 filtergraph 內合成這些元素（無需授權樣本），並透過 at=<second> 來錨定時間點：
| 時刻 | 效果鏈（剪輯點在 T） |
|---|---|
| 剪輯點上的撞擊，產品展示 | "riser:at=T,length=2.5" "drop-gap:at=T-0.45,gap=0.45" "hit:at=T" |
| 標題或 Logo | "braam:at=T" "sub-drop:at=T,level=-4" |
| 文字或 UI 飛入 | "whoosh:at=T,length=0.8" (在 T 時達到峰值) |
| 淡出至黑幕 | "stop-tail:at=T,decay=3.5" "sub-drop:at=T,level=-4" |
| 強調某個詞 | "throw:at=T,kind=echo" 應用於人聲 |
| 技術故障 | "stutter:at=T,slice=0.12,repeats=4" (會延長音訊) |
at是您正在處理的檔案中剪輯點所處的秒數。對於riser，這表示它結束的位置；對於whoosh，是它達到峰值的位置；對於drop-gap，是空白開始的位置。- 在調整
gain之前，先使用level(dB) 調整音量：hit和sub-drop的預設音量已經很大。 - 精簡且精確：每 15 秒最多一兩個時刻。在每個剪輯點都放一個撞擊會令人疲勞。
trailer-voice（深沉、史詩級的空間人聲）和archival（檔案訪談）是聲音處理效果，沒有at參數。- 需要一個真實的錄製聲音（有重量的撞擊、門聲、玻璃聲、雨聲）而不是合成音嗎？請在
T秒處層疊一個樣本：參見下一節。
作為層的真實樣本
合成的撞擊音快速且免費，但錄製的撞擊、呼嘯或 Foley 音效通常聽起來更真實。layer 效果可在同一個 filtergraph 內，將任何音訊檔案在精確的秒數處混入訊號中：
sfx apply mix.wav mix-door.wav "layer:file=door.wav,at=6,align=onset,level=-3"
sfx apply mix.wav mix-hit.wav "riser:at=6,length=2.5" "drop-gap:at=5.55,gap=0.45" "layer:file=library:ab12cd34ef56,at=6,align=onset" "sub-drop:at=6,level=-4"
align=onset會測量樣本攻擊點的所在位置，並將那個點對齊到at參數。樣本通常以 20–300 毫秒的靜音或前導開始；使用預設的align=start，這段靜音會導致撞擊聲音延遲。對於呼嘯聲和漸強音，請使用align=peak，因為這類聲音的最響亮點需要對齊剪輯點。level以 dB 為單位，length用於僅使用前幾秒，fadeIn/fadeOut用於塑造波形。sync=<s>可以手動設定同步點（與align=start一起使用）。- 樣本可以取代合成的
hit、braam或whoosh；但請保留其周圍的riser、drop-gap和sub-drop。 - 若要處理樣本本身（殘響、距離、喇叭效果），請先用
sfx apply sample.wav sample-fx.wav ...處理它，再層疊處理後的結果。 - 一個經過的物體（汽車、摩托車、無人機）：將孤立的樣本透過
doppler效果渲染，使用at參數設定其最近點，然後以該秒數作為sync進行層疊，使經過的聲音對齊剪輯點：sfx apply car.wav car-pass.wav "doppler:at=2,speed=90"，接著"layer:file=car-pass.wav,at=6,sync=2"。 - 樣本音量差異很大。層疊後，對結果執行
sfx analyze，如果峰值達到 0 dBFS，請降低level。
樣本存放位置
樣本是屬於使用者訂閱的授權音訊。它們存放在 ~/.audiofx/samples 中，每個檔案旁邊有一個 .json 檔案（包含 id、標題、來源、種類、音軌），絕不放在專案資料夾或儲存庫中：
sfx sample add <file-or-url> --title "重型木門關閉聲" --id <library id> --source epidemic-sound
sfx sample list # 每個樣本的 library:<id>、時長以及其攻擊點位置
sample add 會複製本機檔案或下載 URL，測量攻擊點，並輸出 library:<id> 引用，供您在 layer:file=... 中使用。工作室會在其「樣本」標籤頁中顯示這些樣本，且其時刻可以使用一個樣本來取代合成的撞擊或呼嘯聲。
從音效庫擷取（Epidemic Sound MCP）
當使用者已連接 Epidemic Sound MCP（工具為 SearchSoundEffects 和 DownloadSoundEffect）時：
- 優先重複使用。
sfx sample list：如果已存在合適的樣本，請直接使用。 - 搜尋 使用
SearchSoundEffects：一個簡短、具體的詞彙（"cinematic impact low", "whoosh fast short", "glass shatter"），first: 5，以及符合用途的毫秒時長過濾器（撞擊與呼嘯聲小於 4000；環境音可更長）。根據標題、標籤和時長選擇。 - 下載 使用
DownloadSoundEffect(fileType: WAV)。它會回傳一個有時效性的簽名 URL。 - 保留它：
sfx sample add "<assetUrl>" --title "<title>" --id <id> --source epidemic-sound。切勿將簽名 URL 寫入檔案，也切勿將音訊儲存在專案內部。 - 使用它 透過
sample add輸出的library:<id>："layer:file=library:<id>,at=T,align=onset"。
您無法聆聽，所以不要聲稱樣本「聽起來正確」。請報告您可以測量的數據（時長、攻擊點位置、結果的峰值），當選擇很重要時，請加入兩三個候選項目，讓使用者在工作室的「樣本」標籤頁中透過耳朵挑選。如果下載失敗並出現 RETRY_LATER，請等待它指定的秒數再重試。
混合：sfx mix
sfx mix 將人聲、音樂和效果片段放置在一個時間軸上，將音樂在人聲之下閃避，並標準化主輸出，全部在一次 ffmpeg 過程中完成。簡潔形式使用一個標誌對應一個片段，格式為 file@second：
sfx mix final.mp4 --video cut.mp4 --voice [email protected] --music library:<id> --sfx [email protected]
sfx mix final.wav --voice vo.wav --music song.wav --duck 14 --loudness -16
sfx mix --video cut.mp4 --voice [email protected] --music song.wav --print > mix.json
- 當人聲播放時，音樂音量會降低 10 dB (
--duck <dB>,--no-duck)。一個--sfx片段的攻擊點會對齊其指定的秒數，如同align=onset。 - 主輸出會標準化至 -14 LUFS (
--loudness <LUFS|off>)，然後套用 -1 dB 的頂值限制。混合訊號會被測量並以固定增益提升至目標，因此其動態範圍得以保留；當峰值首先碰到頂值限制時，限制器會最多推高 6 dB 來縮小差距，因此一個帶有非常大撞擊聲的混合訊號仍可能低於目標：請使用sfx analyze檢查。影片的 AAC 音訊可能會超過頂值限制約 0.3 dB（"master": { "ceiling": -1.5 }可將其保持在 -1 dBTP）。 - 混合的長度為
--duration，否則為影片的長度，再否則為最後一個片段結束的時間。使用--video和影片輸出時，影像會直接複製，音訊會被替換。 --print會輸出專案 JSON 而不是渲染：編輯它，然後執行sfx mix mix.json final.mp4。
專案檔案可以為每個片段和音軌設定自己的設定。路徑是相對於專案檔案的路徑，且 library:<id> 在檔案路徑可用的任何地方都有效：
{
"version": 1,
"video": "cut.mp4",
"tracks": [
{ "id": "voice", "role": "voice", "clips": [{ "file": "vo.wav", "at": 1.5, "steps": [{ "effect": "voice-clean" }] }] },
{ "id": "music", "role": "music", "clips": [{ "file": "library:<id>", "fadeOut": 2 }], "duck": { "depth": 12, "release": 600 } },
{ "id": "hits", "role": "sfx", "clips": [{ "file": "door.wav", "at": 7.52, "align": "onset", "gain": -3 }] }
],
"master": { "loudness": -14 }
}
- 片段 (Clip)：
file、at（時間軸秒數）、start和length（要使用的檔案部分）、gain(dB)、fadeIn、fadeOut、align(start、onset、peak)、steps。 - 音軌 (Track)：
id、role(voice、music、sfx)、gain、mute、solo、steps、duck(true、false或{ depth, attack, release, threshold }；對音樂預設為開啟)。 - 步驟 (Step)：
{ "effect": "underwater", "params": { "depth": 0.8 }, "from": 4, "to": 9.5, "fade": 0.35 }。片段步驟在片段時間內執行（0 = 片段開始）；音軌步驟在時間軸時間內執行，因此它們的視窗會與影片對齊。 - 主輸出 (Master)：
steps、loudness(null會保留混合後的原始電平)、ceiling(dB, 預設 -1)。
音樂配合影片
目標是將一首歌剪輯至影片的精確長度，並將其高潮點對齊在影片的主要剪輯點上。您無法聽到哪個上升是「那個」高潮點：請測量，用數字提出建議，並讓使用者透過耳朵確認。使用 Epidemic Sound MCP (SearchRecordings、DownloadRecording、EditRecording、PollEditRecordingJob、DownloadRecordingEdit)：
- 測量影片。
sfx cuts cut.mp4會輸出其長度（例如 30.000 秒）及其硬剪輯點。與使用者商定高潮點必須落腳的主要剪輯點C（例如 12.4 秒）。 - 尋找並保留一首歌。
SearchRecordings使用query: { term: "..." }、一個filter(bpm: {min,max}、duration: {min,max}
...
[為翻譯而截斷]