Merge pull request #96174 from DeeJayLSP/wav-docs

WAV stream/importer: Improve compression/loop names and descriptions

doc/classes/AudioStreamWAV.xml

@@ -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.

doc/classes/ResourceImporterWAV.xml

@@ -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]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]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]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]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][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.
+			Controls how audio should loop.
-			[b]Disabled:[/b] Don't loop audio, even if metadata indicates the file should be played back looping.
+			- [b]Detect From WAV:[/b] Uses loop information from the WAV metadata.
-			[b]Forward:[/b] Standard audio looping.
+			- [b]Disabled:[/b] Don't loop audio, even if the metadata indicates the file playback should loop.
-			[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]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]Backward:[/b] Play audio in reverse and loop back to the end when done playing.
+			- [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">

editor/import/resource_importer_wav.cpp

@@ -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) {

scene/resources/audio_stream_wav.cpp

@@ -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");

servers/audio/effects/audio_effect_record.cpp

@@ -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() {