AudioPlayer

继承： Item3D < Item < Object

在3D空间中播放位置声音。

描述

根据音频听众的相对位置播放带有位置音效的音频。位置效果包括距离衰减、方向性和多普勒效应。为了更加逼真，对远处的声音应用了低通滤波器。可以通过将attenuation_filter_cutoff_hz设置为20500来禁用此功能。

默认情况下，从摄像机位置听到音频。这可以通过向场景添加AudioListener节点并通过调用AudioListener.make_current()来启用它来更改。

另见AudioStreamPlayer播放非位置声音。

注意：隐藏AudioPlayer节点不会禁用其音频输出。要暂时禁用AudioPlayer的音频输出，请将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可以与大于0.0的max_distance值组合，以实现固定在定义大小的球体上的线性衰减。

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

禁用多普勒跟踪。

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

在处理帧期间执行多普勒跟踪（参见Item.NOTIFICATION_INTERNAL_PROCESS）。

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

在物理帧期间执行多普勒跟踪（参见Item.NOTIFICATION_INTERNAL_PHYSICS_PROCESS）。

属性说明

int area_mask = 1 🔗

  • void set_area_mask(value: int)

  • int get_area_mask()

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

float attenuation_filter_cutoff_hz = 5000.0 🔗

  • void set_attenuation_filter_cutoff_hz(value: float)

  • float get_attenuation_filter_cutoff_hz()

衰减低通滤波器的截止频率，单位为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 🔗

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

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总是以线性方式工作。这可以用来防止AudioPlayer在听众很远的时候需要音频混合，从而节省CPU资源。

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乘以此因子来缩放此节点的平移强度。较高的值将比较低的值更显着地从左到右平移音频。

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，返回值等价于volume_db上@GlobalScope.db_to_linear()的结果，设置此成员等价于设置volume_db为某个值上@GlobalScope.linear_to_db()的结果。

方法说明

float get_playback_position() 🔗

返回AudioStream中的位置。

AudioStreamPlayback get_stream_playback() 🔗

返回与此AudioPlayer关联的AudioStreamPlayback对象。

bool has_stream_playback() 🔗

返回AudioStreamPlayer是否可以返回AudioStreamPlayback对象。

void play(from_position: float = 0.0) 🔗

从给定位置from_position在下一个物理帧上播放音频。

void seek(to_position: float) 🔗

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

void stop() 🔗

停止音频。