オーディオプレイヤー

AudioPlayerクラスを使ってBGMや効果音などのオーディオ再生ができます。 WAVやOgg Vorbisなどの音源ファイルを再生・一時停止・停止・ループ・フェードアウトなど多彩な制御が可能です。

基本の使い方

AudioPlayerはインスタンスを生成して利用します。

// 初期化
var audio = new AudioPlayer();

// 再生
audio.Play(new VorbisAudioSource("assets/bgm.ogg"));

// 停止
audio.Stop();

// 一時停止・再開
audio.Pause();
audio.Resume();

主なAPI

audio.Play(source, loop)
音源を再生します（loopはループ開始位置、省略可）
audio.Stop(time)
再生を停止します（timeはフェードアウト秒、省略可）
audio.Pause()
一時停止します
audio.Resume()
一時停止を解除します
audio.PlayOneShot(source, gain, pitch, pan, followsMasterGain)
効果音などをその場で再生します（followsMasterGainをtrueにするとaudio.Gainが乗算されます）
audio.Gain
音量（0.0～1.0）
audio.Pan
パン（-1.0～1.0）
audio.Pitch
ピッチ比率
audio.IsPlaying
再生中かどうか
audio.IsPausing
一時停止中かどうか
audio.Time
再生位置（ミリ秒）。値を設定するとその位置へシークします
audio.TimeInSamples
再生位置（サンプル単位）。値を設定するとその位置へシークします
audio.Length
音源の長さ（ミリ秒）
audio.StartPlaying
再生開始イベント
audio.StopPlaying
停止イベント
audio.Loop
ループ時イベント
audio.FinishPlaying
再生終了イベント

サンプル：BGM再生とイベント

private readonly AudioPlayer _audio = new();
private VorbisAudioSource _bgm = new("./assets/amaebi.ogg");

public override void OnStart()
{
    _audio.StartPlaying += (_, _) => console.Print($"BGM STARTED");
    _audio.StopPlaying += (_, _) => console.Print($"BGM STOPPED");
    _audio.Loop += (_, _) => console.Print($"BGM LOOP");
    _audio.FinishPlaying += (_, _) => console.Print($"BGM FINISHED");
    _audio.Play(_bgm, 0);
}

シーク

Time または TimeInSamples に値を設定すると、再生位置を変更できます。

// 30秒地点へシーク
audio.Time = 30000;

再生していないときに設定した値は、次に Play したときの開始位置になります
Stop を呼ぶと再生位置は 0 にリセットされます
範囲外の値を設定した場合は、音源の長さの範囲内にクランプされます

バッファサイズとレイテンシ

AudioPlayer は、音声データを小さなかたまり（バッファ）に分けて少し先まで用意しながら出力しています。このバッファの大きさと数によって、Play を呼んでから実際に音が聴こえるまでの遅れ（レイテンシ）が決まります。

audio.BufferSize
1バッファあたりのフレーム数です。デフォルトは 1024（44.1kHz でおよそ 23ms）です
audio.BufferCount
先に用意しておくバッファの数です。デフォルトは 3、最小は 2 です

レイテンシはおよそ「BufferSize × BufferCount ÷ サンプリング周波数」になります。どちらも小さくするほど遅れは減りますが、処理が間に合わずに音が途切れやすくなります。

// 遅延を減らしたい場合（音が途切れる場合は値を戻してください）
audio.BufferSize = 512;
audio.BufferCount = 2;

BufferSize と BufferCount は、値を設定した時点で出力が再起動され、すぐに反映されます。

現在の出力レイテンシは audio.Latency でミリ秒単位で取得できます。 Time はこのレイテンシを考慮した「実際に聴こえている位置」を返すため、通常は自分で補正する必要はありません。リズムゲームのタイミング調整などの目安として利用できます。

console.Print($"レイテンシ: {audio.Latency:F1}ms");

ノート

再生できるフォーマットはWAV（8/16/24/32bit PCM、32bit float）, Ogg Vorbisなどです
効果音再生には PlayOneShot を使うと便利です
再生中に Stop を呼ぶと即時またはフェードアウトで停止します
イベントで再生状態の変化を検知できます
audio.Filters にディレイやローパスなどのDSPフィルターを追加できます。詳しくはオーディオフィルターを参照してください