Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

AudioStreamGenerator¶

继承： AudioStream < Resource < RefCounted < Object

提供程序式声音生成工具的音频流。

描述¶

AudioStreamGenerator 是一种音频流，它自己并不播放声音，而是要用脚本来为它生成音频数据。另见 AudioStreamGeneratorPlayback。

以下是用它来生成正弦波的例子：

var playback # 存放 AudioStreamGeneratorPlayback。
@onready var sample_hz = $AudioStreamPlayer.stream.mix_rate
var pulse_hz = 440.0 # 声音波形的频率。

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

func fill_buffer():
    var phase = 0.0
    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; // 音频波形的频率。

public override void _Ready()
{
    if (Player.Stream is AudioStreamGenerator generator) // Type as a generator to access MixRate.
    {
        _sampleHz = generator.MixRate;
        Player.Play();
        _playback = (AudioStreamGeneratorPlayback)Player.GetStreamPlayback();
        FillBuffer();
    }
}

public void FillBuffer()
{
    double phase = 0.0;
    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 中使用这个类，请考虑使用 11,025 Hz 或 22,050 Hz 等较低的 mix_rate。

教程¶

音频生成器演示

属性¶

float	buffer_length	`0.5`
float	mix_rate	`44100.0`

属性说明¶

float buffer_length = 0.5

void set_buffer_length ( float value )
float get_buffer_length ( )

要生成的缓冲区的长度，以秒为单位。较低的值会带来更少的延迟，但需要脚本更快地生成音频数据，从而导致 CPU 使用率增加，如果 CPU 跟不上，则音频破裂的风险更大。

float mix_rate = 44100.0

void set_mix_rate ( float value )
float get_mix_rate ( )

使用的采样率（单位：Hz）。更高的值对 CPU 要求更高，但会带来更好的质量。

在游戏中，常用的采样率有 11025、16000、22050、32000、44100、48000。

根据奈奎斯特–香农采样定理，当超过 40000 赫兹时，人类的听觉没有质量上的差别（因为大多数人最多只能听到 ~20000 赫兹，往往更少）。如果你要生成语音等音高较低的声音，则可以使用 32000 或 22050 等较低的采样率，不会降低质量。