AudioStreamPlayer

继承： Node < Object

用于播放音频的节点。

描述

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

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

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

教程

属性

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

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

当声音不受打断完成播放时发出。调用 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 🔗

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

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

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

bool playing = false 🔗

  • void set_playing(value: bool)

  • bool is_playing()

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

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 音量的偏移。

注意：如需在分贝和线性能量间进行转换（常见于音量滑块），请使用 volume_linear、@GlobalScope.db_to_linear() 和 @GlobalScope.linear_to_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 声音中的位置，单位为秒。如果没有正在播放的声音，则返回 0.0。

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

注意：如果 stream 是 AudioStreamInteractive，则始终返回 0.0，因为这种音频流可以同时播放多个剪辑。

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

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