AudioStreamPlayer3D

继承： Node3D < Node < Object

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

描述

根据音频收听者的相对位置播放具有位置音效的音频。位置效应包括距离衰减、方向性和多普勒效应。为了更逼真，低通滤波器会自动应用于远处的声音。这可以通过将 attenuation_filter_cutoff_hz 设置为 20500 来禁用。

默认情况下，音频是从相机的位置听到的，这可以通过在场景中添加一个 AudioListener3D 节点，并通过对其调用 AudioListener3D.make_current 来启用该节点来改变。

参阅 AudioStreamPlayer 来播放非位置的声音。

注意：隐藏一个 AudioStreamPlayer3D 节点并不能禁用其音频输出。要暂时禁用 AudioStreamPlayer3D 的音频输出，请将 volume_db 设置为一个非常低的值，如 -100（人的听觉听不到）。

教程

• 音频流

属性

方法

信号

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 🔗

• void set_attenuation_model(value: AttenuationModel)

• AttenuationModel get_attenuation_model()

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

bool autoplay = false 🔗

• void set_autoplay(value: bool)

• bool is_autoplay_enabled()

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

StringName bus = &"Master" 🔗

• void set_bus(value: StringName)

• StringName get_bus()

播放音频的总线。

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

DopplerTracking doppler_tracking = 0 🔗

• void set_doppler_tracking(value: DopplerTracking)

• DopplerTracking get_doppler_tracking()

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

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 乘以该因子，来缩放该节点的声像强度。与较低的值相比，较高的值将从左到右更显著地声像移动音频。

float pitch_scale = 1.0 🔗

• void set_pitch_scale(value: float)

• float get_pitch_scale()

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

PlaybackType playback_type = 0 🔗

• void set_playback_type(value: PlaybackType)

• PlaybackType get_playback_type()

实验性： 未来版本中可能会修改或移除该属性。

The playback type of the stream player. If set other than to the default value, it will force that playback type.

bool playing = false 🔗

• bool is_playing()

如果为 true，则音频正在播放，或者已加入播放队列（见 play）。

AudioStream stream 🔗

• void set_stream(value: AudioStream)

• AudioStream get_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 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() 🔗

停止音频。