bevy-audio

Bevy 0.19 — オーディオ

このスキルを使用する場面

• AudioPlayer とシンクコンポーネントを使って、クリップやループを再生または制御する場合。
• 音楽や環境音の切り替え、カテゴリのミックス、ダッキング、一時停止ポリシーを構築する場合。
• 空間音源やリスナーを追加する場合、または組み込みの HRTF／エフェクトの境界を定義する場合。
• ブラウザー向けにオーディオを配信する場合、またはグラフバックエンドとして bevy_seedling 0.8 を評価する場合。

単純なクリップ、ループ、再生制御、基本的な空間ステレオには、Bevy の組み込みのエンティティベースのオーディオを使用します。カテゴリや切り替えには、アプリケーション側でミキサーポリシーを追加します。測定値や設計上の要件がその範囲を超える場合に限り、オーディオグラフライブラリに移行してください。

標準的なパターン

use bevy::{audio::Volume, prelude::*};

#[derive(Component)]
struct Music;

fn start_music(mut commands: Commands, assets: Res<AssetServer>) {
    commands.spawn((
        Name::new("Exploration music"),
        Music,
        AudioPlayer::new(assets.load("audio/exploration.ogg")),
        PlaybackSettings::LOOP.with_volume(Volume::Decibels(-9.0)),
    ));
}

fn mute_music(mut sinks: Query<&mut AudioSink, With<Music>>) {
    for mut sink in &mut sinks {
        sink.mute();
    }
}

Bevy は、空間化されていない再生の開始後に AudioSink を、空間再生には SpatialAudioSink を挿入します。シンクをクエリして、再生中の音量、ミュート、一時停止、速度、位置、シーク、停止を操作します。PlaybackSettings や GlobalVolume を変更しても、すでに再生中のオーディオには反映されません。

PlaybackSettings::{ONCE, LOOP, DESPAWN, REMOVE} は、再生完了時の処理を定義します。ONCE プレイヤーはシンクの再生が終わると、そのまま再生を再開できません。オーディオコンポーネントを削除して再挿入するか、新しいプレイヤーを生成してください。AudioPlayer を残したままシンクを削除すると、変更されていない音源の再生が再開します。

注意点

• PlaybackSettings と GlobalVolume が影響するのは初回の再生であり、既存のシンクには影響しません。
• シンクが現れるのは再生開始後のみです。任意のクエリとして取得してください。
• 再生が終わった ONCE 再生は、オーディオコンポーネントを置き換えない限り再生できません。
• 変更されていないプレイヤーを残したままシンクを削除すると、音源の再生が再開します。
• 組み込みの空間オーディオはステレオパンニングであり、HRTF や汎用エフェクトグラフではありません。

空間オーディオの境界

fn spawn_spatial_loop(mut commands: Commands, assets: Res<AssetServer>) {
    commands.spawn((
        SpatialListener::new(0.2),
        Transform::default(),
    ));
    commands.spawn((
        AudioPlayer::new(assets.load("audio/generator.ogg")),
        PlaybackSettings::LOOP.with_spatial(true),
        Transform::from_xyz(4.0, 0.0, 0.0),
    ));
}

SpatialListener は必ず 1 つだけにし、正となるリスナー／カメラの姿勢にアタッチしてください。ワールド単位がオーディオの距離と一致しない場合は、SpatialScale を設定します。組み込みの空間化は単純な左右のステレオパンニングです。HRTF や完全な 3D 音響モデルには対応していません。

ミックスグループと切り替え

組み込みオーディオには、汎用バス／エフェクトグラフはありません。カテゴリ（Master、Music、Sfx、Dialogue、Ambience、Ui）をアプリケーションの状態としてモデル化し、プレイヤーエンティティにタグを付けます。マスター × グループ × 切り替え／ダッキング × 音源ゲインから実効ゲインを計算し、シンクに書き込みます。スライダーはデシベルまたは知覚的に使いやすいカーブで保存してください。実用的な範囲の大部分が数ピクセルに押し込まれるような、線形値の UI は避けてください。

音楽や環境音を切り替える場合は、ポーズポリシーに応じて実時間または仮想時間を使い、古いループと新しいループを重ねてクロスフェードします。シンクが無音になるまでは、古いエンティティを破棄しないでください。遅延が問題となる切り替えの前にアセットを事前読み込みし、新しいトラックの準備ができていない場合の動作を定義してください。

ブラウザー向けのルール

ブラウザーでは、ユーザー操作があるまで音声再生がブロックされることがよくあります。オーディオのロック解除を明示的なアプリ状態として扱い、最初の意図的な入力でオーディオを再開または開始し、ブロックされた場合はリクエストを保留し、利用しやすいミュート／ロック解除コントロールを表示してください。ページの再読み込み、タブのバックグラウンド／フォアグラウンドへの切り替え、デバイス変更、モバイルブラウザーをテストしてください。起動時に再生できたからといって、すべてのブラウザーで再生が許可されるとは限りません。

組み込み機能と Seedling

単純な再生、制御、空間パンニングには、Bevy の組み込みオーディオを選択してください。Bevy 0.19 では、バス／エフェクト、エミッターのプール化、サンプル精度の高いスケジューリング、より豊かなルーティング、または Firewheel スタック経由の HRTF が必要な場合、bevy_seedling 0.8 が互換性のあるグラフベースの選択肢です。HRTF はデフォルトの機能ではありません。Seedling の hrtf 機能を有効にしてください（埋め込み済みのすべての被験者が必要な場合に限り、hrtf_subjects も有効にします）。2 つのバックエンド／型が競合しないよう、Seedling を使用する場合は Bevy の組み込み audio 機能を無効にしてください。ライブラリの使用するリリースとプラットフォームを固定し、テストしてください。

関連する詳細を確認する

問題	参照先
プレイヤー、再生モード、シンク、リプレイ、クリーンアップ	組み込みオーディオ
ミックスモデル、クロスフェード、ダッキング、一時停止、アセットのライフタイム	ミキシング、ライフサイクル、トランジション
空間的な制限、ブラウザーのロック解除、アクセシビリティ、Seedling の境界	空間オーディオ、Web、Seedling

レビューチェックリスト

• 再生エンティティの所有権と完了モードが意図どおりになっています。
• 実行時の変更はPlaybackSettingsではなく、シンクを対象にしています。
• グループ／マスターの変更によって、ソースゲインを損なうことなく再生中のシンクが更新されます。
• トランジションは、アセットの読み込み遅延、急激な状態変化、一時停止、エンティティのクリーンアップに対応しています。
• リスナーが正確に1つだけ存在し、スケール／ポーズが意図した視点に追従しています。
• ブラウザーのオーディオロック解除／失敗が明示され、復旧可能です。
• ダイアログには字幕があり、重要なオーディオキューには音声以外の代替手段があります。
• ヘッドレステストでは、オーディオデバイスを必要とせずにミキサー／状態ロジックを検証しています。

関連項目

• bevy-a11y — 字幕、キューの代替手段、ダイナミックレンジ、コントロール。
• bevy-assets — 読み込み状態、ハンドル、アセットのライフタイム。
• bevy-testing — 決定論的なミキサー／トランジションのテスト。
• Bevy オーディオモジュール
• bevy_seedling 0.8