AudioStreamPlayer

EVOCOSMOS2026/4/14大约 6 分钟

最后同步日期：2026-04-15 | Godot 官方原文 — AudioStreamPlayer

AudioStreamPlayer

节点继承关系

继承链：Node -> AudioStreamPlayer

继承自 Node

类型	名称	说明
属性	`Name`	节点名称
属性	`ProcessMode`	处理模式（始终 / 暂停时 / 仅编辑器）
属性	`ProcessPriority`	处理优先级，数字越小越先执行
信号	`ready`	节点进入场景树并准备就绪
信号	`tree_entered`	节点进入场景树
信号	`tree_exited`	节点完全离开场景树
方法	`GetNode<T>()`	按路径获取子节点
方法	`AddChild()`	添加子节点
方法	`RemoveChild()`	移除子节点
方法	`QueueFree()`	帧结束后释放节点
方法	`GetParent()`	获取父节点

定义

AudioStreamPlayer 是 Godot 中最基本的音频播放节点。它播放的声音没有"位置感"——不管声音从哪里发出来，听起来都一样大、一样清晰。

一句话理解：它就像一个房间里的广播喇叭，声音从四面八方同时传过来，你无法分辨声音来自哪个方向。

想象你在逛商场，商场里放着的背景音乐——你不会觉得音乐是从左边还是右边来的，它就是弥漫在整个空间里。这就是 AudioStreamPlayer 的效果。

使用频率：★★★★★ 通用高频（几乎每个游戏都需要）

节点用途

播放背景音乐（BGM）
播放 UI 音效（按钮点击、菜单打开）
播放不需要空间定位的全局音效（如得分提示音）
作为音频管理器的核心组件

使用场景

典型场景

背景音乐：游戏主菜单、战斗场景、胜利/失败画面的背景音乐。BGM 不需要位置感，它就是用来烘托气氛的。
UI 音效：点击按钮时的"嘀"声、打开背包的"沙沙"声。这些声音跟着界面走，不需要 3D 定位。
全局提示音：比如"任务完成"的提示音、成就解锁的"叮"声。无论玩家在哪里都能听到。

不适用场景

需要根据物体位置改变声音大小时，请使用：
- 2D 游戏 → AudioStreamPlayer2D
- 3D 游戏 → AudioStreamPlayer3D

常用节点搭配

搭配节点	用途	必需？
Node	作为音频管理器的容器	是
其他 AudioStreamPlayer	一个管 BGM，一个管音效	视需求
AudioEffectReverb 等效果节点	给声音加混响、回声等效果	视需求

生效必备素材/资源

资源类型	格式	说明
音频文件	`.ogg`、`.wav`、`.mp3`	需要加载为 `AudioStream` 资源才能播放

提示

推荐使用 .ogg 格式的音频文件。它是开源格式、文件体积小、音质好，Godot 对它的支持也最好。.wav 文件体积很大但无损，适合短音效。.mp3 有版权问题且不支持循环播放的精确控制，不推荐。

节点属性与信号

音频属性

属性	类型	默认值	继承自	说明
Stream	AudioStream?	null	—	要播放的音频资源，从文件加载后赋值给它
VolumeDb	float	0.0	—	音量（单位：分贝）。0 是原始音量，负数变小，正数变大
PitchScale	float	1.0	—	播放速度和音调的缩放。1.0 是正常速度，2.0 是两倍速（音调也变高）
Autoplay	bool	false	—	是否在场景加载后自动播放
Bus	StringName	"Master"	—	音频总线名称，控制声音走哪个输出通道
MaxPolyphony	int	1	—	同时播放的最大声音数量（同时播放同一个流的最大实例数）

播放状态属性

属性	类型	默认值	继承自	说明
Playing	bool	false	—	是否正在播放（只读，不能手动修改）
StreamPaused	bool	false	—	是否暂停播放（可以手动修改来暂停/恢复）

信号

信号	触发时机	说明
`Finished`	音频播放完毕时	非循环音频播完会触发，可用于自动切换下一首 BGM

常用方法

方法	返回值	说明
`Play(double fromPosition = 0.0)`	void	从指定位置（秒）开始播放。不传参数则从头开始
`Stop()`	void	停止播放并将进度归零
`Seek(double position)`	void	跳到指定时间点（秒），不停止播放
`GetPlaybackPosition()`	double	获取当前播放进度（秒）
`SetStreamPaused(bool paused)`	void	暂停或恢复播放（保留进度）
`IsPlaying()`	bool	判断是否正在播放

代码示例

音频管理器（BGM + 音效）

using Godot;

public partial class AudioManager : Node
{
    private AudioStreamPlayer _bgmPlayer;
    private AudioStreamPlayer _sfxPlayer;

    public override void _Ready()
    {
        // 创建两个播放器：一个管背景音乐，一个管音效
        _bgmPlayer = new AudioStreamPlayer();
        _sfxPlayer = new AudioStreamPlayer();
        AddChild(_bgmPlayer);
        AddChild(_sfxPlayer);

        // 设置 BGM 音量比原始音量小 10 分贝（听起来柔和一些）
        _bgmPlayer.VolumeDb = -10.0f;

        // 加载并播放背景音乐
        var bgmStream = GD.Load<AudioStream>("res://assets/audio/bgm_main.ogg");
        _bgmPlayer.Stream = bgmStream;
        _bgmPlayer.Play();

        // 监听 BGM 播放完毕信号
        _bgmPlayer.Finished += OnBgmFinished;
    }

    /// <summary>
    /// 播放指定路径的音效
    /// </summary>
    public void PlaySfx(string path)
    {
        var sfxStream = GD.Load<AudioStream>(path);
        _sfxPlayer.Stream = sfxStream;
        _sfxPlayer.Play();
    }

    /// <summary>
    /// 播放按钮点击音效
    /// </summary>
    public void PlayClickSound()
    {
        _sfxPlayer.Stream = GD.Load<AudioStream>("res://assets/audio/click.ogg");
        _sfxPlayer.Play();
    }

    /// <summary>
    /// 暂停/恢复 BGM
    /// </summary>
    public void ToggleBgm()
    {
        _bgmPlayer.StreamPaused = !_bgmPlayer.StreamPaused;
    }

    /// <summary>
    /// 调整 BGM 音量
    /// </summary>
    public void SetBgmVolume(float volumeDb)
    {
        _bgmPlayer.VolumeDb = Mathf.Clamp(volumeDb, -80.0f, 24.0f);
    }

    private void OnBgmFinished()
    {
        GD.Print("背景音乐播放完毕");
    }
}

GDScript

extends Node

var _bgm_player: AudioStreamPlayer
var _sfx_player: AudioStreamPlayer

func _ready():
    # 创建两个播放器：一个管背景音乐，一个管音效
    _bgm_player = AudioStreamPlayer.new()
    _sfx_player = AudioStreamPlayer.new()
    add_child(_bgm_player)
    add_child(_sfx_player)

    # 设置 BGM 音量比原始音量小 10 分贝（听起来柔和一些）
    _bgm_player.volume_db = -10.0

    # 加载并播放背景音乐
    var bgm_stream = load("res://assets/audio/bgm_main.ogg")
    _bgm_player.stream = bgm_stream
    _bgm_player.play()

    # 监听 BGM 播放完毕信号
    _bgm_player.finished.connect(_on_bgm_finished)

## 播放指定路径的音效
func play_sfx(path: String):
    var sfx_stream = load(path)
    _sfx_player.stream = sfx_stream
    _sfx_player.play()

## 播放按钮点击音效
func play_click_sound():
    _sfx_player.stream = load("res://assets/audio/click.ogg")
    _sfx_player.play()

## 暂停/恢复 BGM
func toggle_bgm():
    _bgm_player.stream_paused = !_bgm_player.stream_paused

## 调整 BGM 音量
func set_bgm_volume(volume_db: float):
    _bgm_player.volume_db = clampf(volume_db, -80.0, 24.0)

func _on_bgm_finished():
    print("背景音乐播放完毕")

渐入渐出背景音乐

using Godot;

public partial class BgmFader : Node
{
    private AudioStreamPlayer _player;
    private Tween _tween;

    public override void _Ready()
    {
        _player = GetNode<AudioStreamPlayer>("AudioStreamPlayer");
        _player.Stream = GD.Load<AudioStream>("res://assets/audio/bgm_main.ogg");
        _player.VolumeDb = -80.0f; // 先静音
        _player.Play();
    }

    /// <summary>
    /// 淡入 BGM（从静音到目标音量）
    /// </summary>
    public void FadeIn(float duration = 2.0f, float targetDb = -10.0f)
    {
        _tween?.Kill();
        _tween = CreateTween();
        _tween.TweenProperty(_player, "volume_db", targetDb, duration);
    }

    /// <summary>
    /// 淡出 BGM（从当前音量到静音）
    /// </summary>
    public void FadeOut(float duration = 1.0f)
    {
        _tween?.Kill();
        _tween = CreateTween();
        _tween.TweenProperty(_player, "volume_db", -80.0f, duration);
    }
}

GDScript

extends Node

@onready var _player: AudioStreamPlayer = $AudioStreamPlayer
var _tween: Tween

func _ready():
    _player.stream = load("res://assets/audio/bgm_main.ogg")
    _player.volume_db = -80.0  # 先静音
    _player.play()

## 淡入 BGM（从静音到目标音量）
func fade_in(duration: float = 2.0, target_db: float = -10.0):
    if _tween:
        _tween.kill()
    _tween = create_tween()
    _tween.tween_property(_player, "volume_db", target_db, duration)

## 淡出 BGM（从当前音量到静音）
func fade_out(duration: float = 1.0):
    if _tween:
        _tween.kill()
    _tween = create_tween()
    _tween.tween_property(_player, "volume_db", -80.0, duration)