AudioStreamPlayer

继承： Node < Object

用于播放音频的节点。

描述

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

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

如果你需要在特定的位置播放音频，请改用 AudioStreamPlayer2D 或 AudioStreamPlayer3D。

教程

• 音频流

• 2D Dodge The Creeps 演示

• 音频设备切换演示

• 音频生成器演示

• 音频麦克风录音演示

• 音频频谱可视化演示

属性

方法

信号

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" 🔗

• void set_bus(value: StringName)

• StringName get_bus()

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

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

int max_polyphony = 1 🔗

• void set_max_polyphony(value: int)

• int get_max_polyphony()

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

MixTarget mix_target = 0 🔗

• void set_mix_target(value: MixTarget)

• MixTarget get_mix_target()

混合目标声道，使用 MixTarget 常量。检测到小于等于两个扬声器时无效（见 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 🔗

• void set_playback_type(value: PlaybackType)

• PlaybackType get_playback_type()

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

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

bool playing = false 🔗

• bool is_playing()

如果为 true，则该节点正在播放声音。设置该属性与 play 和 stop 等效。

AudioStream stream 🔗

• void set_stream(value: AudioStream)

• AudioStream get_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_paused 为 true。另见 playing 和 get_stream_playback。

void play(from_position: float = 0.0) 🔗

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

void seek(to_position: float) 🔗

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

void stop() 🔗

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