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

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 🔗

混合目标声道，使用 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 🔗

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

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

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

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