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) // Введите в качестве генератора для доступа к 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 Гц или 22 050 Гц.

Обучающие материалы

Свойства

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()

Длина буфера для генерации (в секундах). Более низкие значения приводят к меньшей задержке, но требуют, чтобы скрипт генерировал аудиоданные быстрее, что приводит к увеличению использования ЦП и большему риску взлома звука, если ЦП не справляется.

float mix_rate = 44100.0 🔗

void set_mix_rate(value: float)
float get_mix_rate()

Частота дискретизации для использования (в Гц). Более высокие значения более требовательны к ЦП для генерации, но приводят к лучшему качеству.

В играх обычно используются частоты дискретизации 11025, 16000, 22050, 32000, 44100 и 48000.

Согласно теореме дискретизации Найквиста-Шеннона, для человеческого слуха нет никакой разницы в качестве при выходе за пределы 40 000 Гц (поскольку большинство людей могут слышать только до ~20 000 Гц, часто меньше). Если вы генерируете более низкие звуки, такие как голоса, можно использовать более низкие частоты дискретизации, такие как 32000 или 22050 без потери качества.

Примечание: AudioStreamGenerator не выполняет автоматическую передискретизацию (resampling) входных данных, для получения ожидаемого результата 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.