Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

AudioStreamPlayer3D

继承: Node3D < Node < Object

在 3D 空间中播放与位置相关的声音。

描述

根据音频收听者的相对位置播放具有位置音效的音频。位置效应包括距离衰减、方向性、和多普勒效应。为了更逼真,低通滤波器会自动应用于远处的声音。这可以通过将 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

bool

playing

false

AudioStream

stream

bool

stream_paused

false

float

unit_size

10.0

float

volume_db

0.0

方法

float

get_playback_position ( )

AudioStreamPlayback

get_stream_playback ( )

bool

has_stream_playback ( )

void

play ( float from_position=0.0 )

void

seek ( float to_position )

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 可以与大于 0.0max_distance 值结合使用,以实现线性衰减,限制在定义的球体大小。


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

  • int get_area_mask ( )

确定哪些 Area3D 层影响混响和音频总线效果的声音。区域可用于重定向 AudioStream,以便它们在特定音频总线中播放。可以如何使用它的一个示例是制作一个“水”区域,以便在水中播放的声音通过音频总线重定向,使它们听起来像是在水下播放的。


float attenuation_filter_cutoff_hz = 5000.0

  • void set_attenuation_filter_cutoff_hz ( float value )

  • float get_attenuation_filter_cutoff_hz ( )

衰减低通滤波器的截止频率,单位为 Hz。高于该频率的声音比低于此频率的声音衰减得更多。要禁用该效果,请将其设置为 20500,因为该频率高于人类听力极限。


float attenuation_filter_db = -24.0

  • void set_attenuation_filter_db ( float value )

  • float get_attenuation_filter_db ( )

滤波器对响度的影响程度,以分贝为单位。


AttenuationModel attenuation_model = 0

决定音频是否应该随着距离,以线性、二次、对数的方式变得更安静,或者不受距离影响,有效地禁用衰减。


bool autoplay = false

  • void set_autoplay ( bool value )

  • bool is_autoplay_enabled ( )

如果为 true,则在将 AudioStreamPlayer3D 节点添加到场景树时播放音频。


StringName bus = &"Master"

播放音频的总线。

注意:设置这个属性时,请记住它并不会对给定的名称是否与现有总线匹配进行校验。这是因为音频总线布局可以在设置这个属性后再加载。如果这个给定的名称在运行时无法解析,就会回退到 "Master"


DopplerTracking doppler_tracking = 0

决定应该在哪个步骤计算多普勒效应。


float emission_angle_degrees = 45.0

  • void set_emission_angle ( float value )

  • float get_emission_angle ( )

音频到达听者而不衰减的角度。


bool emission_angle_enabled = false

  • void set_emission_angle_enabled ( bool value )

  • bool is_emission_angle_enabled ( )

如果为 true,则音频应该根据声音的方向衰减。


float emission_angle_filter_attenuation_db = -12.0

  • void set_emission_angle_filter_attenuation_db ( float value )

  • float get_emission_angle_filter_attenuation_db ( )

听者在 emission_angle_degrees 之外且 emission_angle_enabled 被设置时使用的衰减系数,单位是分贝。


float max_db = 3.0

  • void set_max_db ( float value )

  • float get_max_db ( )

设置声级的绝对最大值,以分贝为单位。


float max_distance = 0.0

  • void set_max_distance ( float value )

  • float get_max_distance ( )

完全听不到声音的距离。仅当设置为大于 0.0 的值时才有效。max_distanceunit_size 协同工作。但是,与 unit_size 的行为取决于 attenuation_model 不同,max_distance 始终以线性方式工作。这可用于防止 AudioStreamPlayer3D 在听者较远时需要混音,从而节省 CPU 资源。


int max_polyphony = 1

  • void set_max_polyphony ( int value )

  • int get_max_polyphony ( )

该节点可以同时播放的最大声音数。达到此值后,播放额外的声音将切断最旧的声音。


float panning_strength = 1.0

  • void set_panning_strength ( float value )

  • float get_panning_strength ( )

通过将基础 ProjectSettings.audio/general/3d_panning_strength 乘以该因子,来缩放该节点的声像强度。与较低的值相比,较高的值将从左到右更显著地声像移动音频。


float pitch_scale = 1.0

  • void set_pitch_scale ( float value )

  • float get_pitch_scale ( )

音频的音高和节奏,作为音频样本的采样率的倍数。


bool playing = false

  • bool is_playing ( )

如果为 true,则音频正在播放,或者已加入播放队列(见 play)。


AudioStream stream

要播放的 AudioStream 资源。


bool stream_paused = false

  • void set_stream_paused ( bool value )

  • bool get_stream_paused ( )

如果为 true,则播放会暂停。你可以通过将 stream_paused 设置为 false来恢复它。


float unit_size = 10.0

  • void set_unit_size ( float value )

  • float get_unit_size ( )

衰减效果的系数。更高的值使声音在更远的距离可以听到。


float volume_db = 0.0

  • void set_volume_db ( float value )

  • float get_volume_db ( )

不受衰减影响的基础声级,单位为分贝。


方法说明

float get_playback_position ( )

返回 AudioStream 中的位置。


AudioStreamPlayback get_stream_playback ( )

返回与这个 AudioStreamPlayer3D 相关联的 AudioStreamPlayback 对象。


bool has_stream_playback ( )

返回该 AudioStreamPlayer 是否能够返回 AudioStreamPlayback 对象。


void play ( float from_position=0.0 )

将要播放的音频入队,将在下一物理帧从给定的位置 from_position 开始播放,单位为秒。


void seek ( float to_position )

设置音频的播放位置,以秒为单位。


void stop ( )

停止音频。