Document how to use AudioStreamGenerator

[MewPurPur]

This class doesn't have many (if any) resources online for how to use it. Other than our own, linked under tutorials:

• The first link is to a demo, which is alright, but I find it overkill since this class works from script without assets or complex node configurations.
• The second link is Juan's blog post from long ago when he announced the feature. The page itself claims it might be outdated - and indeed it is. The code also doesn't abide by GDScript's style guide, has a typo that results in an error, and... it can be better.

I changed up the description (to remove any confusion that AudioStreamGenerator produces sounds on its own). I also added a simple GDScript example and removed the second link.

[mieldepoche]

your code snippet is invalid, since you have to call play on the audioStreamPlayer before getting the stream playback (at least when using an audioStreamGenerator). No idea if it's a bug or something, but that's how it is. From what I get this means that you can't pre-fill a buffer? idk.
Here's a snippet that works (in 4.0.2):

@onready var sample_hz: float = $AudioStreamPlayer.stream.mix_rate
var playback: AudioStreamGeneratorPlayback
var pulse_hz := 440.0 # The frequency of the sound wave.


func _ready() -> void:
    $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)

[MewPurPur]

I think it's a bug. Neither Juan's announcement nor the demo do this. I believe it shouldn't be the case with AudioStreamGenerator, as the announcement moreover claims:

Just call this function before AudioStreamPlayer.play() (to ensure buffer is full before playback begins), and then call it from _process(), to ensure it remains full.

For reference: The error thrown is this:

godot/scene/audio/audio_stream_player.cpp

Line 315 in 7a0977c

ERR_FAIL_COND_V_MSG(stream_playbacks.is_empty(), Ref<AudioStreamPlayback>(), "Player is inactive. Call play() before requesting get_stream_playback().");

It was added 3 months ago in #71906

[MewPurPur]

Fixed a typo and addressed the concerns above.

[mhilbrunner]

Thanks! Merged.

[akien-mga]

Cherry-picked for 4.0.3.