openverse-sfx

openverse-sfx：測定によって検証された、動画向けのライセンスフリーなサウンドデザイン

音を聴くことはできません。このスキルでの判断はすべて、測定（librosa、ffmpeg ebur128、波形プロット）に基づき、書き出したファイルで検証します。感覚に頼ることは決してなく、ユーザーに「良い音です」と伝えることも決してありません。代わりに、ヘッドフォンで確認してもらうため、チェックすべきタイムスタンプを短くリストにして渡してください。

音声はすべてOpenverse（https://api.openverse.org）から取得します。無料の音声ファイルは520万件あり、APIキーは不要で、費用もかかりません。コードで音楽や効果音を合成してはいけません。正弦波のビープ音やノイズバーストも禁止です。実際のライセンス付き録音のみを使用してください。

---

重要なルール

1. ライセンスフィルターは必須です。 license=cc0,by,pdm かつ source=freesound,jamendo のOpenverse検索結果のみを使用してください。scripts/sfx_search.py がこれを強制します。回避してはいけません。
2. 音の種類ごとに検索は1回だけです。 Openverseを匿名で利用する場合、検索回数は1日あたり約200回に制限されています。音の種類ごとに（"whoosh"、"ui pop"、"upbeat loop"）1回検索し、候補リストから選んでください。言い換えたクエリで再検索してはいけません。
3. credits.txt は必須です。 CC BYの音声を合法的に使用するには、クレジット表記が必要です。ダウンロードしたすべてのファイルの attribution フィールドを、そのまま credits.txt に記載してください。scripts/sfx_fetch.py が自動で処理します。CC0/PDMにはクレジット表記は不要ですが、記録は残してください。
4. まず前提条件を整えてください。 不足している場合は、作業を始める前に ffmpeg と pip install librosa matplotlib numpy scipy をインストールしてください。
5. 書き出し前のWAVではなく、書き出したMP4を測定してください。 AAC圧縮とモノラルのスマートフォン再生によって結果は変わります。納品するファイルだけが評価対象です。

---

ワークフロー

ステップ1 - 音楽

ユーザーから提供された曲を使うか、Openverseで検索します（python3 scripts/sfx_search.py --query "upbeat loop" --min-ms 15000）。ソースとライセンスを記録してください。scripts/sfx_fetch.py を使って sfx/ にダウンロードし、クレジット情報が credits.txt に記載されるようにしてください。

ステップ2 - ビートグリッド

python3 scripts/beat_grid.py sfx/<music_file> を実行します。キックドラムが鳴るサブ120 Hzの波形を検出したビートグリッドと照らしてプロットし、ビートからのずれを数値で検出して、beats.json を書き出します。beatgrid.png を開き、赤い線がキックのスパイクにぴったり重なっていることを確認してください。重なっていない場合は、グリッド全体を半ビート間隔分ずらしてください（スクリプトはこれを数値で確認し、半ビートずらしたほうが一致度が5％を超えて高い場合は自動でずらします）。

ステップ3 - 大きな動きをビートに合わせる

シーンの切り替え、タイトルの表示、大きなアニメーションは、beats.json のビートに合わせて配置してください。アニメーションを変更できる場合は、カットを最も近いビートに合わせます。変更できない場合は、音楽入力の -itsoffset / adelay を使って音楽の開始位置をずらし、既存のカットがビートに合うようにしてください。

ステップ4 - カットや大きな動きごとに、既成の効果音を1つ使う

プロジェクトに既存のサウンドライブラリがあれば、まずそれを使いましょう。必要な音がない場合はユーザーに確認してください。それ以外の場合は、音の種類ごとに sfx_search.py を1回実行します。動きには風切り音、何かが表示されるときにはポップ音、クリックにはクリック音、タイピングにはタイピング音を使ってください。候補リストから各ショットの動作に最も合うものを選び、sfx_fetch.py でダウンロードしてください。

ステップ 5 - 適切な階層でミックスする

• ナレーションを最も大きなレイヤーにします。誰かが話している間は音楽の音量を下げます（サイドチェインダッキング、または手動の音量オートメーション）。
• 効果音は音楽より上に配置します。素材ファイルごとに音量が大きく異なるため、固定の音量倍率ではなく、測定に基づいて各レイヤーを正規化します。
  • 効果音のワンショットは、scripts/sfx_normalize.py を使ってピーク正規化し、-3 dBTP にします（ワンショットはトランジェントによって際立つため、LUFS ではなくピークを使います。また、短い効果音に ffmpeg loudnorm を絶対に実行しないでください。3 秒のバッファによって短いファイルが破損します）。
  • 音楽ベッドは -20 LUFS に正規化します。
  • 正確なコマンドは references/ffmpeg_recipes.md にあります。
• 納品する MP4 は 統合ラウドネス -16 LUFS、トゥルーピーク -4 dBFS 未満を目標にします。これにより、AAC 圧縮後やスマートフォンのモノラルスピーカーでクリッピングが発生しません。マスターは TP=-4.5 にします。AAC エンコードでは約 0.3～0.6 dB のオーバーシュートが加わるため、-4.0 でマスターすると、mux 後のファイルがゲートに不合格になります。
• ダッキング、拍のタイミングに合わせた効果音の配置、2 パスの loudnorm に使う正確な ffmpeg コマンドは references/ffmpeg_recipes.md を参照してください。

ステップ 6 - 書き出しを検証し、確認用のチェックポイントを渡す

すべてのキュー時刻を指定して python3 scripts/verify_mix.py final.mp4 --cue <t1> --cue <t2> ... を実行します。このスクリプトは、ebur128 を使って書き出した MP4 を測定し、MP4 から各キューの前後のフレームを取得して、キュー位置の線を重ねた書き出し済みの波形をプロットします。ラウドネスとピークが基準を満たしていること、各キューが波形のスパイクに一致し、フレームにカットやタイトルが表示されることを確認します。その後、ユーザーにヘッドフォンで確認する 5 つのタイムスタンプと credits.txt のパスを伝えます。音が良いとは断言しないでください。

---

スクリプト

スクリプト	目的
scripts/sfx_search.py	Openverse 検索、ライセンス／ソースのフィルターを適用（freesound,jamendo の cc0,by,pdm）、再生時間のフィルタリング、クレジット情報フィールド付きの JSON 候補リスト
scripts/sfx_fetch.py	Python 標準ライブラリ（urllib.request）を使って選択したファイルを sfx/ にダウンロードし、その帰属表示を原文のまま credits.txt に追記
scripts/sfx_normalize.py	ebur128 で測定し、ゲインを調整して再測定。効果音のワンショットにはピークモード（-3 dBTP）、ベッドには LUFS モードを使用します。loudnorm によって短いファイルが破損する場合でも安全です
scripts/beat_grid.py	librosa によるビートトラッキング、拍のずれを数値で確認するロックチェック、120 Hz 未満のキック帯域／グリッドのプロット（beatgrid.png）、beats.json
scripts/verify_mix.py	書き出した MP4 の ebur128 ラウドネスとトゥルーピーク、キュー前後のフレーム取得、波形プロット（verify/waveform.png）、PASS ／ NEEDS FIX の判定

参考資料

• references/ffmpeg_recipes.md - 音楽の拍をずらす、キュー時刻に効果音を配置する、ナレーションのサイドチェインダッキング、-16 LUFS ／ -4 dBTP にする 2 パスの loudnorm に使う正確な ffmpeg コマンド。ffmpeg コマンドを書く前に必ず読んでください。