ao_coreaudio: add an option for changing the physical format

ao_coreaudio uses AudioUnit - the OSX software mixer. In theory, it
supports multichannel audio just fine. But in practice, this might be
disabled by default, and the user is supposed to select a multichannel
base format in the "Audio MIDI Setup" utility.

This option attempts to change this setting automatically. Some possible
disadvantages and caveats are listed in the manpage additions. It is off
by default, since changing this might be rather bad behavior for a
normal application.

1 files changed, 8 insertions, 0 deletions

diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
index 5103997e76..e02a5886ff 100644
--- a/DOCS/man/ao.rst
+++ b/DOCS/man/ao.rst
@@ -162,6 +162,14 @@ Available audio output drivers are:
     Automatically redirects to ``coreaudio_exclusive`` when playing compressed
     formats.
 
+    ``change-physical-format=<yes|no>``
+        Change the physical format to one similar to the requested audio format
+        (default: no). This has the advantage that multichannel audio output
+        will actually work. The disadvantage is that it will change the
+        system-wide audio settings. This is equivalent to change the ``Format``
+        setting in the ``Audio Devices`` dialog in the ``Audio MIDI Setup``
+        utility. Note that this does not effect the selected speaker setup.
+
 ``coreaudio_exclusive`` (Mac OS X only)
     Native Mac OS X audio output driver using direct device access and
     exclusive mode (bypasses the sound server).