godotengine/godot-docs-l10n
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs-l10n.git synced 2026-01-04 10:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
4.x
godot-docs-l10n/classes/zh_Hant/class_audiostreamwav.rst

389 lines
16 KiB
ReStructuredText
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

:github_url: hide
.. _class_AudioStreamWAV:
AudioStreamWAV
==============
**繼承：** :ref:`AudioStream<class_AudioStream>` **<** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
儲存自 WAV 檔載入的音訊資料。
.. rst-class:: classref-introduction-group
說明
----
AudioStreamWAV 會儲存自 WAV 檔載入的聲音取樣。播放時可使用 :ref:`AudioStreamPlayer<class_AudioStreamPlayer>`\ （非空間定位）或 :ref:`AudioStreamPlayer2D<class_AudioStreamPlayer2D>`/:ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>`\ （空間定位）。聲音可設定為循環播放。
此類別亦可用於儲存動態產生的 PCM 音訊。程式化音訊請參閱 :ref:`AudioStreamGenerator<class_AudioStreamGenerator>`\ 。
.. rst-class:: classref-introduction-group
教學
----
- :doc:`執行時檔案載入與儲存 <../tutorials/io/runtime_file_loading_and_saving>`
.. rst-class:: classref-reftable-group
屬性
----
.. table::
:widths: auto
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`PackedByteArray<class_PackedByteArray>` | :ref:`data<class_AudioStreamWAV_property_data>` | ``PackedByteArray()`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`Format<enum_AudioStreamWAV_Format>` | :ref:`format<class_AudioStreamWAV_property_format>` | ``0`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>` | :ref:`loop_begin<class_AudioStreamWAV_property_loop_begin>` | ``0`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>` | :ref:`loop_end<class_AudioStreamWAV_property_loop_end>` | ``0`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` | :ref:`loop_mode<class_AudioStreamWAV_property_loop_mode>` | ``0`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>` | :ref:`mix_rate<class_AudioStreamWAV_property_mix_rate>` | ``44100`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`bool<class_bool>` | :ref:`stereo<class_AudioStreamWAV_property_stereo>` | ``false`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
| :ref:`Dictionary<class_Dictionary>` | :ref:`tags<class_AudioStreamWAV_property_tags>` | ``{}`` |
+-----------------------------------------------+-------------------------------------------------------------+-----------------------+
.. rst-class:: classref-reftable-group
方法
----
.. table::
:widths: auto
+---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`AudioStreamWAV<class_AudioStreamWAV>` | :ref:`load_from_buffer<class_AudioStreamWAV_method_load_from_buffer>`\ (\ stream_data\: :ref:`PackedByteArray<class_PackedByteArray>`, options\: :ref:`Dictionary<class_Dictionary>` = {}\ ) |static| |
+---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`AudioStreamWAV<class_AudioStreamWAV>` | :ref:`load_from_file<class_AudioStreamWAV_method_load_from_file>`\ (\ path\: :ref:`String<class_String>`, options\: :ref:`Dictionary<class_Dictionary>` = {}\ ) |static| |
+---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`save_to_wav<class_AudioStreamWAV_method_save_to_wav>`\ (\ path\: :ref:`String<class_String>`\ ) |
+---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
列舉
----
.. _enum_AudioStreamWAV_Format:
.. rst-class:: classref-enumeration
enum **Format**: :ref:`🔗<enum_AudioStreamWAV_Format>`
.. _class_AudioStreamWAV_constant_FORMAT_8_BITS:
.. rst-class:: classref-enumeration-constant
:ref:`Format<enum_AudioStreamWAV_Format>` **FORMAT_8_BITS** = ``0``
8 位元 PCM 音訊編碼。
.. _class_AudioStreamWAV_constant_FORMAT_16_BITS:
.. rst-class:: classref-enumeration-constant
:ref:`Format<enum_AudioStreamWAV_Format>` **FORMAT_16_BITS** = ``1``
16 位元 PCM 音訊編碼。
.. _class_AudioStreamWAV_constant_FORMAT_IMA_ADPCM:
.. rst-class:: classref-enumeration-constant
:ref:`Format<enum_AudioStreamWAV_Format>` **FORMAT_IMA_ADPCM** = ``2``
音訊以 IMA ADPCM 有損壓縮。
.. _class_AudioStreamWAV_constant_FORMAT_QOA:
.. rst-class:: classref-enumeration-constant
:ref:`Format<enum_AudioStreamWAV_Format>` **FORMAT_QOA** = ``3``
音訊以 `Quite OK Audio <https://qoaformat.org/>`__ 有損壓縮。
.. rst-class:: classref-item-separator
----
.. _enum_AudioStreamWAV_LoopMode:
.. rst-class:: classref-enumeration
enum **LoopMode**: :ref:`🔗<enum_AudioStreamWAV_LoopMode>`
.. _class_AudioStreamWAV_constant_LOOP_DISABLED:
.. rst-class:: classref-enumeration-constant
:ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` **LOOP_DISABLED** = ``0``
音訊不循環。
.. _class_AudioStreamWAV_constant_LOOP_FORWARD:
.. rst-class:: classref-enumeration-constant
:ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` **LOOP_FORWARD** = ``1``
音訊在 :ref:`loop_begin<class_AudioStreamWAV_property_loop_begin>` 與 :ref:`loop_end<class_AudioStreamWAV_property_loop_end>` 之間循環，僅向前播放。
.. _class_AudioStreamWAV_constant_LOOP_PINGPONG:
.. rst-class:: classref-enumeration-constant
:ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` **LOOP_PINGPONG** = ``2``
音訊在 :ref:`loop_begin<class_AudioStreamWAV_property_loop_begin>` 與 :ref:`loop_end<class_AudioStreamWAV_property_loop_end>` 之間循環，來回播放。
.. _class_AudioStreamWAV_constant_LOOP_BACKWARD:
.. rst-class:: classref-enumeration-constant
:ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` **LOOP_BACKWARD** = ``3``
音訊在 :ref:`loop_begin<class_AudioStreamWAV_property_loop_begin>` 與 :ref:`loop_end<class_AudioStreamWAV_property_loop_end>` 之間循環，僅向後播放。
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
屬性說明
--------
.. _class_AudioStreamWAV_property_data:
.. rst-class:: classref-property
:ref:`PackedByteArray<class_PackedByteArray>` **data** = ``PackedByteArray()`` :ref:`🔗<class_AudioStreamWAV_property_data>`
.. rst-class:: classref-property-setget
- |void| **set_data**\ (\ value\: :ref:`PackedByteArray<class_PackedByteArray>`\ )
- :ref:`PackedByteArray<class_PackedByteArray>` **get_data**\ (\ )
以位元組形式儲存音訊資料。
\ **注意：** 若 :ref:`format<class_AudioStreamWAV_property_format>` 為 :ref:`FORMAT_8_BITS<class_AudioStreamWAV_constant_FORMAT_8_BITS>`\ ，此屬性應為有號 8 位元 PCM；若來源為無號 8 位元 PCM，請對每個位元組減去 128。
\ **注意：** 若 :ref:`format<class_AudioStreamWAV_property_format>` 為 :ref:`FORMAT_QOA<class_AudioStreamWAV_constant_FORMAT_QOA>`\ ，此屬性需包含完整 QOA 檔的資料。
**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedByteArray<class_PackedByteArray>` for more details.
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_format:
.. rst-class:: classref-property
:ref:`Format<enum_AudioStreamWAV_Format>` **format** = ``0`` :ref:`🔗<class_AudioStreamWAV_property_format>`
.. rst-class:: classref-property-setget
- |void| **set_format**\ (\ value\: :ref:`Format<enum_AudioStreamWAV_Format>`\ )
- :ref:`Format<enum_AudioStreamWAV_Format>` **get_format**\ (\ )
音訊格式。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_loop_begin:
.. rst-class:: classref-property
:ref:`int<class_int>` **loop_begin** = ``0`` :ref:`🔗<class_AudioStreamWAV_property_loop_begin>`
.. rst-class:: classref-property-setget
- |void| **set_loop_begin**\ (\ value\: :ref:`int<class_int>`\ )
- :ref:`int<class_int>` **get_loop_begin**\ (\ )
迴圈起始點（樣本數，相對於串流開頭）。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_loop_end:
.. rst-class:: classref-property
:ref:`int<class_int>` **loop_end** = ``0`` :ref:`🔗<class_AudioStreamWAV_property_loop_end>`
.. rst-class:: classref-property-setget
- |void| **set_loop_end**\ (\ value\: :ref:`int<class_int>`\ )
- :ref:`int<class_int>` **get_loop_end**\ (\ )
迴圈結束點（樣本數，相對於串流開頭）。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_loop_mode:
.. rst-class:: classref-property
:ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` **loop_mode** = ``0`` :ref:`🔗<class_AudioStreamWAV_property_loop_mode>`
.. rst-class:: classref-property-setget
- |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode<enum_AudioStreamWAV_LoopMode>`\ )
- :ref:`LoopMode<enum_AudioStreamWAV_LoopMode>` **get_loop_mode**\ (\ )
迴圈模式。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_mix_rate:
.. rst-class:: classref-property
:ref:`int<class_int>` **mix_rate** = ``44100`` :ref:`🔗<class_AudioStreamWAV_property_mix_rate>`
.. rst-class:: classref-property-setget
- |void| **set_mix_rate**\ (\ value\: :ref:`int<class_int>`\ )
- :ref:`int<class_int>` **get_mix_rate**\ (\ )
此音訊的混音取樣率。取樣率越高佔用空間越大，但品質也越好。
遊戲常見的取樣率包括 ``11025``\ 、\ ``16000``\ 、\ ``22050``\ 、\ ``32000``\ 、\ ``44100`` 與 ``48000``\ 。
依 `奈奎斯特–香農取樣定理 <https://zh.wikipedia.org/wiki/奈奎斯特%E2%80%93香農取樣定理>`__\ ，超過 40 kHz 對人耳無額外差異（大多數人只能聽到約 20 kHz 或更低）。若為人聲等低頻音效，\ ``32000`` 或 ``22050`` 等較低取樣率即可不失真。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_stereo:
.. rst-class:: classref-property
:ref:`bool<class_bool>` **stereo** = ``false`` :ref:`🔗<class_AudioStreamWAV_property_stereo>`
.. rst-class:: classref-property-setget
- |void| **set_stereo**\ (\ value\: :ref:`bool<class_bool>`\ )
- :ref:`bool<class_bool>` **is_stereo**\ (\ )
若為 ``true``\ ，音訊為立體聲。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_property_tags:
.. rst-class:: classref-property
:ref:`Dictionary<class_Dictionary>` **tags** = ``{}`` :ref:`🔗<class_AudioStreamWAV_property_tags>`
.. rst-class:: classref-property-setget
- |void| **set_tags**\ (\ value\: :ref:`Dictionary<class_Dictionary>`\ )
- :ref:`Dictionary<class_Dictionary>` **get_tags**\ (\ )
如果 WAV 資料中含有自訂標籤，則會存於此屬性。
常見標籤包含 ``title``\ 、\ ``artist``\ 、\ ``album``\ 、\ ``tracknumber`` 與 ``date``\ （\ ``date`` 無固定格式）。
\ **注意：** 不保證每個檔案都含有任何特定標籤，請先檢查鍵值是否存在。
\ **注意：** 目前僅支援使用 ``LIST`` 區塊且識別碼為 ``INFO`` 的 WAV 標籤。
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
方法說明
--------
.. _class_AudioStreamWAV_method_load_from_buffer:
.. rst-class:: classref-method
:ref:`AudioStreamWAV<class_AudioStreamWAV>` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray<class_PackedByteArray>`, options\: :ref:`Dictionary<class_Dictionary>` = {}\ ) |static| :ref:`🔗<class_AudioStreamWAV_method_load_from_buffer>`
從給定緩衝區建立新的 **AudioStreamWAV** 實例，緩衝區內容必須為 WAV 資料。
\ ``options`` 的鍵和值對應 :ref:`ResourceImporterWAV<class_ResourceImporterWAV>` 的屬性，其用法與 :ref:`load_from_file()<class_AudioStreamWAV_method_load_from_file>` 相同。
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_method_load_from_file:
.. rst-class:: classref-method
:ref:`AudioStreamWAV<class_AudioStreamWAV>` **load_from_file**\ (\ path\: :ref:`String<class_String>`, options\: :ref:`Dictionary<class_Dictionary>` = {}\ ) |static| :ref:`🔗<class_AudioStreamWAV_method_load_from_file>`
從指定檔案路徑建立新的 **AudioStreamWAV** 實例，檔案必須為 WAV 格式。
\ ``options`` 的鍵和值對應 :ref:`ResourceImporterWAV<class_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()
.. rst-class:: classref-item-separator
----
.. _class_AudioStreamWAV_method_save_to_wav:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **save_to_wav**\ (\ path\: :ref:`String<class_String>`\ ) :ref:`🔗<class_AudioStreamWAV_method_save_to_wav>`
將 AudioStreamWAV 另存為 WAV 檔至 ``path``\ 。使用 IMA ADPCM 或 Quite OK Audio 的樣本無法保存。
\ **注意：** 若路徑缺少副檔名，系統會自動附加 ``.wav``\ 。
.. |virtual| replace:: :abbr:`virtual (本方法通常需要使用者覆寫才能生效。)`
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
.. |const| replace:: :abbr:`const (本方法沒有副作用。不會修改該實例的任何成員變數。)`
.. |vararg| replace:: :abbr:`vararg (本方法除了這裡描述的參數外，還可以接受任意數量的參數。)`
.. |constructor| replace:: :abbr:`constructor (本方法用於建構一個型別。)`
.. |static| replace:: :abbr:`static (本方法無需實例即可呼叫，因此可以直接使用類別名稱呼叫。)`
.. |operator| replace:: :abbr:`operator (本方法描述將本型別作為左運算元時可用的有效運算子。)`
.. |bitfield| replace:: :abbr:`BitField (此值是由下列旗標組成的位元遮罩整數。)`
.. |void| replace:: :abbr:`void (無回傳值。)`
Reference in New Issue View Git Blame Copy Permalink