From af3bbb800d709f81c9f30bc4ced26c98ea5eafd6 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Mon, 15 Dec 2014 17:14:23 +0100
Subject: [PATCH] audio: make native channel count the default instead of
 stereo downmix

This should work well with most audio APIs, except ALSA. A long-winded
explanation is provided how to make ALSA multichannel output work.

All other AOs should have no such problems. Of course it's possible
that previously unknown issues arise, because I assume that enabling
multichannel audio is actually relatively rare.

This also disables codec downmix by default, which could change the
audio output due to different mixing in the codec and libavresample.

Fixes #1313.
---
 DOCS/man/ao.rst      | 30 ++++++++++++++++++++++++++++++
 DOCS/man/options.rst |  8 ++++----
 options/options.c    |  2 +-
 3 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
index 258548b514..8c1966dcc4 100644
--- a/DOCS/man/ao.rst
+++ b/DOCS/man/ao.rst
@@ -68,6 +68,36 @@ Available audio output drivers are:
         shells (like zsh), you have to quote the option string to prevent the
         shell from interpreting the brackets instead of passing them to mpv.
 
+        Actually, you should use the ``--audio-device`` option, instead of
+        setting the device directly.
+
+    .. warning::
+
+        Handling of multichannel/surround audio changed in mpv 0.8.0 from the
+        behavior in MPlayer/mplayer2 and older versions of mpv.
+
+        The old behavior is that the player always downmixed to stereo by
+        default. The ``--audio-channels`` (or ``--channels`` before that) option
+        had to be set to get multichannel audio. Then playing stereo would
+        use the ``default`` device (which typically allows multiple programs
+        to play audio at the same time via dmix), while playing anything with
+        more channels would open one of the hardware devices, e.g. via the
+        ``surround51`` alias (typically with exclusive access). Whether the
+        player would use exclusive access or not would depend on the file
+        being played.
+
+        The new behavior since mpv 0.8.0 always enables multichannel audio,
+        i.e. ``--audio-channels=auto`` is the default. However, since ALSA
+        provides no good way to play multichannel audio in a non-exclusive
+        way (without blocking other applications from using audio), the player
+        is restricted to the capabilities of the ``default`` device by default,
+        which means it supports only stereo and mono. But if a hardware device
+        is selected, then multichannel audio will typically work.
+
+        The short story is: if you want multichannel audio with ALSA, use
+        ``--audio-device`` to select the device (use ``--audio-device=help``
+        to get a list of all devices and their mpv name).
+
 ``oss``
     OSS audio output driver
 
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 7ae04a3b26..4bc7054ba6 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -932,7 +932,7 @@ Audio
     ``--dtshd`` and ``--no-dtshd`` are deprecated aliases.
 
 ``--audio-channels=<number|layout>``
-    Request a channel layout for audio output (default: stereo). This  will ask
+    Request a channel layout for audio output (default: auto). This  will ask
     the AO to open a device with the given channel layout. It's up to the AO
     to accept this layout, or to pick a fallback or to error out if the
     requested layout is not supported.
@@ -945,9 +945,9 @@ Audio
     lists speaker names, which can be used to express arbitrary channel
     layouts (e.g. ``fl-fr-lfe`` is 2.1).
 
-    You can use ``--audio-channels=auto`` to disable this. In this case, the AO
-    use the channel layout as the audio filter chain indicates. (``empty`` is
-    an accepted obsolete for ``auto``.)
+    The default is ``--audio-channels=auto``, which tries to play audio using
+    the input file's channel layout. (Or more precisely, the output of the
+    audio filter chain.) (``empty`` is an accepted obsolete alias for ``auto``.)
 
     This will also request the channel layout from the decoder. If the decoder
     does not support the layout, it will fall back to its native channel layout.
diff --git a/options/options.c b/options/options.c
index e3afe5ab14..1eb687d1b2 100644
--- a/options/options.c
+++ b/options/options.c
@@ -749,7 +749,7 @@ const struct MPOpts mp_default_opts = {
     .sub_visibility = 1,
     .sub_pos = 100,
     .sub_speed = 1.0,
-    .audio_output_channels = MP_CHMAP_INIT_STEREO,
+    .audio_output_channels = {0}, // auto
     .audio_output_format = 0,  // AF_FORMAT_UNKNOWN
     .playback_speed = 1.,
     .pitch_correction = 1,