サウンドエフェクトライブラリ
834ファイル / 63カテゴリ / 約1GB。 唯一のエントリポイント: スクリプト sfx はこのSKILL.mdファイルと同じディレクトリにあります。スクリプトは自身のパスを自動的に特定するため、フルパス指定でどこからでも実行できます。以下の例では簡略化して sfx と記述しています。
ステップ0 — データがすでにあるか確認
リポジトリにはコードとカタログのみ含まれています。音声ファイルは data/ にあります（コミットされていません）。
sfx status
「Chua co du lieu（データがありません）」と表示されたらデータを取得します — 一度だけ、約1GB、ダウンロード前にユーザーに通知してください:
sfx setup
setup は以下の優先順位に従って自動的に実行されます。順序を入れ替えないでください:
- まずGoogle Drive — 1つの
.zipファイル（約880MB、約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を検索 — 覚えるべき唯一のコマンド
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
結果には 長さ（秒） が表示されます — タイムラインにSFXを合わせる際に最も重要な情報です。
| フラグ | 使用場面 |
|---|---|
--max-dur N / --min-dur N | タイムラインの空き時間に合わせて長さを制限 |
--group <グループ> | 意図全体をブラウズ（下記のグループ表を参照） |
--category <スラッグ> | カテゴリが正確にわかっている場合 |
--ext wav | wav（またはmp3）のみ取得 |
--paths | パスのみを1行1ファイルで出力 — 他のコマンドに直接渡す |
--json | 機械可読な出力、duration、sha256、score を含む |
--abs | 絶対パス — 別のディレクトリから sfx を呼び出す際に使用 |
-n N / --all | 結果の数（デフォルト20） |
複数ワードのクエリはデフォルトで AND 検索です。全ワードに一致するファイルがない場合は自動的に OR に緩和され、その旨がstderrに明示されます。
何を使えばよいかわからない場合 → sfx list ですべてのカテゴリとその「使用場面」、キーワードを表示します。
意図に基づく10のグループ
最初にグループを選択し、その後でフィルタリングします — カテゴリ名を推測するより高速です。
| グループ | 使用場面 | 代表的なカテゴリ |
|---|---|---|
transition | 2つのシーンを接続 | 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 |
選択前に試聴
スラッグ名 だけでは ファイルの実際の音を推測するのに不十分です。whoosh-fast-05 と whoosh-fast-06 ではニュアンスがまったく異なる場合があります。
afplay "$(sfx find whoosh --paths --abs -n 1)" # macOS; Linux: ffplay -nodisp -autoexit
試聴できない（ヘッドレス環境で実行中）場合は、長さ情報を含む2〜3の選択肢をユーザーに提示し、選択を仰いでください。自分で決定して「これが合う」と断言しないでください。
SFXを動画に合成
sfx mix video.mp4 -o with-sound.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ファイルには含まれません。アニメーションのタイムラインからタイムコードを取得し、sfx mix でffmpegステップにSFXを合成してください。
動画の音声をプロフェッショナルにする3つのポイント:
- SFXはタイムラインの空き時間より短くすること — 後でカットする代わりに、最初から
--max-durでフィルタリングします。 - SFXはシーンの先頭ではなく、動きが発生するフレームに正確に配置すること — whooshはオブジェクトが動き始める瞬間になければなりません。
- SFXをナレーションと重ねないこと。 ナレーションがある場合は
@0.3に音量を下げるか、ui-miniカテゴリを使用します。
よくある3つの間違い
data/をコミットしないでください — 約1GBで、gitignoreされています。sfx setupで再取得します。data/sfx/内のファイルを編集しないでください。 それらはオリジナルです。カットや音量の正規化が必要な場合は、別の場所に出力してください。- 初回データ取得に直接
sfx downloadを呼び出さないでください。 834ファイルを個別にダウンロードするため低速で、フォールバック用です。常にsfx setupを呼び出し、Google Driveが優先的に試行されるようにしてください。
問題が疑われる場合の確認: sfx doctor（ツールとデータソースの確認）、sfx verify --hash（各ファイルのsha256を再計算）。
ライブラリのメンテナンス（カテゴリ追加、再パッケージ化、Driveリンクの変更）: README.md を参照してください。