Merge pull request #808 from ronso0/main-master-group

controls: deprecate [Master],audio_latency_.. -> [App] group

Author: daschuer

source/chapters/appendix/mixxx_controls.rst

@@ -104,6 +104,40 @@ The ``[App]`` group
 
 The :mixxx:cogroupref:`[App]` group contains controls that do not belong to a specific channel, the mixer or the effects engine.
 
+.. mixxx:control:: [App],audio_latency_usage
+
+   Reflects fraction of :term:`latency`, given by the audio buffer size, spend for audio processing inside Mixxx.
+   At value near 25 % there is a high risk of buffer underflows.
+
+   :range: 0 .. 25 %
+   :feedback: latency meter
+
+   .. versionadded:: 2.4.0
+      Replaces the deprecated :mixxx:coref:`[Master],audio_latency_usage` control.
+
+
+.. mixxx:control:: [App],audio_latency_overload
+
+   Indicates a buffer under or over-flow. Resets after 500 ms.
+
+   :range: binary
+   :feedback: Overload indicator
+
+   .. versionadded:: 2.4.0
+      Replaces the deprecated :mixxx:coref:`[Master],audio_latency_overload` control.
+
+
+.. mixxx:control:: [App],audio_latency_overload_count
+
+   Counts buffer over and under-flows, maximum one per 500 ms.
+   The count is displayed in Preferences -> Sound Hardware.
+
+   :range: 0 .. n
+   :feedback: Counter in hardware preferences
+
+   .. versionadded:: 2.4.0
+      Replaces the deprecated :mixxx:coref:`[Master],audio_latency_overload_count` control.
+
 
 
 .. mixxx:control:: [App],gui_tick_50ms_period_s
@@ -235,35 +269,6 @@ The ``[Master]`` group
 The :mixxx:cogroupref:`[Master]` group generally corresponds to controls that affect the mixing engine.
 This will bear some similarity to what you will find on a DJ mixer (e.g. :term:`crossfader` controls, headphone cueing controls, etc.).
 
-.. mixxx:control:: [Master],audio_latency_usage
-
-   Reflects fraction of :term:`latency`, given by the audio buffer size, spend for audio processing inside Mixxx. At value near 25 % there is a high risk of buffer underflows
-
-   :range: 0 .. 25 %
-   :feedback: latency meter
-
-   .. versionadded:: 2.0.0
-
-
-.. mixxx:control:: [Master],audio_latency_overload
-
-   Indicates a buffer under or over-flow. Resets after 500 ms
-
-   :range: binary
-   :feedback: Overload indicator
-
-   .. versionadded:: 2.0.0
-
-
-.. mixxx:control:: [Master],audio_latency_overload_count
-
-   Counts buffer over and under-flows. Max one per 500 ms
-
-   :range: 0 .. n
-   :feedback: Counter in hardware preferences
-
-   .. versionadded:: 2.0.0
-
 
 .. mixxx:control:: [Master],balance
 
@@ -4375,6 +4380,44 @@ Deprecated controls
 These controls have been deprecated and may be removed in a future version of Mixxx.
 In the meantime, skins and controller mappings that still use them will keep working, but using the suggested alternatives is strongly recommended.
 
+.. mixxx:control:: [Master],audio_latency_usage
+
+   Reflects fraction of :term:`latency`, given by the audio buffer size, spend for audio processing inside Mixxx.
+   At value near 25 % there is a high risk of buffer underflows.
+
+   :range: 0 .. 25 %
+   :feedback: latency meter
+
+   .. versionadded:: 2.0.0
+   .. deprecated:: 2.4.0
+       Use :mixxx:coref:`[App],audio_latency_usage` instead.
+
+
+.. mixxx:control:: [Master],audio_latency_overload
+
+   Indicates a buffer under or over-flow. Resets after 500 ms.
+
+   :range: binary
+   :feedback: Overload indicator
+
+   .. versionadded:: 2.0.0
+   .. deprecated:: 2.4.0
+       Use :mixxx:coref:`[App],audio_latency_overload` instead.
+
+
+.. mixxx:control:: [Master],audio_latency_overload_count
+
+   Counts buffer over- and underflows, maximum one per 500 ms.
+   See :ref:`preferences-sound-other-options` for details.
+   The count is displayed in Preferences -> Sound Hardware.
+
+   :range: 0 .. n
+   :feedback: Counter in hardware preferences
+
+   .. versionadded:: 2.0.0
+   .. deprecated:: 2.4.0
+       Use :mixxx:coref:`[App],audio_latency_overload_count` instead.
+
 .. mixxx:control:: [Master],guiTick50ms
 
    A throttled timer that provides the time elapsed in seconds since Mixxx was started.

source/chapters/preferences/sound_hardware.rst

@@ -155,6 +155,8 @@ macOS
 ^^^^^
 CoreAudio is the only Sound API on macOS.
 
+.. _preferences-sound-other-options:
+
 Other Sound Hardware options
 ----------------------------
 * **Multi-Soundcard Synchronization**: Mixxx is able to use two or more
@@ -177,12 +179,12 @@ Other Sound Hardware options
   in stereo because of speaker placement or playing in a space with lots of
   reverberation.
 
-* **Buffer Underflow Count**: Underflows (data is not available when needed)
-  indicate that some of the subsystems in Mixxx can't keep up with real-time
-  deadlines imposed by the current audio buffer size. This is useful to tune the
-  latency settings. If the counter increases, then increase your audio buffer
-  size, decrease the sample rate setting or change the sound API setting if
-  available.
+* **Buffer Underflow Count**: This counts overflows in output buffers or underflows
+  in input buffers, indicating either the output device(s) can't consume audio data
+  generated by the engine fast enough, or the input device(s) can't provide audio data
+  as fast as required by the current audio buffer size. If the counter increases,
+  you may try to increase your audio buffer size, decrease the sample rate setting,
+  change the sound API available or try another keylock/pitch-bend engine.
 
 Output and Input Devices
 ------------------------