scenario-godot-audio

Godot オーディオ（オーディオ実装者）

対象：Godot 4.7.2.stable、macOS Apple Silicon。

エキスパートレベルでは、ミックスはデータとして設計し、その後に測定します。バスレイアウト、音楽のトランジション、ボイス数の上限は仕様として記述します。エージェントは音を聴けないため、ミキサーから読み取った数値で、すべての主張を検証します。エキスパートは、音を鳴らすことよりも、どの音を鳴らさないかの判断に多くの時間を費やします。これが戦闘オーディオの核心です。ここに記載されている兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業を進める場合は、ツールスキーマを参考にし、不足している点を明記してください。

必須の事前知識： scenario-godot-expert（チャンネル、gd_run、レビューループ、4.7 の落とし穴）。

ステータス（2026-10-02）： Godot 4.7.2 で、12 のテストグループにおける実行中のジョブ 18 件、2 回目のチェック（P15）、オフラインテスト 13 件がすべて合格しています（references/procedures.md、tests/code/godot-audio/）。

スタンス（専門家による補足）

1. ヘッドレスで測定し、「音が出ない」という警告をうのみにしないでください。 バージョン差分によると、--headless では Dummy ドライバーが使われ、音は出ません。これはスピーカーについてのみ当てはまります。4.7.2 では、Dummy ドライバーでも 44.1 kHz でリアルタイムにミキシングされます。ピークメーター、AudioEffectCapture、AudioEffectRecord はすべて動作し、-24.08 dBFS のファイルは -24.07 と読み取られます（実測）。タイミングを測る場合は、AudioStreamPlayback.mix_audio()（audio_meter.render_stream）を使ってオフラインでレンダリングしてください。サンプル単位で正確です。リアルタイム録音は約 0.2 秒遅れて始まります（実測）。
2. 優れた戦闘音声を実現するには、音を再生しないことが大切です。 Somberg：「音声技術の多くは、音を再生しないことに関するものです」（Vjm-- 00:05:20）。サウンドの種類ごとに上限を設け、一定の範囲内での再生数を約 2 回に抑え、ボイスを割り当てる前に距離でカリングしてください。敵 200 体が 10 Hz で射撃する条件で測定したところ、単純なミックスはリミッター前にピークが +32.4 dBFS に達しましたが、上限を設けた 32 ボイスのプールでは +8.5 に収まりました（P6）。
3. 同時に再生を開始しないよう注意してください。 クールダウンなしで厳密な上限を設けると、12 ボイスすべてが同じティックで開始し、同時に終了します。その結果、ミックスは波形シート（P6）のように断続的に大きくなります。サウンドの種類ごとに 25 ms のクールダウンを設け、4 種類のランダムなテイクを使うと再生タイミングが分散し、ピークは -13.9 dBFS まで下がります［追加、実測］。
4. 音楽をトランジションテーブルとして作成し、到達可能なペアをすべて監査してください。 Octodemy はマトリックスをセルごとに作成します（spBa 00:03:59）。Bittmann は、すべての状態変化を設計することを求めています（dPXa 00:18:07）。一覧にないペアは、ハードカットにはなりません。4.7.2 では次の拍まで待ってから、ソースを約 1 拍かけてフェードアウトします（実測、P9）。music_builder.audit_interactive を使うと、不足しているペアを一覧表示できます。
5. 戻りたいクリップを離れるトランジションに hold を設定してください。 ドキュメントと Octodemy は、「hold previous」と hold への復帰について説明しています（spBa 00:07:49）。4.7.2 では、割り込まれたクリップを離れる、先行するトランジションに hold を設定した場合にのみ復帰します。スタンガーへのトランジションに hold を設定した場合、6 種類すべてでスタンガーの後に無音になりました（実測、P9）。
6. すべての音声を名前付きバス経由でルーティングし、名前で参照してください。 まず Music バスと SFX バスを作成してください（DevWorm 07Ky、Game Dev Artisan h3_1）。バス名を変更すると、プレイヤーは "Master" と読み戻して、そこから再生します。名前を元に戻すと復旧します（実測）。シーンを監査し、Master または存在しないバスを使っているプレイヤーがないか確認してください（P13）。
7. 実際のカーブを使って空間オーディオを測定してください。 4.7.2 のデフォルト設定（unit_size 10、max_db +3）では、3D ソースは 1 m から 7 m まで音量が一定で、10 m で 3 dB、80 m で 21 dB 下がります。ローパスフィルターを使うと、20 m で 8 kHz がさらに 22 dB 下がります。area_mask のデフォルト値は 0 なので、1 に設定するまで Area3D のリバーブオーバーライドは機能しません（P7）。
8. 生成した音声はインポート前に調整し、読み込んだリソース上で確認してください。 AI の MP3 は音量が大きく、無音のパディングも含まれています（テストファイル 1 件では -8.4 LUFS、ピーク +0.99 dB）。長いファイルは 2 パスの loudnorm でノーマライズしてください。短いワンショットはピークでレベル調整してください。0.5 秒のヒット音では loudnorm が目標値から 3 LU 外れました（実測）。

最初に確認する項目

入力項目	計画への影響	未指定の場合のデフォルト
プラットフォーム（デスクトップ、モバイル、Web）	Webはデフォルトでサンプルモードで再生され（default_playback_type.web = 1）、バスエフェクトをバイパスします（ドキュメント）	デスクトップ
2Dまたは3D、リスナー	AudioStreamPlayer2Dまたは3D、単位サイズ、最大距離	3D、Camera3Dリスナー
同時再生ソースのピーク数	プールサイズ、上限	敵200体、ボイス32個
音楽のスタイル（リズミカル、アンビエント）	小節またはビートでの切り替えと即時切り替えの違い、BPMインポート	リズミカル、4/4
アセットのソース	コンディショニング：AI（scenario-audio、scenario-elevenlabs）またはサウンドデザイナー	AIファイル、コンディショニング済み
ミドルウェア（FMOD、Wwise）	ネイティブノードとプラグインバンクのどちらを使うか	Godotネイティブ
ラウドネス目標	種類ごとのLUFS	SFX、ボイス、音楽は-18 LUFS、アンビエンスは-24 LUFS［追加］

ワークフロー

1. バスをデータとして扱う（P1、P2）。 audio_buses.COMBAT_LAYOUT から build_layout でレイアウトを構築し、audio/buses/default_bus_layout で指定されたファイルに保存して、新しいプロセスで再読み込みします。GATE：audit_layout がフラグを返さず、再読み込み後に HardLimiter が Master 上にあることを確認します。スライダーを 0.5 にすると -6.02 dB に設定され、出力が 6.02 dB 下がります。
2. インポート設定（P3）。 gd_audio.set_import_params で .import のキーを編集し、gd_run.import_project を実行してから、読み込まれたリソースを読み取ります。GATE：読み込まれたストリームで音楽の loop、bpm、beat_count が設定され、gd_audio.audit_imports がフラグを返さないことを確認します。
3. 生成アセット（P4）。 prepare_ai_audio(src, dst, kind) で無音をトリミングし、ファイルの音量を調整し、SFX をモノラル WAV に変換します。bars_for(seconds, bpm) で beat_count を取得します。GATE：種類ごとのラウドネスのばらつきが 1 LU 未満であること、冒頭に無音がないこと、audio_meter.loop_seam(stream) によるループの継ぎ目のラグが 0 サンプルであることを確認します。
4. SFX のバリエーション（P5）。 AudioStreamRandomizer を使用し、3 つ以上のテイク、半音単位のピッチ、音量オフセットを設定します。GATE：24 回の再生で繰り返しがなく、すべてのテイクが使われ、測定したピッチが設定範囲内であることを確認します。
5. ボイス（P6）。 種類ごとの limit、radius_m、radius_limit、cooldown_ms、max_distance_m と優先度に基づく割り当て解除に対応した SfxPool を使用します。GATE：敵 200 体の一斉発生時に、再生中のボイスが上限以内に収まり、ノード数が増加せず、リミッター前のピークが 0 dBFS 未満であることを確認します。その後、波形シートを開いて確認します。
6. 空間（P7、P8、P15）。 まずリスナーです。現在の Camera3D または AudioListener3D がない 3D では、すべての 3D プレイヤーが無音（-200 dB）になります。AudioListener3D.make_current() はカメラより優先されます（40 m 移動させると、-12.1 から -29.8 dB になり、左右が入れ替わります）。リスナーのない 2D ではビューポートの中央で音が聞こえます。プレイヤーに AudioListener2D を配置します（DevWorm 07Ky 00:33:25、First Pancake 1PDU 00:04:05）。次に unit_size、max_distance、ルームバス用の area_mask = 1、オクルージョンを設定します（ショットには再生時にレイを 1 本、長時間鳴らすエミッターには Occluder3D を使用）。GATE：現在のリスナーが 1 つだけであること、すべての位置指定プレイヤーが名前付きの非 Master バスを使用していること（audio_audit.scan）、距離ごとの測定レベルと左右のバランス、および遮蔽時に 8 kHz が 12 dB 以上低下することを確認します。
7. 音楽（P9）。 music_builder.build_interactive(spec) でインタラクティブストリームを構築して監査し、.tres として保存します。レイヤーには AudioStreamSynchronized のステムを使用します。GATE：トーンを追跡したオフラインレンダーで、各切り替えがその小節または拍で行われ、スティンガーの再生後に保持中のクリップに戻ることを確認します。
8. ゲーム状態に連動したミックス状態（P2、P15）。 Just Cause 4 では、戦闘中の敵が 5 体を超えると環境音をミュートし、約 1 秒で戦闘用ミックスに移行します（uN8R 00:19:07 から 00:21:12）。状態はオーディオではなく、ゲームの状態に応じた関数として記述します：

   static func combat_mix(engaged: int) -> Dictionary:
   	if engaged == 0: return {"Ambience": -6.0, "Music": -8.0}
   	if engaged <= 5: return {"Ambience": -12.0, "Music": -6.0}
   	return {"Ambience": -80.0, "Music": -4.0}
   # on change: audio_buses.apply_state(self, combat_mix(n), 1.0)
   

   GATE：戦闘中の敵が 0、3、8 体の場合に、各バスがフェード時間内（0.25 秒時点で正確に測定）に目標値に達することを確認します。無音にするために手動でバスを切り替えないでください。Godot は無音のバスを数秒後に自動で無効化します（オーディオバスのドキュメント）。
9. ミックスをレンダリングする（P12）。 Movie Maker を --write-movie x.avi --fixed-fps 60（ウィンドウ表示、160x90）で実行し、続けて gd_audio.movie_audio を実行します。GATE：出力が 48 kHz であること、シードを指定した 2 つのレンダーの MD5 が一致すること、統合ラウドネスが目標範囲内であること、トゥルーピークが -1 dBTP 未満であること、スペクトログラムを開いて確認することを確認します。

数値

値	測定値または出典	比較対象
3Dレベル、平坦な領域	0 dBで1～7 m、10 mで-3 dB、20 mで-8.9 dB、40 mで-14.8 dB、80 mで-20.7 dB（500 Hz）	逆モデル、unit_size 10、max_db +3
距離によるローパス	10 mではなし、20 mでは8 kHzがさらに-22 dB、40 mでは-29 dB	デフォルトは5000 Hz、filter_db -24、filter_db 0で無効化
パン、右に5 m	L -16.0 / R -10.0 dB	panning_strength 1.0、project 3d 0.5倍
リニアスライダー	0.5は-6.02 dB、0.05未満でミュート	Game Dev Artisan（h3_1 00:09:23）
プール	32ボイス、プレイヤーのリング	Michael Games（H-6p 00:09:44）
半径のルール	半径ごとに約2回再生する	Somberg（00:05:52）、Murchの「2.5の法則」
リミッター前の戦闘ピーク	単純方式 +32.4、プール方式 +8.5、調整後 -13.9 dBFS	敵200体、10 Hz、2秒（P6）
遮蔽	1 kHzローパスを通すと8 kHzが-58 dB、Occluder3Dでは約0.5秒で20 kHzから800 Hzに低下	P8
ラウドネス目標	-18 LUFS（効果音、音声、音楽）、-24 LUFS（環境音）、true peak -1 dBTP	［追加］開始時の目安
短いサウンドのしきい値	3秒未満の場合、ピークレベルを-3 dBFSにする	0.5秒ではloudnormが3 LUずれた（P4）
マスター	0 dBを超えないこと、-60～0 dBの範囲で作業する	オーディオバスのドキュメント

品質ゲート

• 測定可能： audit_layout が問題なく、audit_interactive に到達可能なペアの欠落がなく、audit_imports が問題なく、audio_audit.scan が問題ないこと（Master上にプレイヤーがなく、ストリームの欠落がなく、Areaがバスを上書きする箇所で area_mask が設定されていること）。ストレスバーストでは、リミッター前のピークが0 dBFS未満で、ライブボイス数が上限以下であり、ノード数が安定していること。ファイルごとの analyze() では、ラウドネスが目標の1 LU以内、true peakが-1 dBTP以下、ワンショットの lead_silence_s が0.01未満であること。ループの継ぎ目の遅延は0であること。ジェネレーターの get_skips() は0であること。
• 視覚： 単純方式、プール方式、調整後のストレスレンダーの波形コンタクトシートと、Movie Makerミックスのスペクトログラムを用意します。開いて、クリッピングの壁、周期的なバースト、切り替えの欠落を確認します。
• 耳で確認（ユーザー）： トランジションの音楽性、繰り返しの印象、リバーブの自然さを確認します。確認できたことを述べてください。確認していないことを主張してはいけません。

よくある間違い

間違い	発生する現象	対処方法
敵ごとに AudioStreamPlayer3D を 1 つ配置し、射撃のたびに再生する	+32 dBFS の壁、リミッターのポンピング、同時に 200 音声	上限、距離ルール、クールダウンを設定した SfxPool
クールダウンなしで上限を設定する	各クリップの長さに合わせてミックス音量が脈打つ	cooldown_ms を 25 以上にする。Randomizer でテイクを選択する
Area3D のリバーブゾーンが機能しない	ルームバスの音量が -200 dB になる	プレイヤーで area_mask = 1 を設定する（4.7 のデフォルトは 0）
レイアウトでバスの名前を変更する	プレイヤーに Master と表示され、スライダーが無視される	名前を変更しない。audio_audit.scan を実行する
スティンガーへの遷移に Hold を設定する	スティンガーの後、音楽が無音になる	保持されたクリップから出る遷移に Hold を設定する
.import のテキストを信頼する	ゲーム内ではループがオフのまま	読み込まれたストリームの loop と bpm を確認する
0.5 秒のヒット音に loudnorm を適用する	-18 ではなく -21 LUFS になる	短いサウンドにはピークレベルを使用する（prepare_ai_audio）
音楽を WAV、SFX をステレオにする	ビルドサイズが大きくなり、モノラルへのダウンミックスが無駄になる	audit_imports：音楽には Ogg または MP3、SFX にはモノラルを使用する
ループするオーディオで finished を待機する	コードがハングする	ループする 0.2 秒のクリップでは 1 秒間に finished が 0 回発火し、ループなしでは 1 回発火します（ドキュメント、P15）
3D に現在のリスナーがいない	すべての 3D サウンドが無音になり、エラーも出ない	現在の Camera3D または AudioListener3D を設定する（P15）
random_pitch と random_pitch_semitones の両方を設定する	2 つ目の設定が 1 つ目を警告なしに上書きする	プロパティは 1 つだけ使用する。2 半音は random_pitch 1.1225。すべての変化量のデフォルトは 0（ドキュメント、P15）
== を使って足音のタイマーをテストする	足音がまったく鳴らない：10 秒間で 0 回	timer <= 0.0 の後に timer += interval とする：28 回の足音（FinePointCGI 7kD7 00:38:17、P15）
Master に AudioEffectLimiter を設定する	非推奨の警告が出る	AudioEffectHardLimiter を使用し、上限を -1 dB にする
Web でバスエフェクトを使用する	ブラウザーでリバーブやフィルターが機能しない	これらのプレイヤーでは再生タイプに Stream を使用する（ドキュメント）
ffmpeg のネイティブ vorbis エンコーダーで Ogg を作成する	ループのつなぎ目が 32 サンプル遅れる（ファイル長 8.0007 秒）	libvorbis またはギャップレスヘッダー付き MP3 を使用する。audio_meter.loop_seam を確認する

引き継ぎ

• 受け取るもの： scenario-audio と scenario-elevenlabs から、プロンプト、BPM、再生時間が指定された MP3/WAV （prepare_ai_audio、続いて P3 を経由）；scenario-godot-gameplay からイベント、位置、交戦中の敵の数；scenario-godot-architecture からオートロードの配置；scenario-godot-ui からスライダーノード。
• 引き渡すもの： バス名と save_volumes／load_volumes を scenario-godot-ui に；int ID を返す play(type, pos) API を scenario-godot-gameplay に；プール統計と Web の Sample モード一覧を scenario-godot-performance-export に；ライブテストファイルを scenario-godot-pipeline-automation に。
• パケット： プロジェクトパス、レイアウトと音楽の仕様、結果 JSON、波形シート、スペクトログラム、analyze() の表、未解決の問題。

Godot 4.7 に関する注意事項

• AudioStreamPlayer2D と 3D の area_mask のデフォルト値は 0 です（4.7）。エリアのバスオーバーライドを使うには 1 に設定する必要があります（確認済み）。
• AudioEffectLimiter は非推奨です。AudioEffectHardLimiter を使用してください。 AudioEffectSpectrumAnalyzer.tap_back_pos は削除されています。
• set_bus_volume_linear、volume_linear、max_polyphony（デフォルト値は 1）が存在します。 AudioStreamInteractive、Synchronized、Playlist は 4.3 で追加されました。
• MP3 は Ogg と同様に bpm と beat_count を保持します（確認済み）。AudioStreamWAV には bpm がないため、ビート同期クリップには Ogg または MP3 を使用する必要があります。
• WAV のインポートでは、デフォルトで QOA が使用されます（compress/mode は 2、format は 3）。
• ヘッドレスでは Dummy ドライバーを通じてミックスされます（方式 1）。Movie Maker にはウィンドウが必要です。
• 使わなくなった Godot 3 の慣習：yield、Tween ノード、ResourceSaver.save(path, res)。

参考資料

• references/procedures.md（P1～P15 のコードと結果； ジェネレーター、プールのコスト、Movie Maker の数値を記載）、 expert-notes.md（専門家別の原則とタイムスタンプ）、 critique.md（評価基準）、gui-paths.md（Audio パネル、遷移マトリクス、Import ドック、Profiler）、sources.md。
• scripts/gd_audio.py：インストール、インポートの編集と監査、analyze、トーンの追跡、AI の取り込み、ムービー音声、画像。
• scripts/agentkit/audio/：audio_meter、audio_buses、 music_builder、sfx_pool、occluder_3d、tone_generator、audio_audit。