| github_url: | hide |
|---|
Inherits: :ref:`AudioStream<class_AudioStream>` < :ref:`Resource<class_Resource>` < :ref:`RefCounted<class_RefCounted>` < :ref:`Object<class_Object>`
Stores audio data loaded from WAV files.
AudioStreamSample stores sound samples loaded from WAV files. To play the stored sound, use an :ref:`AudioStreamPlayer<class_AudioStreamPlayer>` (for non-positional audio) or :ref:`AudioStreamPlayer2D<class_AudioStreamPlayer2D>`/:ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>` (for positional audio). The sound can be looped.
This class can also be used to store dynamically-generated PCM audio data. See also :ref:`AudioStreamGenerator<class_AudioStreamGenerator>` for procedural audio generation.
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`save_to_wav<class_AudioStreamSample_method_save_to_wav>` ( :ref:`String<class_String>` path ) |
enum Format:
- FORMAT_8_BITS = 0 --- 8-bit audio codec.
- FORMAT_16_BITS = 1 --- 16-bit audio codec.
- FORMAT_IMA_ADPCM = 2 --- Audio is compressed using IMA ADPCM.
enum LoopMode:
- LOOP_DISABLED = 0 --- Audio does not loop.
- LOOP_FORWARD = 1 --- Audio loops the data between :ref:`loop_begin<class_AudioStreamSample_property_loop_begin>` and :ref:`loop_end<class_AudioStreamSample_property_loop_end>`, playing forward only.
- LOOP_PINGPONG = 2 --- Audio loops the data between :ref:`loop_begin<class_AudioStreamSample_property_loop_begin>` and :ref:`loop_end<class_AudioStreamSample_property_loop_end>`, playing back and forth.
- LOOP_BACKWARD = 3 --- Audio loops the data between :ref:`loop_begin<class_AudioStreamSample_property_loop_begin>` and :ref:`loop_end<class_AudioStreamSample_property_loop_end>`, playing backward only.
| Default | PackedByteArray() |
| Setter | set_data(value) |
| Getter | get_data() |
Contains the audio data in bytes.
Note: This property expects signed PCM8 data. To convert unsigned PCM8 to signed PCM8, subtract 128 from each byte.
| Default | 0 |
| Setter | set_format(value) |
| Getter | get_format() |
Audio format. See :ref:`Format<enum_AudioStreamSample_Format>` constants for values.
- :ref:`int<class_int>` loop_begin
| Default | 0 |
| Setter | set_loop_begin(value) |
| Getter | get_loop_begin() |
The loop start point (in number of samples, relative to the beginning of the sample). This information will be imported automatically from the WAV file if present.
- :ref:`int<class_int>` loop_end
| Default | 0 |
| Setter | set_loop_end(value) |
| Getter | get_loop_end() |
The loop end point (in number of samples, relative to the beginning of the sample). This information will be imported automatically from the WAV file if present.
| Default | 0 |
| Setter | set_loop_mode(value) |
| Getter | get_loop_mode() |
The loop mode. This information will be imported automatically from the WAV file if present. See :ref:`LoopMode<enum_AudioStreamSample_LoopMode>` constants for values.
- :ref:`int<class_int>` mix_rate
| Default | 44100 |
| Setter | set_mix_rate(value) |
| Getter | get_mix_rate() |
The sample rate for mixing this audio. Higher values require more storage space, but result in better quality.
In games, common sample rates in use are 11025, 16000, 22050, 32000, 44100, and 48000.
According to the Nyquist-Shannon sampling theorem, there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are using lower-pitched sounds such as voices, lower sample rates such as 32000 or 22050 may be usable with no loss in quality.
- :ref:`bool<class_bool>` stereo
| Default | false |
| Setter | set_stereo(value) |
| Getter | is_stereo() |
If true, audio is stereo.
- :ref:`Error<enum_@GlobalScope_Error>` save_to_wav ( :ref:`String<class_String>` path )
Saves the AudioStreamSample as a WAV file to path. Samples with IMA ADPCM format can't be saved.
Note: A .wav extension is automatically appended to path if it is missing.