AudioStreamPlayer3D

Наследует: Node3D < Node < Object

Воспроизводит позиционный звук в трехмерном пространстве.

Описание

Воспроизводит аудио с позиционными звуковыми эффектами, основанными на относительном положении слушателя аудио. Позиционные эффекты включают затухание на расстоянии, направленность и эффект Доплера. Для большей реалистичности к удаленным звукам применяется фильтр нижних частот. Это можно отключить, установив attenuation_filter_cutoff_hz на 20500.

По умолчанию звук слышен из положения камеры. Это можно изменить, добавив узел AudioListener3D в сцену и включив его, вызвав AudioListener3D.make_current() для него.

См. также AudioStreamPlayer, чтобы воспроизвести звук непозиционно.

Примечание: Скрытие узла AudioStreamPlayer3D не отключает его аудиовыход. Чтобы временно отключить аудиовыход AudioStreamPlayer3D, установите для volume_db очень низкое значение, например -100 (которое не слышно человеческому уху).

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

Свойства

int

area_mask

1

float

attenuation_filter_cutoff_hz

5000.0

float

attenuation_filter_db

-24.0

AttenuationModel

attenuation_model

0

bool

autoplay

false

StringName

bus

&"Master"

DopplerTracking

doppler_tracking

0

float

emission_angle_degrees

45.0

bool

emission_angle_enabled

false

float

emission_angle_filter_attenuation_db

-12.0

float

max_db

3.0

float

max_distance

0.0

int

max_polyphony

1

float

panning_strength

1.0

float

pitch_scale

1.0

PlaybackType

playback_type

0

bool

playing

false

AudioStream

stream

bool

stream_paused

false

float

unit_size

10.0

float

volume_db

0.0

float

volume_linear

Методы

float

get_playback_position()

AudioStreamPlayback

get_stream_playback()

bool

has_stream_playback()

void

play(from_position: float = 0.0)

void

seek(to_position: float)

void

stop()

Сигналы

finished() 🔗

Издается, когда прекращается воспроизведение звука.

Перечисления

enum AttenuationModel: 🔗

AttenuationModel ATTENUATION_INVERSE_DISTANCE = 0

Ослабление громкости в зависимости от линейного расстояния.

AttenuationModel ATTENUATION_INVERSE_SQUARE_DISTANCE = 1

Ослабление громкости пропорционально квадрату расстояния.

AttenuationModel ATTENUATION_LOGARITHMIC = 2

Ослабление громкости в зависимости от логарифмического расстояния.

AttenuationModel ATTENUATION_DISABLED = 3

Нет ослабления громкости в зависимости от расстояния. Звук все равно будет слышен позиционно, в отличие от AudioStreamPlayer. ATTENUATION_DISABLED можно объединить со значением max_distance, большим, чем 0.0, чтобы добиться линейного затухания, привязанного к сфере определенного размера.

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

Откл. доплеровского слежения.

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

Выполняет доплеровское отслеживание во время кадров процесса (см. Node.NOTIFICATION_INTERNAL_PROCESS).

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

Выполняет доплеровское отслеживание во время физических кадров (см. Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS).

Описания свойств

int area_mask = 1 🔗

  • void set_area_mask(value: int)

  • int get_area_mask()

Определяет, какие слои Area3D влияют на звук для эффектов реверберации и аудиошины. Области можно использовать для перенаправления AudioStreams так, чтобы они воспроизводились на определенной аудиошине. Примером того, как это можно использовать, является создание области «воды», чтобы звуки, воспроизводимые в воде, перенаправлялись через аудиошину, чтобы они звучали так, как будто они воспроизводятся под водой.

float attenuation_filter_cutoff_hz = 5000.0 🔗

  • void set_attenuation_filter_cutoff_hz(value: float)

  • float get_attenuation_filter_cutoff_hz()

Частота среза фильтра нижних частот ослабления в Гц. Звук выше этой частоты ослабляется сильнее, чем звук ниже этой частоты. Чтобы отключить этот эффект, установите его на 20500, так как эта частота выше предела человеческого слуха.

float attenuation_filter_db = -24.0 🔗

  • void set_attenuation_filter_db(value: float)

  • float get_attenuation_filter_db()

Величина, в которой фильтр влияет на громкость, в децибелах.

AttenuationModel attenuation_model = 0 🔗

Решает, должен ли звук становиться тише с расстоянием линейно, квадратично, логарифмически или не зависеть от расстояния, эффективно отключая затухание.

bool autoplay = false 🔗

  • void set_autoplay(value: bool)

  • bool is_autoplay_enabled()

Если true, звук воспроизводится при добавлении узла AudioStreamPlayer3D в дерево сцены.

StringName bus = &"Master" 🔗

Шина, на которой воспроизводится этот звук.

Примечание: При установке этого свойства имейте в виду, что проверка соответствия данного имени существующей шине не выполняется. Это связано с тем, что макеты аудиошин могут быть загружены после установки этого свойства. Если данное имя не может быть разрешено во время выполнения, оно вернется к "Master".

DopplerTracking doppler_tracking = 0 🔗

Решает, на каком этапе следует рассчитывать эффект Доплера.

Примечание: Если doppler_tracking не является DOPPLER_TRACKING_DISABLED, но в текущем Camera3D/AudioListener3D отключён доплеровский трекинг, эффект Доплера будет слышен, но не будет учитывать движение текущего слушателя. Для получения точного доплеровского трекинга доплеровский трекинг следует включить как в AudioStreamPlayer3D, так и в текущем Camera3D/AudioListener3D.

float emission_angle_degrees = 45.0 🔗

  • void set_emission_angle(value: float)

  • float get_emission_angle()

Угол, под которым звук достигает слушателя без ослабления.

bool emission_angle_enabled = false 🔗

  • void set_emission_angle_enabled(value: bool)

  • bool is_emission_angle_enabled()

Если true, звук должен быть ослаблен в соответствии с направлением звука.

float emission_angle_filter_attenuation_db = -12.0 🔗

  • void set_emission_angle_filter_attenuation_db(value: float)

  • float get_emission_angle_filter_attenuation_db()

Коэффициент затухания, используемый, если слушатель находится за пределами emission_angle_degrees и задан emission_angle_enabled, в децибелах.

float max_db = 3.0 🔗

  • void set_max_db(value: float)

  • float get_max_db()

Устанавливает абсолютный максимум уровня звука в децибелах.

float max_distance = 0.0 🔗

  • void set_max_distance(value: float)

  • float get_max_distance()

Расстояние, за пределами которого звук больше не слышен. Действует только если установлено значение больше 0.0. max_distance работает в паре с unit_size. Однако, в отличие от unit_size, поведение которого зависит от attenuation_model, max_distance всегда работает линейно. Это можно использовать для предотвращения необходимости микширования звука AudioStreamPlayer3D, когда слушатель находится далеко, что экономит ресурсы ЦП.

int max_polyphony = 1 🔗

  • void set_max_polyphony(value: int)

  • int get_max_polyphony()

Максимальное количество звуков, которые этот узел может воспроизводить одновременно. Воспроизведение дополнительных звуков после достижения этого значения приведет к отключению самых старых звуков.

float panning_strength = 1.0 🔗

  • void set_panning_strength(value: float)

  • float get_panning_strength()

Масштабирует силу панорамирования для этого узла, умножая базовый ProjectSettings.audio/general/3d_panning_strength на этот коэффициент. Если произведение равно 0.0, то стереопанорамирование отключено, а громкость одинакова для всех каналов. Если произведение равно 1.0, то один из каналов будет отключен, когда звук расположен точно слева (или справа) от слушателя.

Двухканальные стереосистемы реализуют стандарт WebAudio для панорамирования StereoPannerNode, где громкость равна косинусу половины угла азимута к уху.

Для других схем расположения динамиков, таких как 5.1 и 7.1, реализован алгоритм SPCAP (Speaker-Placement Correction Amplitude).

float pitch_scale = 1.0 🔗

  • void set_pitch_scale(value: float)

  • float get_pitch_scale()

Высота тона и темп звука как множитель частоты дискретизации аудиосэмпла.

PlaybackType playback_type = 0 🔗

Экспериментальное: Это свойство может быть изменено или удалено в будущих версиях.

Тип воспроизведения потокового проигрывателя. Если установлено значение, отличное от значения по умолчанию, будет принудительно выбран этот тип воспроизведения.

bool playing = false 🔗

  • void set_playing(value: bool)

  • bool is_playing()

Если true, звук воспроизводится или поставлен в очередь на воспроизведение (см. play()).

AudioStream stream 🔗

Ресурс AudioStream для воспроизведения.

bool stream_paused = false 🔗

  • void set_stream_paused(value: bool)

  • bool get_stream_paused()

Если true, воспроизведение приостанавливается. Вы можете возобновить его, установив stream_paused на false.

float unit_size = 10.0 🔗

  • void set_unit_size(value: float)

  • float get_unit_size()

Фактор эффекта затухания. Более высокие значения делают звук слышимым на большем расстоянии.

float volume_db = 0.0 🔗

  • void set_volume_db(value: float)

  • float get_volume_db()

Базовый уровень звука до затухания, в децибелах.

float volume_linear 🔗

  • void set_volume_linear(value: float)

  • float get_volume_linear()

Базовый уровень звука до затухания, как линейное значение.

Примечание: Этот член изменяет volume_db для удобства. Возвращаемое значение эквивалентно результату @GlobalScope.db_to_linear() для volume_db. Установка этого члена эквивалентна установке volume_db на результат @GlobalScope.linear_to_db() для значения.

Описания метода

float get_playback_position() 🔗

Возвращает позицию в AudioStream.

AudioStreamPlayback get_stream_playback() 🔗

Возвращает объект AudioStreamPlayback, связанный с этим AudioStreamPlayer3D.

bool has_stream_playback() 🔗

Возвращает, может ли AudioStreamPlayer вернуть объект AudioStreamPlayback или нет.

void play(from_position: float = 0.0) 🔗

Ставит звук в очередь для воспроизведения в следующем физическом кадре, начиная с указанной позиции from_position в секундах.

void seek(to_position: float) 🔗

Устанавливает позицию, с которой будет воспроизводиться звук, в секундах.

void stop() 🔗

Остановка звука.