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) // Type as a generator to access 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 中使用这个类，请考虑使用 11,025 Hz 或 22,050 Hz 等较低的 mix_rate。

教程

音频生成器演示

属性

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 使用率增加，如果 CPU 跟不上，则音频破裂的风险更大。

float mix_rate = 44100.0 🔗

void set_mix_rate(value: float)
float get_mix_rate()

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

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

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