AudioStreamGenerator

繼承： AudioStream < Resource < RefCounted < Object

提供程式式聲音生成工具的音訊流。

說明

AudioStreamGenerator 是一種音訊流，本身不會播放聲音；它需要程式碼為其產生音訊資料。另請參閱 AudioStreamGeneratorPlayback。

以下示範如何使用它來產生正弦波：

var playback # 用來保存 AudioStreamGeneratorPlayback。
@onready var sample_hz = $AudioStreamPlayer.stream.mix_rate
var pulse_hz = 440.0 # 聲波頻率。
var phase = 0.0

func _ready():
    $AudioStreamPlayer.play()
    playback = $AudioStreamPlayer.get_stream_playback()
    fill_buffer()

func fill_buffer():
    var increment = pulse_hz / sample_hz
    var frames_available = playback.get_frames_available()

    for i in range(frames_available):
        playback.push_frame(Vector2.ONE * sin(phase * TAU))
        phase = fmod(phase + increment, 1.0)

[Export] public AudioStreamPlayer Player { get; set; }

private AudioStreamGeneratorPlayback _playback; // 保存 AudioStreamGeneratorPlayback。
private float _sampleHz;
private float _pulseHz = 440.0f; // 聲波頻率。
private double phase = 0.0;

public override void _Ready()
{
    if (Player.Stream is AudioStreamGenerator generator) // 轉型為 generator 以存取 MixRate。
    {
        _sampleHz = generator.MixRate;
        Player.Play();
        _playback = (AudioStreamGeneratorPlayback)Player.GetStreamPlayback();
        FillBuffer();
    }
}

public void FillBuffer()
{
    float increment = _pulseHz / _sampleHz;
    int framesAvailable = _playback.GetFramesAvailable();

    for (int i = 0; i < framesAvailable; i++)
    {
        _playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau));
        phase = Mathf.PosMod(phase + increment, 1.0);
    }
}

在上述範例中，「AudioStreamPlayer」節點必須將 AudioStreamGenerator 設為其串流來源。fill_buffer 函式會產生近似正弦波的音訊資料。

若要進行即時音訊頻譜分析，請參閱 AudioEffectSpectrumAnalyzer。

注意： 受效能限制，建議在 C# 或透過 GDExtension 的編譯語言中使用此類別。若仍需在 GDScript 中使用，請考慮將 mix_rate 降至 11,025 Hz 或 22,050 Hz。

教學

音訊產生器範例

屬性

float	buffer_length	`0.5`
float	mix_rate	`44100.0`
AudioStreamGeneratorMixRate	mix_rate_mode	`2`

列舉

enum AudioStreamGeneratorMixRate: 🔗

AudioStreamGeneratorMixRate MIX_RATE_OUTPUT = 0

目前 AudioServer 的輸出混音速率。

AudioStreamGeneratorMixRate MIX_RATE_INPUT = 1

目前 AudioServer 的輸入混音速率。

AudioStreamGeneratorMixRate MIX_RATE_CUSTOM = 2

由 mix_rate 指定的自訂混音速率。

AudioStreamGeneratorMixRate MIX_RATE_MAX = 3

混音速率模式列舉的最大值。

屬性說明

float buffer_length = 0.5 🔗

void set_buffer_length(value: float)
float get_buffer_length()

要產生的緩衝長度（秒）。較低的值延遲更小，但腳本必須更快地生成音訊資料，增加 CPU 使用率，若處理不及恐導致破音。

float mix_rate = 44100.0 🔗

void set_mix_rate(value: float)
float get_mix_rate()

使用的取樣率（Hz）。取樣率越高，CPU 負擔越重，但音質越好。

遊戲中常見的取樣率有 11025、16000、22050、32000、44100 及 48000。

依據奈奎斯特–香農取樣定理，超過 40,000 Hz 對人耳已無聽覺差異（大多數人僅能聽到約 20,000 Hz）。若產生如人聲等低頻音，可使用 32000 或 22050 而不影響品質。

注意：AudioStreamGenerator 不會自動重新取樣輸入資料，為得到預期結果，mix_rate_mode 應與輸入資料的取樣率一致。

注意：若以 AudioEffectCapture 作為資料來源，請將 mix_rate_mode 設為 MIX_RATE_INPUT 或 MIX_RATE_OUTPUT 以自動配合目前 AudioServer 的混音速率。

AudioStreamGeneratorMixRate mix_rate_mode = 2 🔗

void set_mix_rate_mode(value: AudioStreamGeneratorMixRate)
AudioStreamGeneratorMixRate get_mix_rate_mode()

混音速率模式。若設為 MIX_RATE_CUSTOM 則使用 mix_rate；否則使用目前的 AudioServer 混音速率。