Improve "Audio buses", "Audio streams" and "Importing audio samples"

This improves writing style and formatting, and adds more links
to refer to other pages.

getting_started/workflow/assets/importing_audio_samples.rst

@@ -7,11 +7,11 @@ Why import?
 -----------
 
 Raw audio data in general is large and undesired. Godot provides two main
-options to import your audio data: WAV and OGG Vorbis.
+options to import your audio data: WAV and Ogg Vorbis.
 
 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.
+* 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.
 
 
@@ -19,30 +19,30 @@ Each has different advantages.
 
 Here is a comparative chart.
 
-+-------------------------------+---------------------+
-| Format                        | 1 Second of Audio   |
-+===============================+=====================+
-| WAV 24 bits, 96 kHz, Stereo   | 576kb               |
-+-------------------------------+---------------------+
-| WAV 16 bits, 44 kHz, Mono     | 88kb                |
-+-------------------------------+---------------------+
-| WAV 16 bits, IMA-ADPCM, Mono  | 22kb                |
-+-------------------------------+---------------------+
-| OGG 128kbps, Stereo           | 16kb                |
-+-------------------------------+---------------------+
-| OGG Vorbis 96kbps, Stereo     | 12kb                |
-+-------------------------------+---------------------+
-
-Consider using WAV for short and repetitive sound effects, and OGG
++-----------------------------+-------------------+
+| Format                      | 1 second of audio |
++=============================+===================+
+| WAV 24-bit, 96 kHz, stereo  | 576 KB            |
++-----------------------------+-------------------+
+| WAV 16-bit, 44 kHz, mono    | 88 KB             |
++-----------------------------+-------------------+
+| WAV 16-bit, IMA-ADPCM, mono | 22 KB             |
++-----------------------------+-------------------+
+| Ogg Vorbis 128 Kb/s, stereo | 16 KB             |
++-----------------------------+-------------------+
+| Ogg Vorbis 96 Kb/s, stereo  | 12 KB             |
++-----------------------------+-------------------+
+
+Consider using WAV for short and repetitive sound effects, and Ogg Vorbis
 for music, speech, and long sound effects.
 
 Best practices
 --------------
 
-Godot 3+ has an amazing bus system with built-in effects. This saves
-SFX artists the need to add reverb to the sound effects, reducing their
-size greatly and ensuring correct trimming. Say no to SFX with baked
-reverb!
+Godot has an :ref:`extensive bus system <doc_audio_buses>` with built-in effects.
+This saves SFX artists the need to add reverb to the sound effects,
+reducing their size greatly and ensuring correct trimming. Say no to SFX
+with baked reverb!
 
 .. image:: img/reverb.png
 
@@ -56,16 +56,16 @@ silences at the beginning and at the end. These are inserted by
 DAWs when saving to a waveform, increase their size unnecessarily and
 add latency to the moment they are played back.
 
-Importing as WAV with the Trimming option enabled solves
+Importing as WAV with the **Trimming** option enabled solves
 this.
 
 Looping
 ~~~~~~~
 
 Godot supports looping in the samples (tools such as Sound Forge or
-Audition can add loop points to wav files). This is useful for sound
+Audition can add loop points to WAV files). This is useful for sound
 effects, such as engines, machine guns etc. Ping-pong looping is also
 supported.
 
-As an alternative, the import screen has a "loop" option that enables
+As an alternative, the Import dock has a **Loop** option that enables
 looping for the entire sample when importing.

tutorials/audio/audio_buses.rst

@@ -1,4 +1,4 @@
-.. _doc_audio-buses:
+.. _doc_audio_buses:
 
 Audio buses
 ===========
@@ -6,40 +6,64 @@ Audio buses
 Introduction
 ------------
 
-Godot's audio processing code has been written with games in mind, with the aim of achieving an optimal balance between performance and sound quality.
+Godot's audio processing code has been written with games in mind, with the aim
+of achieving an optimal balance between performance and sound quality.
 
-Godot's audio engine allows any number of audio buses to be created and any number of effect processors can be added to each bus. Only the hardware of the device running your game will limit the number of buses and effects that can be used before performance starts to suffer.
+Godot's audio engine allows any number of audio buses to be created and any
+number of effect processors can be added to each bus. Only the hardware of the
+device running your game will limit the number of buses and effects that can be
+used before performance starts to suffer.
 
 Decibel scale
 -------------
 
 Godot's sound interface is designed to meet the expectations of sound design
-professionals. To this end it primarily uses the decibel scale.
+professionals. To this end, it primarily uses the decibel scale.
 
 For those unfamiliar with it, it can be explained with a few facts:
 
-* The decibel (dB) scale is a relative scale. It represents the ratio of sound power by using 10 times the base 10 logarithm of the ratio (10×log\ :sub:`10`\ (P/P\ :sub:`0`\ )).
-* For every 3dB, sound amplitude doubles or halves. 6dB represents a factor of 4, 9dB a factor of 8, 10dB a factor of 10, 20dB a factor of 100, etc.
-* Since the scale is logarithmic, true zero (no audio) can't be represented.
-* 0dB is the maximum amplitude possible in a digital audio system. This limit is not the human limit, but a limit from the sound hardware. Audio with amplitudes that are too high to be represented properly below 0dB create a kind of distortion called clipping.
-* To avoid clipping, your sound mix be arranged so that the output of the *Master Bus* (more on that later) never exceeds 0dB.
-* Every 3dB below the 0dB limit, sound energy is *halved*. It means the sound volume at -3dB is half as loud as 0dB. -6dB is half as loud as -3dB and so on.
-* When working with decibels, sound is considered no longer audible between -60dB and -80dB. This makes your working range generally between -60dB and 0dB.
-
-This can take a bit getting used to, but it's friendlier in the end and will allow you to communicate better with audio professionals.
+- The decibel (dB) scale is a relative scale. It represents the ratio of
+  sound power by using 10 times the base 10 logarithm of the ratio
+  (10 × log\ :sub:`10`\ (P/P\ :sub:`0`\ )).
+- For every 3 dB, sound amplitude doubles or halves. 6 dB represents a factor
+  of 4, 9 dB a factor of 8, 10 dB a factor of 10, 20 dB a factor of 100, etc.
+- Since the scale is logarithmic, true zero (no audio) can't be represented.
+- 0 dB is the maximum amplitude possible in a digital audio system.
+  This limit is not the human limit, but a limit from the sound hardware.
+  Audio with amplitudes that are too high to be represented properly below 0 dB
+  create a kind of distortion called *clipping*.
+- To avoid clipping, your sound mix be arranged so that the output of the
+  *master bus* (more on that later) never exceeds 0 dB.
+- Every 3 dB below the 0 dB limit, sound energy is *halved*.
+  It means the sound volume at -3 dB is half as loud as 0dB.
+  -6 dB is half as loud as -3 dB and so on.
+- When working with decibels, sound is considered no longer audible
+  between -60 dB and -80 dB. This makes your working range generally
+  between -60 dB and 0 dB.
+
+This can take a bit getting used to, but it's friendlier in the end
+and will allow you to communicate better with audio professionals.
 
 Audio buses
 -----------
 
-Audio buses can be found in the bottom panel of the Godot Editor:
+Audio buses can be found in the bottom panel of the Godot editor:
 
 .. image:: img/audio_buses1.png
 
-An *Audio Bus* (also called an *Audio Channel*) can be considered a place that audio is channeled through on the way to playback through a device's speakers. Audio data can be *modified* and *re-routed* by an *Audio Bus*. An *Audio Bus* has a VU meter (the bars that light up when sound is played) which indicates the amplitude of the signal passing through.
+An *audio bus* (also called an *audio channel*) can be considered a place that
+audio is channeled through on the way to playback through a device's speakers.
+Audio data can be *modified* and *re-routed* by an audio bus. An audio bus
+has a VU meter (the bars that light up when sound is played) which indicates the
+amplitude of the signal passing through.
 
-The leftmost bus is the *Master Bus*. This bus outputs the mix to your speakers so, as mentioned in the item above (Decibel Scale), make sure that your mix level doesn't reach 0dB in this bus.
-The rest of the audio buses can be flexibly routed. After modifying the sound, they send it to another bus to the left. The destination bus can be specified for each of the non-master audio buses. Routing always passes audio from buses on the right to buses further to the left. This
-avoids infinite routing loops.
+The leftmost bus is the *master bus*. This bus outputs the mix to your speakers
+so, as mentioned in the *Decibel scale* section above, make sure that your mix
+level doesn't reach 0 dB in this bus. The rest of the audio buses can be
+flexibly routed. After modifying the sound, they send it to another bus to
+the left. The destination bus can be specified for each of the non-master audio
+buses. Routing always passes audio from buses on the right to buses further
+to the left. This avoids infinite routing loops.
 
 .. image:: img/audio_buses2.png
 
@@ -48,111 +72,159 @@ In the above image, the output of *Bus 2* has been routed to the *Master* bus.
 Playback of audio through a bus
 -------------------------------
 
-To test passing audio to a bus, create an AudioStreamPlayer node, load an AudioStream and select a target bus for playback:
+To test passing audio to a bus, create an AudioStreamPlayer node, load an
+AudioStream and select a target bus for playback:
 
 .. image:: img/audio_buses3.png
 
-Finally, toggle the "playing" property to on and sound will flow.
+Finally, toggle the **Playing** property to **On** and sound will flow.
+
+.. seealso::
 
-You may also be interested in reading about :ref:`doc_audio-streams` now.
+    You may also be interested in reading about :ref:`doc_audio_streams` now.
 
 Adding effects
 --------------
 
-Audio buses can contain all sorts of effects. These effects modify the sound in one way or another and are applied in order.
+Audio buses can contain all sorts of effects. These effects modify the sound in
+one way or another and are applied in order.
 
 .. image:: img/audio_buses4.png
 
-Try them all out to get a sense of how they alter sound. Here follows a short description of available effects:
+Try them all out to get a sense of how they alter sound. Here follows a short
+description of the available effects:
 
 Amplify
 ~~~~~~~
 
-Amplify changes the amplitude of the signal. Some care needs to be taken. Setting the level too high can make the sound clip, which is usually undesirable.
+Amplify changes the amplitude of the signal. Some care needs to be taken.
+Setting the level too high can make the sound clip, which is usually
+undesirable.
 
 BandLimit and BandPass
 ~~~~~~~~~~~~~~~~~~~~~~
 
-These are resonant filters which block frequencies around the *Cutoff* point. BandPass can be used to simulate sound passing through an old telephone line or megaphone. Modulating the BandPass frequency can simulate the sound of a wah-wah guitar pedal, think of the guitar in Jimi Hendrix's *Voodoo Child (Slight Return)*.
+These are resonant filters which block frequencies around the *Cutoff* point.
+BandPass can be used to simulate sound passing through an old telephone line or
+megaphone. Modulating the BandPass frequency can simulate the sound of a wah-wah
+guitar pedal, think of the guitar in Jimi Hendrix's *Voodoo Child (Slight
+Return)*.
 
 Chorus
 ~~~~~~
 
-The Chorus effect duplicates the incoming audio, delays the duplicate slightly and uses an LFO to continuously modulate the pitch of the duplicated signal before mixing the duplicatated signal(s) and the original together again. This creates a shimmering effect and adds stereo width to the sound.
+The Chorus effect duplicates the incoming audio, delays the duplicate slightly
+and uses an LFO to continuously modulate the pitch of the duplicated signal
+before mixing the duplicatated signal(s) and the original together again. This
+creates a shimmering effect and adds stereo width to the sound.
 
 Compressor
 ~~~~~~~~~~
 
-A dynamic range compressor automatically attenuates the level of the incoming signal when its amplitude exceeds a certain threshold. The level of attenuation applied is proportional to how far the incoming audio exceeds the threshold. The compressor's Ratio parameter controls the degree of attenuation.
-One of the main uses of a compressor is to reduce the dynamic range of signals with very loud and quiet parts. Reducing the dynamic range of a signal can make it easier to mix.
+A dynamic range compressor automatically attenuates the level of the incoming
+signal when its amplitude exceeds a certain threshold. The level of attenuation
+applied is proportional to how far the incoming audio exceeds the threshold.
+The compressor's Ratio parameter controls the degree of attenuation.
+One of the main uses of a compressor is to reduce the dynamic range of signals
+with very loud and quiet parts. Reducing the dynamic range of a signal
+can make it easier to mix.
 
 The compressor has many uses. For example:
 
-* It can be used in the Master bus to compress the whole output.
-* It can be used in voice channels to ensure they sound as even as possible.
-* It can be *Sidechained*. This means it can reduce the sound level of one signal using the level of another audio bus for threshold detection. This technique is very common in video game mixing to 'duck' the level of music or sound effects when voices need to be heard.
-* It can accentuate transients by using a slower attack. This can make sound effects more punchy.
+- It can be used in the Master bus to compress the whole output.
+- It can be used in voice channels to ensure they sound as even as possible.
+- It can be *sidechained*. This means it can reduce the sound level
+  of one signal using the level of another audio bus for threshold detection.
+  This technique is very common in video game mixing to "duck" the level of
+  music or sound effects when voices need to be heard.
+- It can accentuate transients by using a slower attack.
+  This can make sound effects more punchy.
 
 .. note::
 
-    If your goal is to prevent a signal from exceeding a given amplitude altogether, rather that to reduce the dynamic range       of the signal, a limiter is likely a better choice than a compressor. See below.
+    If your goal is to prevent a signal from exceeding a given amplitude
+    altogether, rather than to reduce the dynamic range of the signal,
+    a :ref:`limiter <doc_audio_buses_limiter>` is likely a better choice
+    than a compressor.
 
 
 Delay
 ~~~~~
 
-Adds an "Echo" effect with a feedback loop. It can be used, together with Reverb, to simulate wide rooms, canyons, etc. where sound bounces are far apart.
+Adds an "echo" effect with a feedback loop. It can be used together
+with *Reverb* to simulate wide rooms, canyons, etc. where sound bounces
+are far apart.
 
 Distortion
 ~~~~~~~~~~
 
-Distortion effects make the sound 'dirty'. Godot offers several types of distortion: Overdrive, tan and bit crushing.
-Distortion can be used simulate sound coming through a low-quality speaker or device.
+Distortion effects make the sound "dirty". Godot offers several types of
+distortion: *overdrive*, *tan* and *bit crushing*. Distortion can be used
+to simulate sound coming through a low-quality speaker or device.
 
 EQ, EQ6, EQ10, EQ21
 ~~~~~~~~~~~~~~~~~~~
 
-Godot provides four equalizers with different numbers of bands. An equalizer on the master bus can be useful to cut frequencies that the device's speakers can't reproduce well (e.g. a mobile phone's speakers won't reproduce bass content well). The equalizer effect can be disabled when headphones are plugged in.
+Godot provides four equalizers with different numbers of bands. An equalizer on
+the Master bus can be useful to cut frequencies that the device's speakers can't
+reproduce well (e.g. a mobile phone's speakers won't reproduce bass content
+well). The equalizer effect can be disabled when headphones are plugged in.
 
 Filter
 ~~~~~~
 
-Filter is what all other effects processors inherit from and should not be used directly.
+Filter is what all other effects processors inherit from and should not be used
+directly.
 
 HighPassFilter, HighShelfFilter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These are filters that cut frequencies below a specific *Cutoff* frequency. HighPassFilter and HighShelfFilter are used to reduce the bass content of a signal.
+These are filters that cut frequencies below a specific *Cutoff* frequency.
+HighPassFilter and HighShelfFilter are used to reduce the bass content of a
+signal.
+
+.. _doc_audio_buses_limiter:
 
 Limiter
 ~~~~~~~
 
-A limiter is similar to a compressor, but it's less flexible and designed to prevent a signal's amplitude exceeding a given dB threshold. Adding a limiter to the *Master Bus* is a safeguard against clipping.
+A limiter is similar to a compressor, but it's less flexible and designed to
+prevent a signal's amplitude exceeding a given dB threshold. Adding a limiter to
+the Master bus is a safeguard against clipping.
 
 LowPassFilter, LowShelfFilter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These are the most common filters, they cut frequencies above a specific *Cutoff* frequency and can also resonate (boost frequencies close to the *Cutoff* frequency). Low pass filters can be used to simulate 'muffled' sound. For instance underwater sound, sound blocked by walls, or distant sound.
+These are the most common filters, they cut frequencies above a specific
+*Cutoff* frequency and can also resonate (boost frequencies close to the
+*Cutoff* frequency). Low pass filters can be used to simulate "muffled" sound.
+For instance, underwater sounds, sounds blocked by walls, or distant sounds.
 
 NotchFilter
 ~~~~~~~~~~~
 
-The opposite to the BandPassFilter, it removes a band of sound from the frequency spectrum at a given *Cutoff* frequency.
+The opposite of the BandPassFilter, it removes a band of sound from the
+frequency spectrum at a given *Cutoff* frequency.
 
 Panner
 ~~~~~~
 
-The Panner allows the stereo balance of a signal to be adjusted between left and right channels (wear headphones to audition this effect).
+The Panner allows the stereo balance of a signal to be adjusted between
+the left and right channels (wear headphones to audition this effect).
 
 Phaser
 ~~~~~~
 
-It probably does not make much sense to explain that this effect is formed by two signals being dephased and cancelling each other out. You can make a Darth Vader voice with it, or jet-like sounds.
+It probably does not make much sense to explain that this effect is formed by
+two signals being dephased and cancelling each other out. You can make a Darth
+Vader voice with it, or jet-like sounds.
 
 PitchShift
 ~~~~~~~~~~
 
-This effect allows the adjustment of the signal's pitch independently of its speed. All frequencies can be increased/decreased with minimal effect on transients. PitchShift can be useful to create unusually high or deep voices.
+This effect allows the adjustment of the signal's pitch independently of its
+speed. All frequencies can be increased/decreased with minimal effect on
+transients. PitchShift can be useful to create unusually high or deep voices.
 
 Record
 ~~~~~~
@@ -162,30 +234,40 @@ The Record effect allows audio passing through the bus to be written to a file.
 Reverb
 ~~~~~~
 
-Reverb simulates rooms of different sizes. It has adjustable parameters that can be tweaked to obtain the sound of a specific room. Reverb is commonly outputted from :ref:`Areas <class_Area>` (see :ref:`doc_audio-streams` tutorial, look for the "Reverb buses" section), or
-to apply chamber feel to all sounds.
+Reverb simulates rooms of different sizes. It has adjustable parameters that can
+be tweaked to obtain the sound of a specific room. Reverb is commonly outputted
+from :ref:`Areas <class_Area>`
+(see :ref:`Reverb buses <doc_audio_streams_reverb_buses>`), or to apply
+a "chamber" feel to all sounds.
 
 StereoEnhance
 ~~~~~~~~~~~~~
 
-This effect has a few algorithms for enhancing a signal's stereo spectrum.
+This effect uses a few algorithms to enhance a signal's stereo spectrum.
 
 Automatic bus disabling
 -----------------------
 
-There is no need to disable buses manually when not in use; Godot detects that the bus has been silent for a few seconds and disables it (including all effects).
+There is no need to disable buses manually when not in use. Godot detects
+that the bus has been silent for a few seconds and disables it (including
+all effects).
 
 .. figure:: img/audio_buses5.png
 
-   Disabled buses have a blue VU meter.
+   Disabled buses have a blue VU meter instead of a red-green one.
 
 Bus rearrangement
 -----------------
 
-Stream Players use bus names to identify a bus, which allows adding, removing and moving buses around while the reference to them is kept.
-If a bus is renamed, however, the reference will be lost and the Stream Player will output to Master. This system was chosen because rearranging buses is a more common process than renaming them.
+Stream Players use bus names to identify a bus, which allows adding, removing
+and moving buses around while the reference to them is kept. However, if a bus
+is renamed, the reference will be lost and the Stream Player will output
+to Master. This system was chosen because rearranging buses is a more common
+process than renaming them.
 
 Default bus layout
 ------------------
 
-The default bus layout is automatically saved to the ``res://default_bus_layout.tres`` file. Custom bus arrangements can saved and loaded from disk.
+The default bus layout is automatically saved to the
+``res://default_bus_layout.tres`` file. Custom bus arrangements can be saved
+and loaded from disk.

tutorials/audio/audio_streams.rst

@@ -1,4 +1,4 @@
-.. _doc_audio-streams:
+.. _doc_audio_streams:
 
 Audio streams
 =============
@@ -6,49 +6,67 @@ Audio streams
 Introduction
 ------------
 
-As you might have already read in the :ref:`Audio Buses Tutorial<doc_audio-buses>`,
-sound is sent to each bus via an AudioStreamPlayer.
-
-There are different kinds of AudioStreamPlayer. Each one loads
-an AudioStream and plays it back.
+As you might have already read in :ref:`doc_audio_buses`, sound is sent to
+each bus via an AudioStreamPlayer node. There are different kinds
+of AudioStreamPlayers. Each one loads an AudioStream and plays it back.
 
 AudioStream
 -----------
 
-An audio stream is an abstract object that emits sound. The sound can come from many places, but most commonly
-from the filesystem. Audio files, such as .wav or .ogg, can be loaded as AudioStreams and placed
-inside an AudioStreamPlayer.
+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 types of file to help you choose the one that fits your use case best:
+Here is a comparison of the two file types to help you choose the one that fits
+your use case best:
 
-* Audio files of type *.wav* are quite large, but use little CPU power to play back. Hundreds of them can be played simultaneously with little impact to performance. This format is usually best for short sound effects.
-* Audio files of type *.ogg* are much smaller, but use considerably more CPU power to play back, so only a few can be played back (especially on mobile!). This format works well for music, long sound effect sequences, and voice at relatively low bitrates.
+- 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 neither .wav nor .ogg usually contains looping information. If looping is desired it must be set up using the import options of each file type:
+Keep in mind Ogg Vorbis files don't contain looping information. If looping an
+Ogg Vorbis file is desired, it must be set up using the import options:
 
 .. image:: img/audio_stream_import.png
 
-There are other types of AudioStreamPlayer, such as AudioStreamRandomPitch. This one makes a random adjustment to the sound's pitch every time it's played back. This can be helpful for adding interest to sounds that are played back often.
+There are other types of AudioStreamPlayer, such as AudioStreamRandomPitch.
+This one makes a random adjustment to the sound's pitch every time it's
+played back. This can be helpful for adding variation to sounds that are
+played back often.
 
 AudioStreamPlayer
 -----------------
 
-This is the standard stream player; it can play to any bus. In 5.1 sound, it can send to stereo mix or front speakers.
+This is the standard, non-positional stream player. It can play to any bus.
+In 5.1 sound setups, it can send audio to stereo mix or front speakers.
 
 AudioStreamPlayer2D
 -------------------
 
-This is a variant of AudioStreamPlayer, but emits sound in a 2D positional environment. When close to the left of the screen, the panning will go left. When close to the right side, it will go right.
+This is a variant of AudioStreamPlayer, but emits sound in a 2D positional
+environment. When close to the left of the screen, the panning will go left.
+When close to the right side, it will go right.
+
+.. note::
 
-.. note:: Area2Ds can be used to divert sound from any AudioStreamPlayer2Ds they contain to specific buses. This makes it possible to create buses with different reverb or sound qualities to handle action happening in a particular parts of your game world.
+    Area2Ds can be used to divert sound from any AudioStreamPlayer2Ds they
+    contain to specific buses. This makes it possible to create buses with
+    different reverb or sound qualities to handle action happening in a
+    particular parts of your game world.
 
 .. image:: img/audio_stream_2d_area.png
 
 AudioStreamPlayer3D
 -------------------
 
-This is a variant of AudioStreamPlayer, but emits sound in a 3D positional environment. Depending on the location of the player relative to the screen, it can position sound in Stereo, 5.1 or 7.1 depending
-on the chosen audio setup.
+This is a variant of AudioStreamPlayer, but emits sound in a 3D positional
+environment. Depending on the location of the player relative to the screen,
+it can position sound in stereo, 5.1 or 7.1 depending on the chosen audio setup.
 
 Similar to AudioStreamPlayer2D, an Area can divert the sound to an audio bus.
 
@@ -56,27 +74,41 @@ Similar to AudioStreamPlayer2D, an Area can divert the sound to an audio bus.
 
 Unlike for 2D, the 3D version of AudioStreamPlayer has a few more advanced options:
 
+.. _doc_audio_streams_reverb_buses:
+
 Reverb buses
 ~~~~~~~~~~~~
 
-Godot allows 3D Audio Streams that enter a specific *Area* to send dry and wet audio to separate buses. This is useful when you have several reverb configurations for different types of rooms.
-This is done by enabling this type of reverb in the *Reverb Bus* section of *Area* properties:
+Godot allows for 3D audio streams that enter a specific Area node to send dry
+and wet audio to separate buses. This is useful when you have several reverb
+configurations for different types of rooms. This is done by enabling this type
+of reverb in the **Reverb Bus** section of the Area's properties:
 
 .. image:: img/audio_stream_reverb_bus.png
 
-At the same time, a special bus layout is created where each area receives the reverb info from each area. A Reverb effect needs to be created and configured in each reverb bus to complete the setup for the desired effect:
+At the same time, a special bus layout is created where each area receives the
+reverb info from each area. A Reverb effect needs to be created and configured
+in each reverb bus to complete the setup for the desired effect:
 
 .. image:: img/audio_stream_reverb_bus2.png
 
-The Area Reverb Bus section also has a parameter named "Uniformity". Some types of rooms bounce sounds more than others (like a warehouse), so reverberation can be heard
-almost uniformly across the room even though the source may be far away. Playing around with this parameter can simulate that effect.
+The Area's **Reverb Bus** section also has a parameter named **Uniformity**.
+Some types of rooms bounce sounds more than others (like a warehouse), so
+reverberation can be heard almost uniformly across the room even though the
+source may be far away. Playing around with this parameter can simulate
+that effect.
 
 Doppler
 ~~~~~~~
 
-When the relative velocity between an emitter and listener changes, this is perceived as an increase or decrease in the pitch of the emitted sound. Godot can track changes in velocities of *AudioStreamPlayer3D* or *Camera*.
-Both have this property, which must be enabled manually:
+When the relative velocity between an emitter and listener changes, this is
+perceived as an increase or decrease in the pitch of the emitted sound.
+Godot can track velocity changes in the AudioStreamPlayer3D and Camera nodes.
+Both nodes have this property, which must be enabled manually:
 
 .. image:: img/audio_stream_doppler.png
 
-Enable it by setting it depending on how objects will be moved (whether on regular *process* or *physics_process* step) and the tracking will happen automatically.
+Enable it by setting it depending on how objects will be moved:
+use **Idle** for objects moved using ``_process``, or **Physics**
+for objects moved using ``_physics_process``. The tracking will
+happen automatically.

tutorials/plugins/editor/import_plugins.rst

@@ -9,7 +9,7 @@ Introduction
 An import plugin is a special type of editor tool that allows custom resources
 to be imported by Godot and be treated as first-class resources. The editor
 itself comes bundled with a lot of import plugins to handle the common resources
-like PNG images, Collada and glTF models, OGG Vorbis sounds, and many more.
+like PNG images, Collada and glTF models, Ogg Vorbis sounds, and many more.
 
 This tutorial will show you how to create a simple import plugin to load a
 custom text file as a material resource. This text file will contain three

tutorials/viewports/viewports.rst

@@ -51,7 +51,7 @@ Listener
 --------
 
 Godot supports 3D sound (in both 2D and 3D nodes); more on this can be
-found in the :ref:`Audio Streams Tutorial<doc_audio-streams>`. For this type of sound to be
+found in the :ref:`Audio Streams Tutorial<doc_audio_streams>`. For this type of sound to be
 audible, the :ref:`Viewport <class_Viewport>` needs to be enabled as a listener (for 2D or 3D).
 If you are using a custom :ref:`Viewport <class_Viewport>` to display your :ref:`World <class_World>`, don't forget
 to enable this!