音效庫
834 個檔案 / 63 類別 / 約 1 GB。 單一入口：sfx 指令碼與此 SKILL.md 檔案位於同一目錄。該指令碼會自動判斷自身路徑，因此可從任何位置使用完整路徑呼叫 — 以下範例簡寫為 sfx。
步驟 0 — 檢查資料是否已就緒
儲存庫僅包含程式碼與目錄；音訊檔案位於 data/ 目錄（未提交）。
sfx status
若顯示「Chua co du lieu」，則需取得資料 — 僅需一次，約 1 GB，下載前請告知使用者：
sfx setup
setup 會依照優先順序自動執行，請勿變更順序：
- 優先使用 Google Drive — 下載一個
.zip檔案（約 880 MB，約需 1 分鐘）， 驗證 sha256 後解壓縮。 - 目錄中的 URL 為備用 — 僅在 Drive 失敗時使用（如 404、檔案未公開分享、下載次數限制、sha256 不符）。
此時
setup會自動切換為依catalog/source/*.json中的 URL 逐一下載檔案（依序，約需 18 分鐘），並以catalog/meta.json中的 sha256 驗證。
僅需 python3（≥ 3.8），無需安裝其他套件。若中途中斷，重新執行 sfx setup — 它會繼續下載，不會從頭開始。備用步驟較慢：請在背景執行並告知使用者等待時間。
僅在 使用者要求 時，才直接呼叫 sfx setup --source（跳過 Drive）。
若 setup 顯示「Ca hai nguon deu that bai」，則執行 sfx doctor 並告知使用者 — 請勿自行尋找其他替代音源。
搜尋音效 — 唯一需要記住的指令
sfx find "<關鍵字>"
輸入中文（含標點、不含標點）或英文，都會得到相同的結果 — 比對前會先移除標點，且每個類別都已內建雙語關鍵字。
sfx find "轉場" # 依意圖搜尋
sfx find "提示音" --max-dur 2
sfx find whoosh --group transition
sfx find --group impact --max-dur 1.5
sfx find riser --min-dur 3 --max-dur 5
結果會附帶 持續時間（秒） — 這是在時間軸上配對音效時最重要的資訊。
| 選項 | 使用時機 |
|---|---|
--max-dur N / --min-dur N | 根據時間軸上的空檔限制長度 |
--group <群組> | 瀏覽整個意圖（請見下方群組表格） |
--category <slug> | 已確切知道類別 |
--ext wav | 僅限 wav（或 mp3） |
--paths | 僅輸出路徑，每行一個檔案 — 可直接傳遞給其他指令 |
--json | 機器可讀的輸出，包含 duration、sha256、score |
--abs | 絕對路徑 — 從其他目錄呼叫 sfx 時使用 |
-n N / --all | 結果數量（預設為 20） |
多個詞的查詢預設為 AND；若無任何檔案符合所有詞彙，則自動放寬為 OR 並在 stderr 上明確提示。
若不確定該用什麼 → sfx list 會列出所有類別，並附帶「使用時機」說明與關鍵字。
10 個意圖群組
先選群組，再進行篩選 — 比猜測類別名稱更快。
| 群組 | 用途 | 典型類別 |
|---|---|---|
transition | 連接兩個場景 | fast-whoosh swoosh-swish whip zoom reverse |
impact | 強調重點、顯示數據 | hit boom impacts slam bass |
ui | 文字出現、按鈕點擊、鍵盤打字 | pop click typing ui-mini tick shine |
alert | 通知、提醒 | notification ding bell alarm |
tension | 在高潮前引導情緒 | riser builder braam tension trailer |
ambience | 場景下方的背景音 | ambience environment |
foley | 真實物體音效 | paper doors footsteps liquid draw camera-shutter |
comedy | 搞笑音效 | comedy-cartoon memes |
scifi | 科技、奇幻音效 | technology glitch laser magic data |
horror | 恐怖音效 | horror jumpscare |
選取前先試聽
僅憑 slug 名稱並不足以判斷檔案聽起來如何。 whoosh-fast-05 和 whoosh-fast-06 的質感可能截然不同。
afplay "$(sfx find whoosh --paths --abs -n 1)" # macOS；Linux：ffplay -nodisp -autoexit
若無法播放（例如在無頭模式下執行），則 提供 2–3 個選項及其長度供使用者選擇，請勿自行決定並聲稱其合適。
將音效混入影片
sfx mix video.mp4 -o 有聲影片.mp4 \
2.4:fast-whoosh/whoosh-fast-05.wav \
5.0:ding/[email protected]
每個提示點為 <秒數>:<路徑>[@音量]。路徑相對於 data/sfx/，若檔名不重複也可僅寫檔名。預設音量為 0.6。需要 ffmpeg。
- 影片中原有的音訊會保留並混音在一起，不會被覆蓋 — 在已加入旁白後執行
sfx mix是安全的。 - 使用
amix=normalize=0+alimiter：加入提示點不會降低原始音量，且多個音源重疊時不會破音。 --dry-run會印出 ffmpeg 命令，以便整合到其他腳本中。
從 HTML 製作的影片（使用 Playwright/Puppeteer/Remotion 錄製螢幕）： 網頁中的 <audio> 標籤或 new Audio().play() 僅在瀏覽器中觀看時會發出聲音 — 它 不會 錄製到所產生的 MP4 檔案中。請在 ffmpeg 階段使用 sfx mix 來混入音效，並從動畫時間軸取得時間點。
決定影片聽起來是否專業的三個要素：
- 音效必須比時間軸上的空檔短 — 一開始就使用
--max-dur進行過濾，而不是事後裁剪。 - 將音效對齊動作發生的那一幀，而不是場景的開頭 — whoosh 音效必須在物體開始移動的那一刻響起。
- 不要讓音效覆蓋對話。 若有旁白，請降低音量至
@0.3或使用ui-mini類別。
三個容易犯的錯誤
- 不要提交
data/目錄 — 約 1 GB，已加入 gitignore，透過sfx setup重新取得。 - 不要修改
data/sfx/中的檔案。 這些是原始檔案；若要裁剪或標準化音量，請輸出到其他位置。 - 首次取得資料時，不要直接呼叫
sfx download。 它會下載 834 個分散的檔案，速度慢，而且是備用路徑。請務必呼叫sfx setup，以便優先嘗試 Google Drive。
若懷疑有問題，請執行 sfx doctor（檢查工具與資料來源）、sfx verify --hash（重新計算每個檔案的 sha256）。
如需維護此資料庫（新增類別、重新打包、更改 Drive 連結），請參閱 README.md。