302 lines
10 KiB
ReStructuredText
302 lines
10 KiB
ReStructuredText
.. _doc_audio_buses:
|
||
|
||
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 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.
|
||
|
||
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 20 times the base 10 logarithm of the ratio
|
||
(20 × log\ :sub:`10`\ (P/P\ :sub:`0`\ )).
|
||
- For every 6 dB, sound amplitude doubles or halves. 12 dB represents a factor
|
||
of 4, 18 dB a factor of 8, 20 dB a factor of 10, 40 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 should be arranged so that the output of the
|
||
*master bus* (more on that later) never exceeds 0 dB.
|
||
- Every 6 dB below the 0 dB limit, sound energy is *halved*.
|
||
It means the sound volume at -6 dB is half as loud as 0dB.
|
||
-12 dB is half as loud as -6 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:
|
||
|
||
.. 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.
|
||
|
||
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
|
||
|
||
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:
|
||
|
||
.. image:: img/audio_buses3.png
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
.. image:: img/audio_buses4.png
|
||
|
||
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.
|
||
|
||
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)*.
|
||
|
||
Capture
|
||
~~~~~~~
|
||
|
||
The Capture effect copies the audio frames of the audio bus that it is on into
|
||
an internal buffer. This can be used to capture data from the microphone
|
||
or to transmit audio over the network in real-time.
|
||
|
||
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 duplicated 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.
|
||
|
||
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.
|
||
|
||
.. note::
|
||
|
||
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.
|
||
|
||
Distortion
|
||
~~~~~~~~~~
|
||
|
||
Makes the sound distorted. 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
|
||
~~
|
||
|
||
EQ is what all other equalizers inherit from. It can be extended with with Custom
|
||
scripts to create an equalizer with a custom number of bands.
|
||
|
||
EQ6, EQ10, EQ21
|
||
~~~~~~~~~~~~~~~
|
||
|
||
Godot provides three 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 filters inherit from and should not be used directly.
|
||
|
||
HighPassFilter
|
||
~~~~~~~~~~~~~~
|
||
|
||
Cuts frequencies below a specific *Cutoff* frequency.
|
||
HighPassFilter is used to reduce the bass content of a
|
||
signal.
|
||
|
||
HighShelfFilter
|
||
~~~~~~~~~~~~~~~
|
||
|
||
Reduces all frequencies above a specific *Cutoff* frequency.
|
||
|
||
.. _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.
|
||
|
||
LowPassFilter
|
||
~~~~~~~~~~~~~
|
||
|
||
Cuts 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.
|
||
|
||
LowShelfFilter
|
||
~~~~~~~~~~~~~~
|
||
|
||
Reduces all frequencies below a specific *Cutoff* frequency.
|
||
|
||
NotchFilter
|
||
~~~~~~~~~~~
|
||
|
||
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
|
||
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.
|
||
|
||
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.
|
||
|
||
Record
|
||
~~~~~~
|
||
|
||
The Record effect allows the user to record sound from a microphone.
|
||
|
||
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:`Reverb buses <doc_audio_streams_reverb_buses>`), or to apply
|
||
a "chamber" feel to all sounds.
|
||
|
||
SpectrumAnalyzer
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
This effect doesn't alter audio, instead, you add this effect to buses you want
|
||
a spectrum analysis of. This would typically be used for audio visualization. A
|
||
demo project using this can be found `here <https://github.com/godotengine/godot-demo-projects/tree/master/audio/spectrum>`__.
|
||
|
||
StereoEnhance
|
||
~~~~~~~~~~~~~
|
||
|
||
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).
|
||
|
||
.. figure:: img/audio_buses5.png
|
||
|
||
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. 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 be saved
|
||
and loaded from disk.
|