From cb3499b78b07d9fa00633d3cecc10aa25ccd1a76 Mon Sep 17 00:00:00 2001 From: Matthew Date: Sat, 30 Jan 2021 19:34:37 -0500 Subject: [PATCH] Update audio stream and audio import pages, document MP3 support (#4606) Co-authored-by: Hugo Locurcio --- .../importing_audio_samples.rst | 28 ++++++++++++------ tutorials/audio/audio_streams.rst | 23 ++------------ tutorials/audio/img/audio_stream_import.png | Bin 10472 -> 0 bytes 3 files changed, 22 insertions(+), 29 deletions(-) delete mode 100644 tutorials/audio/img/audio_stream_import.png diff --git a/tutorials/assets_pipeline/importing_audio_samples.rst b/tutorials/assets_pipeline/importing_audio_samples.rst index 8668e2c6f..5a260ce8d 100644 --- a/tutorials/assets_pipeline/importing_audio_samples.rst +++ b/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 | diff --git a/tutorials/audio/audio_streams.rst b/tutorials/audio/audio_streams.rst index d13f0d65b..a786cc8e3 100644 --- a/tutorials/audio/audio_streams.rst +++ b/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 diff --git a/tutorials/audio/img/audio_stream_import.png b/tutorials/audio/img/audio_stream_import.png deleted file mode 100644 index 5148bce8ddce2665012dd7399fae22fc45122c4b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 10472 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