Update audio stream and audio import pages, document MP3 support (#4606)

Co-authored-by: Hugo Locurcio <[email protected]>

Author: skyace65

tutorials/assets_pipeline/importing_audio_samples.rst

@@ -3,19 +3,27 @@
 Importing audio samples
 =======================
 
-Why import?
------------
+Supported files
+---------------
 
-Raw audio data in general is large and undesired. Godot provides two main
-options to import your audio data: WAV and Ogg Vorbis.
+Godot provides three options to import your audio data: WAV, Ogg Vorbis
+and MP3.
 
 Each has different advantages.
 
-* WAV files use raw data or light compression, make few demands on the CPU to play back (hundreds of simultaneous voices in this format are fine), but take up significant space.
-* Ogg Vorbis files use a stronger compression that results in much smaller file size, but require significantly more processing power to play back.
-
-
-.. image:: img/audio_stream_import.png
+* WAV files use raw data or light compression (IMA-ADPCM). They are lightweight
+  on the CPU to play back (hundreds of simultaneous voices in this format are
+  fine). The downside is that they take up a lot of disk space.
+* Ogg Vorbis files use a stronger compression that results in much
+  smaller file size, but require significantly more processing power to
+  play back.
+* MP3 files use better compression than WAV with IMA-ADPCM, but worse than
+  Ogg Vorbis. This means that a MP3 file with roughly equal quality to
+  Ogg Vorbis will be significantly larger. On the bright side, MP3 requires
+  less CPU usage to play back compared to Ogg Vorbis. This makes MP3 useful
+  for mobile and HTML5 projects where CPU resources are limited, especially
+  when playing multiple compressed sounds at the same time (such as long
+  ambient sounds).
 
 Here is a comparative chart.
 
@@ -28,6 +36,8 @@ Here is a comparative chart.
 +-----------------------------+-------------------+
 | WAV 16-bit, IMA-ADPCM, mono | 22 KB             |
 +-----------------------------+-------------------+
+| MP3 192 Kb/s, stereo        | 24 KB             |
++-----------------------------+-------------------+
 | Ogg Vorbis 128 Kb/s, stereo | 16 KB             |
 +-----------------------------+-------------------+
 | Ogg Vorbis 96 Kb/s, stereo  | 12 KB             |

tutorials/audio/audio_streams.rst

@@ -14,26 +14,9 @@ AudioStream
 -----------
 
 An audio stream is an abstract object that emits sound. The sound can come from
-many places, but is most commonly loaded from the filesystem. Audio files such
-as WAV (``.wav``) or Ogg Vorbis (``.ogg``) can be loaded as AudioStreams and
-placed inside an AudioStreamPlayer.
-
-Here is a comparison of the two file types to help you choose the one that fits
-your use case best:
-
-- WAV files are quite large, but use little CPU power to play back.
-  Hundreds of them can be played simultaneously with little impact
-  on performance. This format is usually best for short sound effects.
-- Ogg Vorbis files are much smaller, but use considerably more CPU power
-  to play back, so only a few can be played back at once (especially on mobile).
-  This format works well for music, long sound effect sequences, and voice
-  at relatively low bitrates.
-
-Keep in mind that while WAV files may contain looping information in their metadata,
-Ogg Vorbis files do not. If looping an Ogg Vorbis file is desired, 
-it must be set up using the import options:
-
-.. image:: img/audio_stream_import.png
+many places, but is most commonly loaded from the filesystem. Audio files can be
+loaded as AudioStreams and placed inside an AudioStreamPlayer. You can find a
+information on supported formats and differences in :ref:`doc_importing_audio_samples`.
 
 There are other types of AudioStreams, such as AudioStreamRandomPitch.
 This one makes a random adjustment to the sound's pitch every time it's