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 # 聲波頻率。
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 混音速率。