Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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 等较低的采样率，不会降低质量。