+Audio control
+-------------
+
+Before you attempt to control audio from the theme, be sure to have read
+the documentation about :doc:`audio`.
+
+The theme has a certain amount of control over the audio
+mix, assuming that you are in multichannel mode. This is useful in particular
+to be able to set defaults, if e.g. one channel should always be muted at
+startup, or to switch in/out certain channels depending on whether they are
+visible or not.
+
+In particular, these operations are available::
+
+ # Returns number of buses in the mapping.
+ local num_buses = Nageru.get_num_audio_buses()
+
+ # Gets the name from the mapping. All indexes start at zero,
+ # so valid indexes are 0..(num_buses-1), inclusive.
+ local name = Nageru.get_audio_bus_name(N)
+
+ # 0.0 is zero amplification, as in the UI. Valid range is
+ # -inf to +6.0, inclusive.
+ local level = Nageru.get_audio_bus_fader_level_db(N)
+ set_audio_bus_fader_level_db(N, level)
+
+ # Similar as the above, but valid range is -15.0..+15.0 (dB).
+ # Valid bands are Nageru.EQ_BAND_{BASS, MID, TREBLE}.
+ local eq_level = Nageru.get_audio_bus_eq_level_db(N, Nageru.EQ_BAND_BASS)
+ Nageru.set_audio_bus_eq_level_db(N, Nageru.EQ_BAND_BASS, level)
+
+ # A boolean. Does not affect the bus levels set/returned above.
+ local muted = Nageru_get_audio_bus_mute(N)
+ Nageru_set_audio_bus_mute(N, false)
+
+Note that any audio operation is inherently unsynchronized with the UI,
+so if the user reduces the number of audio buses while
+the theme tries to access one that is going away, you may get unpredictable
+behavior, up to and including crashes. Thus, you will need to be careful
+with such operations.
+
+Also, you cannot do anything with audio before the first *get_scene()* call,
+since the audio mixer is initialized only after the theme has been loaded and
+initialized. Thus, for things that should be done only the first frame, the
+recommended method is to put code into get_scene() and have a guard variable
+that makes sure it is only run
+once, ever.
+
+