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

• void set_attenuation_model ( AttenuationModel value )

• AttenuationModel get_attenuation_model ( )

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

bool autoplay = false

• void set_autoplay ( bool value )

• bool is_autoplay_enabled ( )

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

StringName bus = &"Master"

• void set_bus ( StringName value )

• StringName get_bus ( )

播放音频的总线。

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

DopplerTracking doppler_tracking = 0

• void set_doppler_tracking ( DopplerTracking value )

• DopplerTracking get_doppler_tracking ( )

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

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_distance 与 unit_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

• void set_stream ( AudioStream value )

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

停止音频。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.