Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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

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 🔗

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

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 🔗

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

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

bool playing = false 🔗

如果为 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 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() 🔗

停止音频。