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。