Merging upstream version 0.38.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 64 insertions, 14 deletions

diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
index 4e4e454..4ac1cc5 100644
--- a/DOCS/man/ao.rst
+++ b/DOCS/man/ao.rst
@@ -12,16 +12,59 @@ in the list.
 
 .. note::
 
-    See ``--ao=help`` for a list of compiled-in audio output drivers. The
-    driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems
-    where PulseAudio is used. On BSD systems, ``--ao=oss`` is preferred.
+    See ``--ao=help`` for a list of compiled-in audio output drivers sorted by
+    autoprobe order.
 
 Available audio output drivers are:
 
-``alsa`` (Linux only)
-    ALSA audio output driver
+``alsa``
+    ALSA audio output driver.
 
-    See `ALSA audio output options`_ for options specific to this AO.
+    The following global options are supported by this audio output:
+
+    ``--alsa-resample=yes``
+        Enable ALSA resampling plugin. (This is disabled by default, because
+        some drivers report incorrect audio delay in some cases.)
+
+    ``--alsa-mixer-device=<device>``
+        Set the mixer device used with ``ao-volume`` (default: ``default``).
+
+    ``--alsa-mixer-name=<name>``
+        Set the name of the mixer element (default: ``Master``). This is for
+        example ``PCM`` or ``Master``.
+
+    ``--alsa-mixer-index=<number>``
+        Set the index of the mixer channel (default: 0). Consider the output of
+        "``amixer scontrols``", then the index is the number that follows the
+        name of the element.
+
+    ``--alsa-non-interleaved``
+        Allow output of non-interleaved formats (if the audio decoder uses
+        this format). Currently disabled by default, because some popular
+        ALSA plugins are utterly broken with non-interleaved formats.
+
+    ``--alsa-ignore-chmap``
+        Don't read or set the channel map of the ALSA device - only request the
+        required number of channels, and then pass the audio as-is to it. This
+        option most likely should not be used. It can be useful for debugging,
+        or for static setups with a specially engineered ALSA configuration (in
+        this case you should always force the same layout with ``--audio-channels``,
+        or it will work only for files which use the layout implicit to your
+        ALSA device).
+
+    ``--alsa-buffer-time=<microseconds>``
+        Set the requested buffer time in microseconds. A value of 0 skips requesting
+        anything from the ALSA API. This and the ``--alsa-periods`` option uses the
+        ALSA ``near`` functions to set the requested parameters. If doing so results
+        in an empty configuration set, setting these parameters is skipped.
+
+        Both options control the buffer size. A low buffer size can lead to higher
+        CPU usage and audio dropouts, while a high buffer size can lead to higher
+        latency in volume changes and other filtering.
+
+    ``--alsa-periods=<number>``
+        Number of periods requested from the ALSA API. See ``--alsa-buffer-time``
+        for further remarks.
 
     .. warning::
 
@@ -95,11 +138,21 @@ Available audio output drivers are:
         passthrough (even if the device reports it as supported). Use with
         extreme care.
 
-
 ``coreaudio_exclusive`` (macOS only)
     Native macOS audio output driver using direct device access and
     exclusive mode (bypasses the sound server).
 
+``avfoundation`` (macOS only)
+    Native macOS audio output driver using ``AVSampleBufferAudioRenderer``
+    in AVFoundation, which supports `spatial audio
+    <https://support.apple.com/en-us/HT211775>`_.
+
+    .. warning::
+
+        Turning on spatial audio may hang the playback
+        if mpv is not started out of the bundle,
+        though playback with spatial audio off always works.
+
 ``openal``
     OpenAL audio output driver.
 
@@ -131,15 +184,12 @@ Available audio output drivers are:
         changes. "native" lets the sound server determine buffers.
 
     ``--pulse-latency-hacks=<yes|no>``
-        Enable hacks to workaround PulseAudio timing bugs (default: no). If
+        Enable hacks to workaround PulseAudio timing bugs (default: yes). If
         enabled, mpv will do elaborate latency calculations on its own. If
         disabled, it will use PulseAudio automatically updated timing
         information. Disabling this might help with e.g. networked audio or
         some plugins, while enabling it might help in some unknown situations
-        (it used to be required to get good behavior on old PulseAudio versions).
-
-        If you have stuttering video when using pulse, try to enable this
-        option. (Or try to update PulseAudio.)
+        (it is currently enabled due to known bugs with PulseAudio 16.0).
 
     ``--pulse-allow-suspended=<yes|no>``
         Allow mpv to use PulseAudio even if the sink is suspended (default: no).
@@ -167,8 +217,8 @@ Available audio output drivers are:
         By default the channel volumes are used.
 
 ``sdl``
-    SDL 1.2+ audio output driver. Should work on any platform supported by SDL
-    1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
+    SDL 2.0+ audio output driver. Should work on any platform supported by SDL
+    2.0, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
     appropriately for your system.
 
     .. note:: This driver is for compatibility with extremely foreign