procedural-sfx

プロシージャル効果音

ノイズ、サイン波、フィルター、エンベロープから効果音を作り、それぞれが発生する正確なフレームに配置します。サードパーティーのサンプルライセンスが不要で、毎回同じようにレンダリングされ、映像と自動的に同期するサウンドを作れます。

この方法は、アニメーション、解説動画、UI、モーショングラフィックス、ゲームのプロトタイプなど、スタイライズされた作品に最適です。フォトリアルな映画のフォーリー（特定の実銃の音や、本物の砂利の上を歩く足音など）には、録音したサンプルのほうが適しています。ミキサーは音声ファイルも受け付けるため（"type": "file"）、組み合わせて使うこともできます。

セットアップ

pip install -r scripts/requirements.txt   # numpy, scipy, soundfile
python scripts/check_env.py               # verifies them; ffmpeg >= 4.2 is optional (only for master.sh / mux.sh)

すべてのスクリプトは scripts/ にあり、どこからでも実行できます。以下のパスは、このスキルのディレクトリからの相対パスです。エラーがあると、スクリプトは error: … と fix: … の行を出力して終了コード 1 で終了します。修正行の指示に従って、再実行してください。

ワークフロー

1. 必要なサウンドを見つけます。 サウンドが必要な瞬間をすべて列挙します。時間、何が起きるか、どの素材が関係するか（プラスチック、木、金属、空気、電気）を記録します。レシピを決めるのは動作の名前ではなく素材です。「コインが落ちる音」と「鍵が落ちる音」は、どちらも小さな金属の衝撃音です。無音の箇所も計画しましょう。大きな衝撃音の前に少し静寂を挟むと、音量を上げるよりも強く響きます。

2. サウンドを選ぶか、設計します。 python scripts/render_sfx.py --list を実行して、組み込みレシピを確認します。合うものがあれば、引数を指定してレンダリングし、試聴します。合うものがなければ、assets/recipe_template.py をもとに、プロジェクトファイルに新しいレシピを書きます。

   • 新しいレシピを書く前に、references/design-method.md を読んでください。アタック、ボディ、テールを重ねる方法と、どの数値を変えると聞こえ方がどう変わるかを説明しています。
   • references/recipes.md を読んで、各組み込みレシピの内容とパラメーター、銃の種類、表面、距離などのバリエーションを確認してください。

3. 各サウンドを数値で確認します。 出力を聴くことはできないため、測定してください。python scripts/analyze.py sound.wav --bands を実行します。アタック、残響時間、スペクトル重心、帯域バランスを、サウンドに期待される特性と比較してください。references/design-method.md に大まかな目標値があります。繰り返し使うサウンドについては、render_sfx.py <recipe> --variants 4 を実行すると、テイクごとの測定値が表示され、同一またはほとんど違いのないテイクにフラグが付きます。

4. イベントリストを書きます。 events.json には、時間、種類、引数、ゲイン、パンを含むサウンドごとのエントリーを記述します。assets/events.example.json は実行可能なサンプルです。音声セリフや録音音声は、"type": "file" イベントとして追加します。時間を再入力するのではなく、アニメーションを駆動する定数と同じものから取得してください。スキーマ、さまざまなアニメーションスタックからの書き出し方法、衝撃音より前に始まるウーシュ音などの予告オフセットについては、references/event-sync.md を参照してください。

5. ミックスします。 python scripts/mix.py events.json -o mix.wav [--recipes my_recipes.py] [--music score.wav] [--bed rumble] [--stems stems/] [--audition audition/] を実行します。イベントファイル全体の検証後、バスごとのレベル、より大きな音に埋もれているイベントを示すマスキングレポート、リミッター適用前後の真のピーク（上限 −1 dBTP）が出力されます。CHECK の行はすべて調査し、修正するか、理由を把握したうえでそのまま受け入れてください。ゲインステージング、ダッキング、マスキングの解消方法については、references/mixing.md を参照してください。

6. 納品用にマスタリングします。 どちらのスクリプトもミックスを測定し、ラウドネス目標（ウェブ／ソーシャル向けは−14 LUFS、その他は references/mixing.md §5）に達するように線形ゲインを1回だけ適用し、再測定した結果を出力します。コンプレッションは行いません。目標に達するためにトゥルーピークが上限を超える場合は処理を停止し、到達可能な最大の目標値を示します。

   • 動画がある場合：sh scripts/mux.sh video.mp4 mix.wav out.mp4 [LUFS=-14] [dBTP=-1]。ミックスは動画の元の音声を置き換えます。動画に残す必要のある音楽やセリフがすでに含まれている場合は、抽出して（ffmpeg -i video.mp4 -vn -c:a pcm_s24le original.wav）、多重化する前に mix.py --music original.wav に渡してください。mux.sh は動画に音声がある場合に警告を表示します。動画のすべてのフレームを保持し、マスタリングの前にミックスを動画の長さに合わせます（"dur" を動画の長さに設定すれば、長さを合わせる必要はありません）。出力形式は .mp4、.m4v、.mov、または .mkv です。
   • 音声のみの場合：sh scripts/master.sh mix.wav final.wav [LUFS=-14] [dBTP=-1]。

7. 試聴用に引き渡します。 数値で問題のある音は検出できますが、不快な音は検出できません。ミックスレポートの最後には、「まだ耳で調整されていない」テーブルがあり、レシピのステータスが starting point または new の配置済みサウンドが、レシピと引数セットごとに1行ずつ記載されています。--audition DIR を指定して mix.py を実行すると、該当する各サウンドを個別にレンダリングし（ミックスと同じ引数とテイクを使用）、ファイル列に値を入力します。イベントに "name"（「怒った猫」など）を指定すると、サウンド列にも値が入力されます。そのテーブルをそのまま引き渡し資料に貼り付けてください。項目は、サウンド · レシピ · 引数 · ステータス · 時刻 · 試聴ファイルです。ユーザーには、tuned 以外のすべての行を聴くよう依頼してください。問題がある場合は、references/troubleshooting.md で「細すぎる」「最後にクリック音がする」「ロボットのような音がする」といった指摘に対応する修正方法を確認できます。また、最終的なQAチェックリストも記載されています。

スクリプト

スクリプト	用途
scripts/sfxkit.py	ライブラリ：ノイズ、エンベロープ、フィルター、スイープ、サチュレーション、エコー、ラジオ効果、トゥルーピークメーターとリミッター、サウンド配置用の add()、WAV入出力
scripts/recipes.py	組み込みレシピ18種類と、プロジェクトのレシピファイルを統合する load()
scripts/render_sfx.py	1つのレシピ、バリエーション、または全レシピを試聴用のWAVにレンダリング
scripts/analyze.py	ファイルごとの指標：ピーク、RMS、アタック、リングタイム、スペクトル重心、帯域エネルギー
scripts/mix.py	events.json → バス、ダッキング、リミッター、ステム、マスキングレポートを含むステレオミックス
scripts/master.sh	音声のみの納品：測定、LUFS目標値への線形ゲイン適用1回、トゥルーピーク確認（ffmpeg）
scripts/mux.sh	master.sh の実行後、動画の下にAACとして多重化（ffmpeg）
scripts/check_env.py	依存関係を確認

組み込みレシピ

インパクト：click、clack、crash、thump、step（hard／wood／soft）、creak · 動き：whoosh · UI：ding、pop、beep · 武器とSF：gunshot（pistol／rifle／shotgun）、burst、explosion、laser · アンビエンスとドラマ：rumble、ignite、roar、heartbeat。各レシピにはステータスがあり、render_sfx.py --list で確認できます。tuned は完成作品で耳による調整済み、starting point は測定済みですが耳による調整は未実施です（該当するのは gunshot、burst、explosion、laser、および木や柔らかい地面の step）。独自の --recipes ファイルから読み込んだレシピは new です。詳細は references/recipes.md を参照してください。

原則

• 1つのレシピにつき、正規化されたサウンドを1つ作成し、ゲインはイベントリストで設定します。 レシピの最後は norm(x) * v で、音量は events.json の gain でのみ設定します。これにより、ミックスは1つのテーブルを編集するだけで調整できます。
• ランダム性を使うのは noise()、rand()、uniform() を通じてのみです。 mix.py は各イベントに対し、そのタイプ、時刻、引数からシードを設定します。そのため、イベントを追加してもほかのイベントの音には影響せず、すべてのレンダリング結果はバイト単位で同一になります。
• 繰り返すサウンドに変化をつけます。 同じ音をそのまま繰り返すと（足音、銃撃音、タイピングなど）、不自然に聞こえます。ピッチを±5～10％、音量を±20％の範囲でランダム化し、パンも少し変化させます。
• タイミングは耳ではなく、アニメーションに合わせます。 同期がずれている場合、ほとんどの場合、修正するのはミックス内の位置ではなく、イベント時刻の生成方法です。