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

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

停止音频。