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

AudioStreamWAV

继承： AudioStream < Resource < RefCounted < Object

存储从 WAV 文件加载的音频数据。

描述

AudioStreamWAV 存储从 WAV 文件加载的声音样本。要播放存储的声音，请使用 AudioStreamPlayer（用于非空间定位音频）或 AudioStreamPlayer2D/AudioStreamPlayer3D（用于空间定位音频）。声音可以循环播放。

这个类还可用于存储动态生成的 PCM 音频数据。另见 AudioStreamGenerator 以了解程序化音频生成。

教程

运行时文件加载与保存

属性

PackedByteArray	data	`PackedByteArray()`
Format	format	`0`
int	loop_begin	`0`
int	loop_end	`0`
LoopMode	loop_mode	`0`
int	mix_rate	`44100`
bool	stereo	`false`

方法

AudioStreamWAV	load_from_buffer(stream_data: PackedByteArray, options: Dictionary = {}) static
AudioStreamWAV	load_from_file(path: String, options: Dictionary = {}) static
Error	save_to_wav(path: String)

枚举

enum Format: 🔗

Format FORMAT_8_BITS = 0

8 位 PCM 音频编解码器。

Format FORMAT_16_BITS = 1

16 位 PCM 音频编解码器。

Format FORMAT_IMA_ADPCM = 2

音频按照 IMA ADPCM 进行有损压缩。

Format FORMAT_QOA = 3

音频按照 Quite OK Audio 进行有损压缩。

enum LoopMode: 🔗

LoopMode LOOP_DISABLED = 0

音频不循环。

LoopMode LOOP_FORWARD = 1

音频在 loop_begin 和 loop_end 之间循环数据，仅向前播放。

LoopMode LOOP_PINGPONG = 2

音频在 loop_begin 和 loop_end 之间循环数据，来回播放。

LoopMode LOOP_BACKWARD = 3

音频在 loop_begin 和 loop_end 之间循环数据，仅向后播放。

属性说明

PackedByteArray data = PackedByteArray() 🔗

void set_data(value: PackedByteArray)
PackedByteArray get_data()

包含音频的字节数据。

注意：如果 format 为 FORMAT_8_BITS，该属性应为带符号 8 位 PCM 数据。从无符号 8 位 PCM 数据转换时，请将每个字节减去 128。

注意：如果 format 为 FORMAT_QOA，该属性应为完整 QOA 文件的数据。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.

Format format = 0 🔗

void set_format(value: Format)
Format get_format()

音频格式。取值见 Format 常量。

int loop_begin = 0 🔗

void set_loop_begin(value: int)
int get_loop_begin()

循环起始点（单位为采样数，相对于该流开头）。

int loop_end = 0 🔗

void set_loop_end(value: int)
int get_loop_end()

循环结束点（单位为采样数，相对于该流开头）。

LoopMode loop_mode = 0 🔗

void set_loop_mode(value: LoopMode)
LoopMode get_loop_mode()

循环模式。取值见 LoopMode 常量。

int mix_rate = 44100 🔗

void set_mix_rate(value: int)
int get_mix_rate()

混合这个音频的采样率。更高的数值需要更多的存储空间，但会带来更好的质量。

在游戏中，常用的采样率有 11025、16000、22050、32000、44100、48000。

根据奈奎斯特–香农采样定理，当超过 40000 赫兹时，人类的听觉没有质量上的差别（因为大多数人只能听到 ~20000 赫兹，往往更少）。如果你要使用语音等音高较低的声音，则可以使用 32000 或 22050 等较低的采样率，不会降低质量。

bool stereo = false 🔗

void set_stereo(value: bool)
bool is_stereo()

如果为 true，则音频为立体声。

方法说明

AudioStreamWAV load_from_buffer(stream_data: PackedByteArray, options: Dictionary = {}) static 🔗

从给定缓冲区新建 AudioStreamWAV 实例。缓冲区中必须包含 WAV 数据。

options 中的键值对与 ResourceImporterWAV 的属性对应。options 的用法与 load_from_file() 一致。

AudioStreamWAV load_from_file(path: String, options: Dictionary = {}) static 🔗

从给定的文件路径新建 AudioStreamWAV 实例。文件必须为 WAV 格式。

options 中的键值对与 ResourceImporterWAV 的属性对应。

示例：将拖放的第一个文件作为 WAV 加载并播放：

@onready var audio_player = $AudioStreamPlayer

func _ready():
    get_window().files_dropped.connect(_on_files_dropped)

func _on_files_dropped(files):
    if files[0].get_extension() == "wav":
        audio_player.stream = AudioStreamWAV.load_from_file(files[0], {
                "force/max_rate": true,
                "force/max_rate_hz": 11025
            })
        audio_player.play()

Error save_to_wav(path: String) 🔗

将 AudioStreamWAV 作为 WAV 文件保存到 path。无法保存 IMA ADPCM 或 Quite OK Audio 格式的样本。

注意：如果缺少 .wav 扩展名，则会自动将其追加到 path。