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

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

在过程帧期间执行多普勒跟踪（请参阅 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 层影响混响和音频总线效果的声音。区域可用于重定向 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 🔗

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

注意：如果 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 在听者较远时需要混音，从而节省 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 相乘，缩放节点的声像强度。如果乘积为 0.0 则禁用立体声声像，所有声道的音量相同。如果乘积为 1.0 则当声音位于听者的正左（或正右）时，有一个通道将被静音。

两个扬声器的立体声配置实现了 WebAudio 标准的 StereoPannerNode 声像，音量为到耳朵的半方位角的余弦值。

5.1 和 7.1 等其他扬声器配置则实现了 SPCAP（扬声器放置校正幅度）算法。

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

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

bool has_stream_playback() 🔗

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

void play(from_position: float = 0.0) 🔗

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

void seek(to_position: float) 🔗

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

void stop() 🔗

停止音频。