Nixyri/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2024-11-24 13:12:42 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #96174 from DeeJayLSP/wav-docs

Browse Source 
WAV stream/importer: Improve compression/loop names and descriptions
This commit is contained in:
Rémi Verschelde 2024-08-30 23:37:50 +02:00
commit 77bc419071
No known key found for this signature in database
GPG Key ID: C3336907360768E1
5 changed files with 22 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/classes/AudioStreamWAV.xml
View File

@ -15,7 +15,7 @@
<return type="int" enum="Error" />
<param index="0" name="path" type="String" />
<description>
Saves the AudioStreamWAV as a WAV file to [param path]. Samples with IMA ADPCM or QOA formats can't be saved.
Saves the AudioStreamWAV as a WAV file to [param path]. Samples with IMA ADPCM or Quite OK Audio formats can't be saved.
[b]Note:[/b] A [code].wav[/code] extension is automatically appended to [param path] if it is missing.
</description>
</method>
@ -23,19 +23,20 @@
<members>
<member name="data" type="PackedByteArray" setter="set_data" getter="get_data" default="PackedByteArray()">
Contains the audio data in bytes.
[b]Note:[/b] This property expects signed PCM8 data. To convert unsigned PCM8 to signed PCM8, subtract 128 from each byte.
[b]Note:[/b] If [member format] is set to [constant FORMAT_8_BITS], this property expects signed 8-bit PCM data. To convert from unsigned 8-bit PCM, subtract 128 from each byte.
[b]Note:[/b] If [member format] is set to [constant FORMAT_QOA], this property expects data from a full QOA file.
</member>
<member name="format" type="int" setter="set_format" getter="get_format" enum="AudioStreamWAV.Format" default="0">
Audio format. See [enum Format] constants for values.
</member>
<member name="loop_begin" type="int" setter="set_loop_begin" getter="get_loop_begin" default="0">
The loop start point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present.
The loop start point (in number of samples, relative to the beginning of the stream).
</member>
<member name="loop_end" type="int" setter="set_loop_end" getter="get_loop_end" default="0">
The loop end point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present.
The loop end point (in number of samples, relative to the beginning of the stream).
</member>
<member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="AudioStreamWAV.LoopMode" default="0">
The loop mode. This information will be imported automatically from the WAV file if present. See [enum LoopMode] constants for values.
The loop mode. See [enum LoopMode] constants for values.
</member>
<member name="mix_rate" type="int" setter="set_mix_rate" getter="get_mix_rate" default="44100">
The sample rate for mixing this audio. Higher values require more storage space, but result in better quality.
@ -48,16 +49,16 @@
</members>
<constants>
<constant name="FORMAT_8_BITS" value="0" enum="Format">
8-bit audio codec.
8-bit PCM audio codec.
</constant>
<constant name="FORMAT_16_BITS" value="1" enum="Format">
16-bit audio codec.
16-bit PCM audio codec.
</constant>
<constant name="FORMAT_IMA_ADPCM" value="2" enum="Format">
Audio is compressed using IMA ADPCM.
Audio is lossily compressed as IMA ADPCM.
</constant>
<constant name="FORMAT_QOA" value="3" enum="Format">
Audio is compressed as QOA ([url=https://qoaformat.org/]Quite OK Audio[/url]).
Audio is lossily compressed as [url=https://qoaformat.org/]Quite OK Audio[/url].
</constant>
<constant name="LOOP_DISABLED" value="0" enum="LoopMode">
Audio does not loop.

17
doc/classes/ResourceImporterWAV.xml
View File

@ -12,9 +12,9 @@
<members>
<member name="compress/mode" type="int" setter="" getter="" default="0">
The compression mode to use on import.
[b]Disabled:[/b] Imports audio data without any compression. This results in the highest possible quality.
[b]RAM (Ima-ADPCM):[/b] Performs fast lossy compression on import. Low CPU cost, but quality is noticeably decreased compared to Ogg Vorbis or even MP3.
[b]QOA ([url=https://qoaformat.org/]Quite OK Audio[/url]):[/b] Performs lossy compression on import. CPU cost is slightly higher than IMA-ADPCM, but quality is much higher.
- [b]PCM (Uncompressed):[/b] Imports audio data without any form of compression, preserving the highest possible quality. It has the lowest CPU cost, but the highest memory usage.
- [b]IMA ADPCM:[/b] Applies fast, lossy compression during import, noticeably decreasing the quality, but with low CPU cost and memory usage. Does not support seeking and only Forward loop mode is supported.
- [b][url=https://qoaformat.org/]Quite OK Audio[/url]:[/b] Also applies lossy compression on import, having a slightly higher CPU cost compared to IMA ADPCM, but much higher quality and the lowest memory usage.
</member>
<member name="edit/loop_begin" type="int" setter="" getter="" default="0">
The begin loop point to use when [member edit/loop_mode] is [b]Forward[/b], [b]Ping-Pong[/b], or [b]Backward[/b]. This is set in samples after the beginning of the audio file.
@ -23,11 +23,12 @@
The end loop point to use when [member edit/loop_mode] is [b]Forward[/b], [b]Ping-Pong[/b], or [b]Backward[/b]. This is set in samples after the beginning of the audio file. A value of [code]-1[/code] uses the end of the audio file as the end loop point.
</member>
<member name="edit/loop_mode" type="int" setter="" getter="" default="0">
Controls how audio should loop. This is automatically read from the WAV metadata on import.
[b]Disabled:[/b] Don't loop audio, even if metadata indicates the file should be played back looping.
[b]Forward:[/b] Standard audio looping.
[b]Ping-Pong:[/b] Play audio forward until it's done playing, then play it backward and repeat. This is similar to mirrored texture repeat, but for audio.
[b]Backward:[/b] Play audio in reverse and loop back to the end when done playing.
Controls how audio should loop.
- [b]Detect From WAV:[/b] Uses loop information from the WAV metadata.
- [b]Disabled:[/b] Don't loop audio, even if the metadata indicates the file playback should loop.
- [b]Forward:[/b] Standard audio looping. Plays the audio forward from the beginning to [member edit/loop_end], then returns to [member edit/loop_begin] and repeats.
- [b]Ping-Pong:[/b] Plays the audio forward until [member edit/loop_end], then backwards to [member edit/loop_begin], repeating this cycle.
- [b]Backward:[/b] Plays the audio backwards from [member edit/loop_end] to [member edit/loop_begin], then repeats.
[b]Note:[/b] In [AudioStreamPlayer], the [signal AudioStreamPlayer.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.
</member>
<member name="edit/normalize" type="bool" setter="" getter="" default="false">

2
editor/import/resource_importer_wav.cpp
View File

@ -90,7 +90,7 @@ void ResourceImporterWAV::get_import_options(const String &p_path, List<ImportOp
r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "edit/loop_mode", PROPERTY_HINT_ENUM, "Detect From WAV,Disabled,Forward,Ping-Pong,Backward", PROPERTY_USAGE_DEFAULT | PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED), 0));
r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "edit/loop_begin"), 0));
r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "edit/loop_end"), -1));
r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "compress/mode", PROPERTY_HINT_ENUM, "Disabled,RAM (Ima-ADPCM),QOA (Quite OK Audio)"), 0));
r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "compress/mode", PROPERTY_HINT_ENUM, "PCM (Uncompressed),IMA ADPCM,Quite OK Audio"), 0));
}
Error ResourceImporterWAV::import(const String &p_source_file, const String &p_save_path, const HashMap<StringName, Variant> &p_options, List<String> *r_platform_variants, List<String> *r_gen_files, Variant *r_metadata) {

2
scene/resources/audio_stream_wav.cpp
View File

@ -760,7 +760,7 @@ void AudioStreamWAV::_bind_methods() {
ClassDB::bind_method(D_METHOD("save_to_wav", "path"), &AudioStreamWAV::save_to_wav);
ADD_PROPERTY(PropertyInfo(Variant::PACKED_BYTE_ARRAY, "data", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NO_EDITOR), "set_data", "get_data");
ADD_PROPERTY(PropertyInfo(Variant::INT, "format", PROPERTY_HINT_ENUM, "8-Bit,16-Bit,IMA-ADPCM,QOA"), "set_format", "get_format");
ADD_PROPERTY(PropertyInfo(Variant::INT, "format", PROPERTY_HINT_ENUM, "8-Bit,16-Bit,IMA ADPCM,Quite OK Audio"), "set_format", "get_format");
ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_mode", PROPERTY_HINT_ENUM, "Disabled,Forward,Ping-Pong,Backward"), "set_loop_mode", "get_loop_mode");
ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_begin"), "set_loop_begin", "get_loop_begin");
ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_end"), "set_loop_end", "get_loop_end");

2
servers/audio/effects/audio_effect_record.cpp
View File

@ -283,7 +283,7 @@ void AudioEffectRecord::_bind_methods() {
ClassDB::bind_method(D_METHOD("get_format"), &AudioEffectRecord::get_format);
ClassDB::bind_method(D_METHOD("get_recording"), &AudioEffectRecord::get_recording);
ADD_PROPERTY(PropertyInfo(Variant::INT, "format", PROPERTY_HINT_ENUM, "8-Bit,16-Bit,IMA-ADPCM"), "set_format", "get_format");
ADD_PROPERTY(PropertyInfo(Variant::INT, "format", PROPERTY_HINT_ENUM, "8-Bit,16-Bit,IMA ADPCM,Quite OK Audio"), "set_format", "get_format");
}
AudioEffectRecord::AudioEffectRecord() {