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
Dictionary	tags	{}

方法

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

音訊格式。

---

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

迴圈模式。

---

int mix_rate = 44100 🔗

• void set_mix_rate(value: int)

• int get_mix_rate()

此音訊的混音取樣率。取樣率越高佔用空間越大，但品質也越好。

遊戲常見的取樣率包括 11025、16000、22050、32000、44100 與 48000。

依 奈奎斯特–香農取樣定理，超過 40 kHz 對人耳無額外差異（大多數人只能聽到約 20 kHz 或更低）。若為人聲等低頻音效，32000 或 22050 等較低取樣率即可不失真。

---

bool stereo = false 🔗

• void set_stereo(value: bool)

• bool is_stereo()

若為 true，音訊為立體聲。

---

Dictionary tags = {} 🔗

• void set_tags(value: Dictionary)

• Dictionary get_tags()

如果 WAV 資料中含有自訂標籤，則會存於此屬性。

常見標籤包含 title、artist、album、tracknumber 與 date（date 無固定格式）。

注意： 不保證每個檔案都含有任何特定標籤，請先檢查鍵值是否存在。

注意： 目前僅支援使用 LIST 區塊且識別碼為 INFO 的 WAV 標籤。

---

方法說明

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

從給定緩衝區建立新的 AudioStreamWAV 實例，緩衝區內容必須為 WAV 資料。

options 的鍵和值對應 ResourceImporterWAV 的屬性，其用法與 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。