AudioStreamPlayer3D

AudioStreamPlayer3D

Inherits: Spatial < Node < Object

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

描述

播放具有定向性的声音效果，如果需要，可随着距离的增加而减弱，产生空间中可听到的位置效果。为了更逼真，低通滤波器会自动应用于远处的声音。这可以通过设置attenuation_filter_cutoff_hz为20500来禁用。

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

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

注意： 隐藏一个AudioStreamPlayer3D节点并不能禁用其音频输出。要暂时禁用AudioStreamPlayer3D的音频输出，请将unit_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`
String	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`
OutOfRangeMode	out_of_range_mode	`0`
float	pitch_scale	`1.0`
bool	playing	`false`
AudioStream	stream
bool	stream_paused	`false`
float	unit_db	`0.0`
float	unit_size	`1.0`

方法

float	get_playback_position ( )
AudioStreamPlayback	get_stream_playback ( )
void	play ( float from_position=0.0 )
void	seek ( float to_position )
void	stop ( )

信号

finished ( )

当音频停止播放时发出。

枚举

enum AttenuationModel:

ATTENUATION_INVERSE_DISTANCE = 0 —- 根据距离对响度进行线性衰减。
ATTENUATION_INVERSE_SQUARE_DISTANCE = 1 —- 根据距离对响度进行平方衰减。
ATTENUATION_LOGARITHMIC = 2 —- 根据距离对数降低响度。
ATTENUATION_DISABLED = 3 —- 不会根据距离衰减响度。与 AudioStreamPlayer 不同，声音仍会在位置上被听到。 ATTENUATION_DISABLED 可以与大于 0.0 的 max_distance 值结合使用，以实现线性衰减，限制在定义的球体大小。

enum OutOfRangeMode:

OUT_OF_RANGE_MIX = 0 —- 将此音频混合，即使它超出范围。这会增加 CPU 使用率，但如果相机离开并进入 AudioStreamPlayer3D 的 max_distance 半径，则保持声音在正确的位置播放。
OUT_OF_RANGE_PAUSE = 1 —- 超出范围时暂停此音频。这会降低 CPU 使用率，但如果相机离开并进入 AudioStreamPlayer3D 的 max_distance 半径，则会使声音重新开始。

enum DopplerTracking:

DOPPLER_TRACKING_DISABLED = 0 —- 禁用多普勒跟踪。
DOPPLER_TRACKING_IDLE_STEP = 1 —- 在空闲的步骤中执行多普勒跟踪（每渲染一帧）。
DOPPLER_TRACKING_PHYSICS_STEP = 2 —- 在物理步骤中执行多普勒跟踪（每个模拟的物理帧）。

属性说明

int area_mask

Default	`1`
Setter	set_area_mask(value)
Getter	get_area_mask()

这个声音的播放区域。

float attenuation_filter_cutoff_hz

Default	`5000.0`
Setter	set_attenuation_filter_cutoff_hz(value)
Getter	get_attenuation_filter_cutoff_hz()

使用高于此频率的低通滤波器衰减音频，以 Hz 为单位。要完全禁用阻尼效果，请将其设置为 20500，因为该频率高于人类听力极限。

float attenuation_filter_db

Default	`-24.0`
Setter	set_attenuation_filter_db(value)
Getter	get_attenuation_filter_db()

滤波器对响度的影响程度，以分贝为单位。

AttenuationModel attenuation_model

Default	`0`
Setter	set_attenuation_model(value)
Getter	get_attenuation_model()

决定音频是否应该得到更安静的距离线性，平方，对数，或不受影响的距离，有效地禁用衰减。

bool autoplay

Default	`false`
Setter	set_autoplay(value)
Getter	is_autoplay_enabled()

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

String bus

Default	`“Master”`
Setter	set_bus(value)
Getter	get_bus()

播放此音频的总线。

DopplerTracking doppler_tracking

Default	`0`
Setter	set_doppler_tracking(value)
Getter	get_doppler_tracking()

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

注意：仅当当前 Camera 的 Camera.doppler_tracking 属性设置为 Camera.DOPPLER_TRACKING_DISABLED 以外的值时有效。

float emission_angle_degrees

Default	`45.0`
Setter	set_emission_angle(value)
Getter	get_emission_angle()

音频到达相机的角度，不受衰减。

bool emission_angle_enabled

Default	`false`
Setter	set_emission_angle_enabled(value)
Getter	is_emission_angle_enabled()

如果true，则应根据声音的方向对音频进行衰减。

float emission_angle_filter_attenuation_db

Default	`-12.0`
Setter	set_emission_angle_filter_attenuation_db(value)
Getter	get_emission_angle_filter_attenuation_db()

如果样机在 emission_angle_degrees 之外，并且 emission_angle_enabled 被设置为这个系数，则对音频进行减弱，单位是分贝。

float max_db

Default	`3.0`
Setter	set_max_db(value)
Getter	get_max_db()

设置声级的绝对最大值，以分贝为单位。

float max_distance

Default	`0.0`
Setter	set_max_distance(value)
Getter	get_max_distance()

设置out_of_range_mode生效的距离。设置为0时没有效果。

OutOfRangeMode out_of_range_mode

Default	`0`
Setter	set_out_of_range_mode(value)
Getter	get_out_of_range_mode()

决定当音源超出 max_distance 范围时，是否应该暂停音频。

float pitch_scale

Default	`1.0`
Setter	set_pitch_scale(value)
Getter	get_pitch_scale()

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

bool playing

Default	`false`
Getter	is_playing()

如果true，则播放音频。

AudioStream stream

Setter	set_stream(value)
Getter	get_stream()

要播放的AudioStream资源。

bool stream_paused

Default	`false`
Setter	set_stream_paused(value)
Getter	get_stream_paused()

如果true，则播放会暂停。你可以通过设置stream_paused为false来恢复它。

float unit_db

Default	`0.0`
Setter	set_unit_db(value)
Getter	get_unit_db()

不受阻尼影响的基本声级，单位为分贝。

float unit_size

Default	`1.0`
Setter	set_unit_size(value)
Getter	get_unit_size()

衰减效果的系数。更高的值使声音在更远的距离可以听到。

方法说明

float get_playback_position ( )

返回AudioStream中的位置。

AudioStreamPlayback get_stream_playback ( )

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

void play ( float from_position=0.0 )

从给定的位置from_position播放音频，以秒为单位。

void seek ( float to_position )

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

void stop ( )

停止音频。