AudioStreamPlayer2D

继承： Node2D < CanvasItem < Node < Object

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

描述

播放随与监听者的距离增大而衰减的音频。

默认情况下，音频是从屏幕中心收听的。要修改这个位置，可以在场景中添加一个 AudioListener2D 节点，并通过调用 AudioListener2D.make_current() 将其启用。

另见 AudioStreamPlayer 以非定位的方式播放声音。

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

教程

• 音频流

属性

int	area_mask	1
float	attenuation	1.0
bool	autoplay	false
StringName	bus	&"Master"
float	max_distance	2000.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	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() 🔗

当音频停止播放时发出。

---

属性说明

int area_mask = 1 🔗

• void set_area_mask(value: int)

• int get_area_mask()

决定对混响及音频总线效果有影响的 Area2D 层。可使用区域对 AudioStream 进行重定向，使其在特定的音频总线中播放。一个例子是可以用来制作“水域”，将水中播放的声音重定向至单独的音频总线，让声音听起来像是在水下播放。

---

float attenuation = 1.0 🔗

• void set_attenuation(value: float)

• float get_attenuation()

以该属性为指数，将音量随着距离的增加而衰减。

---

bool autoplay = false 🔗

• void set_autoplay(value: bool)

• bool is_autoplay_enabled()

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

---

StringName bus = &"Master" 🔗

• void set_bus(value: StringName)

• StringName get_bus()

这个音频在哪个总线上播放。

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

---

float max_distance = 2000.0 🔗

• void set_max_distance(value: float)

• float get_max_distance()

音频仍可听到的最大距离。

---

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/2d_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()

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

流播放器的播放类型。如果设置为非默认值，则将强制使用该播放类型。

---

bool playing = false 🔗

• void set_playing(value: bool)

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

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

---

bool has_stream_playback() 🔗

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

---

void play(from_position: float = 0.0) 🔗

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

---

void seek(to_position: float) 🔗

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

---

void stop() 🔗

停止音频。