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.

AudioStreamPlayer

继承: Node < Object

用于播放音频的节点。

描述

AudioStreamPlayer 节点能够播放音频流,播放的效果与位置无关,是用户界面、菜单、背景音乐的理想选择。

使用该节点时,需要将 stream 设为有效的 AudioStream 资源。此外,还支持同时播放多个声音,见 max_polyphony

如果你需要在特定的位置播放音频,请改用 AudioStreamPlayer2DAudioStreamPlayer3D

教程

属性

bool

autoplay

false

StringName

bus

&"Master"

int

max_polyphony

1

MixTarget

mix_target

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

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

当声音不受打断完成播放时发出。调用 stop不会发出该信号,播放声音时退出场景树也不会。


枚举

enum MixTarget: 🔗

MixTarget MIX_TARGET_STEREO = 0

音频将只在第一个声道中播放。这是默认行为。

MixTarget MIX_TARGET_SURROUND = 1

音频将在所有环绕声声道中播放。

MixTarget MIX_TARGET_CENTER = 2

音频将在第二个声道中播放,通常位于中央。


属性说明

bool autoplay = false 🔗

  • void set_autoplay(value: bool)

  • bool is_autoplay_enabled()

如果为 true,则该节点会在进入场景树时调用 play


StringName bus = &"Master" 🔗

目标总线的名称。该节点的所有声音都会在这条总线上播放。

注意:在运行时,如果不存在该名称的总线,那么所有声音都会回退至 "Master" 总线。另见 AudioServer.get_bus_name


int max_polyphony = 1 🔗

  • void set_max_polyphony(value: int)

  • int get_max_polyphony()

该节点可以同时播放的声音的最大数量。达到此值后再调用 play 将切断最早播放的声音。


MixTarget mix_target = 0 🔗

The mix target channels, as one of the MixTarget constants. Has no effect when two speakers or less are detected (see SpeakerMode).


float pitch_scale = 1.0 🔗

  • void set_pitch_scale(value: float)

  • float get_pitch_scale()

音频的音高和速度,是 stream 采样率的乘数。取值为 2.0 时音频的音高翻倍,为 0.5 时音高减半。


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,则该节点正在播放声音。设置该属性与 playstop 等效。


AudioStream stream 🔗

要播放的 AudioStream 资源。设置该属性会停止所有正在播放的声音。如果留空,则 AudioStreamPlayer 不工作。


bool stream_paused = false 🔗

  • void set_stream_paused(value: bool)

  • bool get_stream_paused()

如果为 true,则声音暂停。将 stream_paused 设置为 false 会恢复所有声音。

注意:进入和退出场景树以及节点暂停时均会自动修改该属性(见 Node.process_mode)。


float volume_db = 0.0 🔗

  • void set_volume_db(value: float)

  • float get_volume_db()

声音的音量,单位为分贝。这是对 stream 音量的偏移。

注意:如需在分贝和线性能量间进行转换(常见于音量滑块),请使用 @GlobalScope.db_to_linear@GlobalScope.linear_to_db


方法说明

float get_playback_position() 🔗

以秒为单位返回最后播放的声音在 AudioStream 中的位置。如果没有正在播放的声音,将返回 0.0

注意:返回的位置不一定精准,因为AudioServer不会在每个处理的帧中混合音频。要想得到更多准确的结果,请将AudioServer.get_time_since_last_mix添加到返回的位置。


AudioStreamPlayback get_stream_playback() 🔗

返回该节点最近的 AudioStreamPlayback,通常是最近由 play 创建的对象。如果当前没有在播放任何声音,则这个方法会失败并返回空的回放对象。


bool has_stream_playback() 🔗

如果有活动的声音则返回 true,即便 stream_pausedtrue。另见 playingget_stream_playback


void play(from_position: float = 0.0) 🔗

从开头或给定的位置 from_position 开始播放声音,位置的单位为秒。


void seek(to_position: float) 🔗

从给定的位置 to_position 开始重新播放所有声音,位置的单位为秒。如果当前没有在播放任何声音,则无事发生。


void stop() 🔗

停止该节点发出的所有声音。