class_resourceimporterwav.rst 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214
  1. :github_url: hide
  2. .. DO NOT EDIT THIS FILE!!!
  3. .. Generated automatically from Godot engine sources.
  4. .. Generator: https://github.com/godotengine/godot/tree/4.3/doc/tools/make_rst.py.
  5. .. XML source: https://github.com/godotengine/godot/tree/4.3/doc/classes/ResourceImporterWAV.xml.
  6. .. _class_ResourceImporterWAV:
  7. ResourceImporterWAV
  8. ===================
  9. **Inherits:** :ref:`ResourceImporter<class_ResourceImporter>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
  10. Imports a WAV audio file for playback.
  11. .. rst-class:: classref-introduction-group
  12. Description
  13. -----------
  14. WAV is an uncompressed format, which can provide higher quality compared to Ogg Vorbis and MP3. It also has the lowest CPU cost to decode. This means high numbers of WAV sounds can be played at the same time, even on low-end deviceS.
  15. .. rst-class:: classref-introduction-group
  16. Tutorials
  17. ---------
  18. - :doc:`Importing audio samples <../tutorials/assets_pipeline/importing_audio_samples>`
  19. .. rst-class:: classref-reftable-group
  20. Properties
  21. ----------
  22. .. table::
  23. :widths: auto
  24. +---------------------------+--------------------------------------------------------------------------------+-----------+
  25. | :ref:`int<class_int>` | :ref:`compress/mode<class_ResourceImporterWAV_property_compress/mode>` | ``0`` |
  26. +---------------------------+--------------------------------------------------------------------------------+-----------+
  27. | :ref:`int<class_int>` | :ref:`edit/loop_begin<class_ResourceImporterWAV_property_edit/loop_begin>` | ``0`` |
  28. +---------------------------+--------------------------------------------------------------------------------+-----------+
  29. | :ref:`int<class_int>` | :ref:`edit/loop_end<class_ResourceImporterWAV_property_edit/loop_end>` | ``-1`` |
  30. +---------------------------+--------------------------------------------------------------------------------+-----------+
  31. | :ref:`int<class_int>` | :ref:`edit/loop_mode<class_ResourceImporterWAV_property_edit/loop_mode>` | ``0`` |
  32. +---------------------------+--------------------------------------------------------------------------------+-----------+
  33. | :ref:`bool<class_bool>` | :ref:`edit/normalize<class_ResourceImporterWAV_property_edit/normalize>` | ``false`` |
  34. +---------------------------+--------------------------------------------------------------------------------+-----------+
  35. | :ref:`bool<class_bool>` | :ref:`edit/trim<class_ResourceImporterWAV_property_edit/trim>` | ``false`` |
  36. +---------------------------+--------------------------------------------------------------------------------+-----------+
  37. | :ref:`bool<class_bool>` | :ref:`force/8_bit<class_ResourceImporterWAV_property_force/8_bit>` | ``false`` |
  38. +---------------------------+--------------------------------------------------------------------------------+-----------+
  39. | :ref:`bool<class_bool>` | :ref:`force/max_rate<class_ResourceImporterWAV_property_force/max_rate>` | ``false`` |
  40. +---------------------------+--------------------------------------------------------------------------------+-----------+
  41. | :ref:`float<class_float>` | :ref:`force/max_rate_hz<class_ResourceImporterWAV_property_force/max_rate_hz>` | ``44100`` |
  42. +---------------------------+--------------------------------------------------------------------------------+-----------+
  43. | :ref:`bool<class_bool>` | :ref:`force/mono<class_ResourceImporterWAV_property_force/mono>` | ``false`` |
  44. +---------------------------+--------------------------------------------------------------------------------+-----------+
  45. .. rst-class:: classref-section-separator
  46. ----
  47. .. rst-class:: classref-descriptions-group
  48. Property Descriptions
  49. ---------------------
  50. .. _class_ResourceImporterWAV_property_compress/mode:
  51. .. rst-class:: classref-property
  52. :ref:`int<class_int>` **compress/mode** = ``0`` :ref:`🔗<class_ResourceImporterWAV_property_compress/mode>`
  53. The compression mode to use on import.
  54. \ **Disabled:** Imports audio data without any compression. This results in the highest possible quality.
  55. \ **RAM (Ima-ADPCM):** Performs fast lossy compression on import. Low CPU cost, but quality is noticeably decreased compared to Ogg Vorbis or even MP3.
  56. \ **QOA (`Quite OK Audio <https://qoaformat.org/>`__):** Performs lossy compression on import. CPU cost is slightly higher than IMA-ADPCM, but quality is much higher.
  57. .. rst-class:: classref-item-separator
  58. ----
  59. .. _class_ResourceImporterWAV_property_edit/loop_begin:
  60. .. rst-class:: classref-property
  61. :ref:`int<class_int>` **edit/loop_begin** = ``0`` :ref:`🔗<class_ResourceImporterWAV_property_edit/loop_begin>`
  62. The begin loop point to use when :ref:`edit/loop_mode<class_ResourceImporterWAV_property_edit/loop_mode>` is **Forward**, **Ping-Pong**, or **Backward**. This is set in samples after the beginning of the audio file.
  63. .. rst-class:: classref-item-separator
  64. ----
  65. .. _class_ResourceImporterWAV_property_edit/loop_end:
  66. .. rst-class:: classref-property
  67. :ref:`int<class_int>` **edit/loop_end** = ``-1`` :ref:`🔗<class_ResourceImporterWAV_property_edit/loop_end>`
  68. The end loop point to use when :ref:`edit/loop_mode<class_ResourceImporterWAV_property_edit/loop_mode>` is **Forward**, **Ping-Pong**, or **Backward**. This is set in samples after the beginning of the audio file. A value of ``-1`` uses the end of the audio file as the end loop point.
  69. .. rst-class:: classref-item-separator
  70. ----
  71. .. _class_ResourceImporterWAV_property_edit/loop_mode:
  72. .. rst-class:: classref-property
  73. :ref:`int<class_int>` **edit/loop_mode** = ``0`` :ref:`🔗<class_ResourceImporterWAV_property_edit/loop_mode>`
  74. Controls how audio should loop. This is automatically read from the WAV metadata on import.
  75. \ **Disabled:** Don't loop audio, even if metadata indicates the file should be played back looping.
  76. \ **Forward:** Standard audio looping.
  77. \ **Ping-Pong:** Play audio forward until it's done playing, then play it backward and repeat. This is similar to mirrored texture repeat, but for audio.
  78. \ **Backward:** Play audio in reverse and loop back to the end when done playing.
  79. \ **Note:** In :ref:`AudioStreamPlayer<class_AudioStreamPlayer>`, the :ref:`AudioStreamPlayer.finished<class_AudioStreamPlayer_signal_finished>` signal won't be emitted for looping audio when it reaches the end of the audio file, as the audio will keep playing indefinitely.
  80. .. rst-class:: classref-item-separator
  81. ----
  82. .. _class_ResourceImporterWAV_property_edit/normalize:
  83. .. rst-class:: classref-property
  84. :ref:`bool<class_bool>` **edit/normalize** = ``false`` :ref:`🔗<class_ResourceImporterWAV_property_edit/normalize>`
  85. If ``true``, normalize the audio volume so that its peak volume is equal to 0 dB. When enabled, normalization will make audio sound louder depending on its original peak volume.
  86. .. rst-class:: classref-item-separator
  87. ----
  88. .. _class_ResourceImporterWAV_property_edit/trim:
  89. .. rst-class:: classref-property
  90. :ref:`bool<class_bool>` **edit/trim** = ``false`` :ref:`🔗<class_ResourceImporterWAV_property_edit/trim>`
  91. If ``true``, automatically trim the beginning and end of the audio if it's lower than -50 dB after normalization (see :ref:`edit/normalize<class_ResourceImporterWAV_property_edit/normalize>`). This prevents having files with silence at the beginning or end, which increases their size unnecessarily and adds latency to the moment they are played back. A fade-in/fade-out period of 500 samples is also used during trimming to avoid audible pops.
  92. .. rst-class:: classref-item-separator
  93. ----
  94. .. _class_ResourceImporterWAV_property_force/8_bit:
  95. .. rst-class:: classref-property
  96. :ref:`bool<class_bool>` **force/8_bit** = ``false`` :ref:`🔗<class_ResourceImporterWAV_property_force/8_bit>`
  97. If ``true``, forces the imported audio to use 8-bit quantization if the source file is 16-bit or higher.
  98. Enabling this is generally not recommended, as 8-bit quantization decreases audio quality significantly. If you need smaller file sizes, consider using Ogg Vorbis or MP3 audio instead.
  99. .. rst-class:: classref-item-separator
  100. ----
  101. .. _class_ResourceImporterWAV_property_force/max_rate:
  102. .. rst-class:: classref-property
  103. :ref:`bool<class_bool>` **force/max_rate** = ``false`` :ref:`🔗<class_ResourceImporterWAV_property_force/max_rate>`
  104. If set to a value greater than ``0``, forces the audio's sample rate to be reduced to a value lower than or equal to the value specified in :ref:`force/max_rate_hz<class_ResourceImporterWAV_property_force/max_rate_hz>`.
  105. This can decrease file size noticeably on certain sounds, without impacting quality depending on the actual sound's contents. See `Best practices <../tutorials/assets_pipeline/importing_audio_samples.html#doc-importing-audio-samples-best-practices>`__ for more information.
  106. .. rst-class:: classref-item-separator
  107. ----
  108. .. _class_ResourceImporterWAV_property_force/max_rate_hz:
  109. .. rst-class:: classref-property
  110. :ref:`float<class_float>` **force/max_rate_hz** = ``44100`` :ref:`🔗<class_ResourceImporterWAV_property_force/max_rate_hz>`
  111. The frequency to limit the imported audio sample to (in Hz). Only effective if :ref:`force/max_rate<class_ResourceImporterWAV_property_force/max_rate>` is ``true``.
  112. .. rst-class:: classref-item-separator
  113. ----
  114. .. _class_ResourceImporterWAV_property_force/mono:
  115. .. rst-class:: classref-property
  116. :ref:`bool<class_bool>` **force/mono** = ``false`` :ref:`🔗<class_ResourceImporterWAV_property_force/mono>`
  117. If ``true``, forces the imported audio to be mono if the source file is stereo. This decreases the file size by 50% by merging the two channels into one.
  118. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
  119. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
  120. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
  121. .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
  122. .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
  123. .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
  124. .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
  125. .. |void| replace:: :abbr:`void (No return value.)`