Merge pull request #48682 from Calinou/doc-audio-generation

Improve AudioStreamGenerator and AudioEffectSpectrumAnalyzer documentation

5 files changed, 35 insertions, 4 deletions

diff --git a/doc/classes/AudioEffectSpectrumAnalyzer.xml b/doc/classes/AudioEffectSpectrumAnalyzer.xml
index 79a8932e25..10d29ff8ab 100644
--- a/doc/classes/AudioEffectSpectrumAnalyzer.xml
+++ b/doc/classes/AudioEffectSpectrumAnalyzer.xml
@@ -1,31 +1,43 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectSpectrumAnalyzer" inherits="AudioEffect" version="4.0">
 	<brief_description>
+		Audio effect that can be used for real-time audio visualizations.
 	</brief_description>
 	<description>
+		This audio effect does not affect sound output, but can be used for real-time audio visualizations.
+		See also [AudioStreamGenerator] for procedurally generating sounds.
 	</description>
 	<tutorials>
+		<link title="https://godotengine.org/asset-library/asset/528">Audio Spectrum Demo</link>
+		<link title="https://godotengine.org/article/godot-32-will-get-new-audio-features">Godot 3.2 will get new audio features</link>
 	</tutorials>
 	<methods>
 	</methods>
 	<members>
 		<member name="buffer_length" type="float" setter="set_buffer_length" getter="get_buffer_length" default="2.0">
+			The length of the buffer to keep (in seconds). Higher values keep data around for longer, but require more memory.
 		</member>
 		<member name="fft_size" type="int" setter="set_fft_size" getter="get_fft_size" enum="AudioEffectSpectrumAnalyzer.FFTSize" default="2">
+			The size of the [url=https://en.wikipedia.org/wiki/Fast_Fourier_transform]Fast Fourier transform[/url] buffer. Higher values smooth out the spectrum analysis over time, but have greater latency. The effects of this higher latency are especially noticeable with sudden amplitude changes.
 		</member>
 		<member name="tap_back_pos" type="float" setter="set_tap_back_pos" getter="get_tap_back_pos" default="0.01">
 		</member>
 	</members>
 	<constants>
 		<constant name="FFT_SIZE_256" value="0" enum="FFTSize">
+			Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time.
 		</constant>
 		<constant name="FFT_SIZE_512" value="1" enum="FFTSize">
+			Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time.
 		</constant>
 		<constant name="FFT_SIZE_1024" value="2" enum="FFTSize">
+			Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time.
 		</constant>
 		<constant name="FFT_SIZE_2048" value="3" enum="FFTSize">
+			Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time.
 		</constant>
 		<constant name="FFT_SIZE_4096" value="4" enum="FFTSize">
+			Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time.
 		</constant>
 		<constant name="FFT_SIZE_MAX" value="5" enum="FFTSize">
 			Represents the size of the [enum FFTSize] enum.
diff --git a/doc/classes/AudioStreamGenerator.xml b/doc/classes/AudioStreamGenerator.xml
index a273beb5af..8464bc8a85 100644
--- a/doc/classes/AudioStreamGenerator.xml
+++ b/doc/classes/AudioStreamGenerator.xml
@@ -1,18 +1,27 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioStreamGenerator" inherits="AudioStream" version="4.0">
 	<brief_description>
+		Audio stream that generates sounds procedurally.
 	</brief_description>
 	<description>
+		This audio stream does not play back sounds, but expects a script to generate audio data for it instead. See also [AudioStreamGeneratorPlayback].
+		See also [AudioEffectSpectrumAnalyzer] for performing real-time audio spectrum analysis.
+		[b]Note:[/b] Due to performance constraints, this class is best used from C# or from a compiled language via GDNative. If you still want to use this class from GDScript, consider using a lower [member mix_rate] such as 11,025 Hz or 22,050 Hz.
 	</description>
 	<tutorials>
 		<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/526</link>
+		<link title="https://godotengine.org/article/godot-32-will-get-new-audio-features">Godot 3.2 will get new audio features</link>
 	</tutorials>
 	<methods>
 	</methods>
 	<members>
 		<member name="buffer_length" type="float" setter="set_buffer_length" getter="get_buffer_length" default="0.5">
+			The length of the buffer to generate (in seconds). Lower values result in less latency, but require the script to generate audio data faster, resulting in increased CPU usage and more risk for audio cracking if the CPU can't keep up.
 		</member>
 		<member name="mix_rate" type="float" setter="set_mix_rate" getter="get_mix_rate" default="44100.0">
+			The sample rate to use (in Hz). Higher values are more demanding for the CPU to generate, but result in better quality.
+			In games, common sample rates in use are [code]11025[/code], [code]16000[/code], [code]22050[/code], [code]32000[/code], [code]44100[/code], and [code]48000[/code].
+			According to the [url=https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem]Nyquist-Shannon sampling theorem[/url], 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 generating lower-pitched sounds such as voices, lower sample rates such as [code]32000[/code] or [code]22050[/code] may be usable with no loss in quality.
 		</member>
 	</members>
 	<constants>
diff --git a/doc/classes/AudioStreamGeneratorPlayback.xml b/doc/classes/AudioStreamGeneratorPlayback.xml
index cd8e8735b6..503f72a048 100644
--- a/doc/classes/AudioStreamGeneratorPlayback.xml
+++ b/doc/classes/AudioStreamGeneratorPlayback.xml
@@ -1,11 +1,14 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioStreamGeneratorPlayback" inherits="AudioStreamPlaybackResampled" version="4.0">
 	<brief_description>
+		Plays back audio generated using [AudioStreamGenerator].
 	</brief_description>
 	<description>
+		This class is meant to be used with [AudioStreamGenerator] to play back the generated audio in real-time.
 	</description>
 	<tutorials>
-		<link title="Audio generator demo project">https://github.com/godotengine/godot-demo-projects/tree/master/audio/generator</link>
+		<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/526</link>
+		<link title="https://godotengine.org/article/godot-32-will-get-new-audio-features">Godot 3.2 will get new audio features</link>
 	</tutorials>
 	<methods>
 		<method name="can_push_buffer" qualifiers="const">
@@ -14,18 +17,21 @@
 			<argument index="0" name="amount" type="int">
 			</argument>
 			<description>
+				Returns [code]true[/code] if a buffer of the size [code]amount[/code] can be pushed to the audio sample data buffer without overflowing it, [code]false[/code] otherwise.
 			</description>
 		</method>
 		<method name="clear_buffer">
 			<return type="void">
 			</return>
 			<description>
+				Clears the audio sample data buffer.
 			</description>
 		</method>
 		<method name="get_frames_available" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns the number of audio data frames left to play. If this returned number reaches [code]0[/code], the audio will stop playing until frames are added again. Therefore, make sure your script can always generate and push new audio frames fast enough to avoid audio cracking.
 			</description>
 		</method>
 		<method name="get_skips" qualifiers="const">
@@ -40,6 +46,7 @@
 			<argument index="0" name="frames" type="PackedVector2Array">
 			</argument>
 			<description>
+				Pushes several audio data frames to the buffer. This is usually more efficient than [method push_frame] in C# and compiled languages via GDNative, but [method push_buffer] may be [i]less[/i] efficient in GDScript.
 			</description>
 		</method>
 		<method name="push_frame">
@@ -48,6 +55,7 @@
 			<argument index="0" name="frame" type="Vector2">
 			</argument>
 			<description>
+				Pushes a single audio data frame to the buffer. This is usually less efficient than [method push_buffer] in C# and compiled languages via GDNative, but [method push_frame] may be [i]more[/i] efficient in GDScript.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/AudioStreamSample.xml b/doc/classes/AudioStreamSample.xml
index c12e1bd05c..d07b1ac66d 100644
--- a/doc/classes/AudioStreamSample.xml
+++ b/doc/classes/AudioStreamSample.xml
@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		AudioStreamSample stores sound samples loaded from WAV files. To play the stored sound, use an [AudioStreamPlayer] (for non-positional audio) or [AudioStreamPlayer2D]/[AudioStreamPlayer3D] (for positional audio). The sound can be looped.
-		This class can also be used to store dynamically-generated PCM audio data.
+		This class can also be used to store dynamically-generated PCM audio data. See also [AudioStreamGenerator] for procedural audio generation.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -39,7 +39,9 @@
 			The loop mode. This information will be imported automatically from the WAV file if present. 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.
+			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 [code]11025[/code], [code]16000[/code], [code]22050[/code], [code]32000[/code], [code]44100[/code], and [code]48000[/code].
+			According to the [url=https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem]Nyquist-Shannon sampling theorem[/url], 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 [code]32000[/code] or [code]22050[/code] may be usable with no loss in quality.
 		</member>
 		<member name="stereo" type="bool" setter="set_stereo" getter="is_stereo" default="false">
 			If [code]true[/code], audio is stereo.
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 851b88c142..25df918522 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -309,7 +309,7 @@
 			If [code]true[/code], microphone input will be allowed. This requires appropriate permissions to be set when exporting to Android or iOS.
 		</member>
 		<member name="audio/driver/mix_rate" type="int" setter="" getter="" default="44100">
-			Mixing rate used for audio. In general, it's better to not touch this and leave it to the host operating system.
+			The mixing rate used for audio (in Hz). In general, it's better to not touch this and leave it to the host operating system.
 		</member>
 		<member name="audio/driver/output_latency" type="int" setter="" getter="" default="15">
 			Output latency in milliseconds for audio. Lower values will result in lower audio latency at the cost of increased CPU usage. Low values may result in audible cracking on slower hardware.