Document theme audio control.

diff --git a/theme.rst b/theme.rst
index 8b3fce337263c70f1d83c1505a8015b2fa00ac5a..645584c0c84b137fe81c867cafb3d0293bee8a1b 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -531,6 +531,55 @@ effect alternatives. In particular, you may want to disable scaling if
 the frame is already of the correct resolution.
 
 
+Audio control
+-------------
+
+Before you attempt to control audio from the theme, be sure to have read
+the documentation about :doc:`audio`.
+
+Since Nageru 1.9.2, 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.
+
+
 Overriding the status line
 --------------------------