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

AudioServer.set_bus_volume_db

定义

AudioServer.set_bus_volume_db 用来设置音频总线（Audio Bus）的音量大小。音频总线就像混音器上的一个通道——你可以把不同的声音分配到不同的通道上，然后分别调节每个通道的音量。

打个比方：想象一个 DJ 调音台，上面有很多推子（滑块）。每个推子控制一路声音的音量——一个管背景音乐，一个管音效，一个管语音。set_bus_volume_db 就是推拉这些推子的操作。

"db" 是"分贝"（Decibel）的缩写，是衡量声音大小的单位。0 分贝表示原始音量不变，负数表示音量减小（比如 -10 分贝大约是一半音量），-80 分贝以下基本听不见。

函数签名

C#

public static void SetBusVolumeDb(int busIdx, float volumeDb)

GDScript

func set_bus_volume_db(bus_idx: int, volume_db: float) -> void

参数说明

参数	类型	必需	说明
busIdx	int	是	音频总线的索引号。Master 总线通常是 0
volumeDb	float	是	音量值（分贝）。0 = 原始音量，负数 = 降低音量，-80 以下基本静音

常用音量值参考

分贝值	大致效果
0 dB	原始音量（最大）
-6 dB	音量减半
-10 dB	约三分之一音量
-20 dB	约十分之一音量
-40 dB	非常小
-80 dB	基本静音

返回值

无返回值（void）。设置后音量立即生效。

代码示例

基础用法：设置主总线音量

C#

// 设置 Master 总线（索引 0）的音量
AudioServer.SetBusVolumeDb(0, -10.0f);
// 运行结果: 所有声音的音量降低到约三分之一

// 恢复最大音量
AudioServer.SetBusVolumeDb(0, 0.0f);
// 运行结果: 所有声音恢复原始音量

// 基本静音
AudioServer.SetBusVolumeDb(0, -80.0f);
// 运行结果: 几乎听不到任何声音

GDScript

# 设置 Master 总线（索引 0）的音量
AudioServer.set_bus_volume_db(0, -10.0)
# 运行结果: 所有声音的音量降低到约三分之一

# 恢复最大音量
AudioServer.set_bus_volume_db(0, 0.0)
# 运行结果: 所有声音恢复原始音量

# 基本静音
AudioServer.set_bus_volume_db(0, -80.0)
# 运行结果: 几乎听不到任何声音

实际场景：音量设置滑块

C#

using Godot;

public partial class VolumeSlider : HSlider
{
    [Export] public string ExBusName = "Master";

    private int _busIndex;

    public override void _Ready()
    {
        _busIndex = AudioServer.GetBusIndex(ExBusName);

        // 把滑块范围设为 -40 到 0（分贝）
        MinValue = -40.0;
        MaxValue = 0.0;
        Step = 1.0;

        // 初始化滑块位置为当前音量
        Value = AudioServer.GetBusVolumeDb(_busIndex);
    }

    public override void _Ready()
    {
    }

    public void OnValueChanged(float value)
    {
        AudioServer.SetBusVolumeDb(_busIndex, value);
        // 运行结果: 拖动滑块时实时调整对应总线的音量
    }
}

GDScript

extends HSlider

@export var bus_name: String = "Master"

var _bus_index: int

func _ready():
    _bus_index = AudioServer.get_bus_index(bus_name)

    # 把滑块范围设为 -40 到 0（分贝）
    min_value = -40.0
    max_value = 0.0
    step = 1.0

    # 初始化滑块位置为当前音量
    value = AudioServer.get_bus_volume_db(_bus_index)

func _on_value_changed(value):
    AudioServer.set_bus_volume_db(_bus_index, value)
    # 运行结果: 拖动滑块时实时调整对应总线的音量

进阶用法：通过总线名称管理多个音量通道

C#

using Godot;

public partial class AudioManager : Node
{
    private int _masterBus;
    private int _bgmBus;
    private int _sfxBus;

    public override void _Ready()
    {
        _masterBus = AudioServer.GetBusIndex("Master");
        _bgmBus = AudioServer.GetBusIndex("BGM");
        _sfxBus = AudioServer.GetBusIndex("SFX");

        // 从配置中读取音量设置
        float masterVol = (float)Config.GetSetting("audio", "master_volume", 0.0);
        float bgmVol = (float)Config.GetSetting("audio", "bgm_volume", -6.0);
        float sfxVol = (float)Config.GetSetting("audio", "sfx_volume", 0.0);

        AudioServer.SetBusVolumeDb(_masterBus, masterVol);
        AudioServer.SetBusVolumeDb(_bgmBus, bgmVol);
        AudioServer.SetBusVolumeDb(_sfxBus, sfxVol);

        // 运行结果: 根据配置设置三个音频通道的音量
        GD.Print($"音量设置完成 - Master: {masterVol}dB, BGM: {bgmVol}dB, SFX: {sfxVol}dB");
    }

    public void MuteAll()
    {
        AudioServer.SetBusVolumeDb(_masterBus, -80.0f);
        // 运行结果: 所有声音静音
    }

    public void UnmuteAll(float volume = 0.0f)
    {
        AudioServer.SetBusVolumeDb(_masterBus, volume);
        // 运行结果: 恢复所有声音
    }
}

// 辅助配置类（示意）
public static class Config
{
    public static Variant GetSetting(string section, string key, Variant defaultValue)
    {
        return defaultValue;
    }
}

GDScript

extends Node

var _master_bus: int
var _bgm_bus: int
var _sfx_bus: int

func _ready():
    _master_bus = AudioServer.get_bus_index("Master")
    _bgm_bus = AudioServer.get_bus_index("BGM")
    _sfx_bus = AudioServer.get_bus_index("SFX")

    # 设置默认音量
    AudioServer.set_bus_volume_db(_master_bus, 0.0)
    AudioServer.set_bus_volume_db(_bgm_bus, -6.0)
    AudioServer.set_bus_volume_db(_sfx_bus, 0.0)

    # 运行结果: 三个音频通道的音量分别设置完毕
    print("音量设置完成 - Master: 0dB, BGM: -6dB, SFX: 0dB")

func mute_all():
    AudioServer.set_bus_volume_db(_master_bus, -80.0)
    # 运行结果: 所有声音静音

func unmute_all(volume: float = 0.0):
    AudioServer.set_bus_volume_db(_master_bus, volume)
    # 运行结果: 恢复所有声音

注意事项

• 分贝不是线性关系：分贝是对数单位。-6 dB 大约是音量减半，而不是减少 6%。要从线性值（0.0-1.0）转换为分贝，可以用公式 volume_db = 20 * log(linear) 或使用 Godot 提供的 Mathf.LinearToDb() 方法。
• 总线索引 vs 总线名称：可以用 AudioServer.GetBusIndex("BGM") 通过名称查找总线索引。默认情况下 Godot 只有一个 "Master" 总线（索引 0），额外的总线需要在项目设置的音频部分或 AudioBusLayout 中添加。
• 不影响实际音频数据：调节音量只是改变播放时的增益，不会修改原始音频文件。
• 配合 SetBusMute 使用：如果需要完全静音，使用 AudioServer.SetBusMute(busIdx, true) 比 SetBusVolumeDb(busIdx, -80) 更规范。