From d8aeeaa4b15e9adbbd021614848c40d4ff264124 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Tue, 26 Jan 2016 15:12:42 +0100
Subject: command: always allow setting volume/mute properties

This seems generally easier when using libmpv (and was already requested
and implemented before: see commit 327a779a; it was reverted some time
later).

With the weird internal logic we have to deal with, in particular the
--softvol=no case (using system volume), and using the audio API's mixer
(--softvol=auto on some systems), we still can't avoid all glitches and
corner cases that complicate this issue so much. The API user is either
recommended to use --softvol=yes or auto, or to watch the new
mixer-active property, and assume the volume/mute properties have
significant values if the mixer is active.

Remaining glitches:
- changing the volume/mute properties has no effect if no internal mixer
  is used (--softvol=no) and the mixer is not active; the actual mixer
  controls do not change, only the property values
- --volume/--mute do not have an effect on the volume/mute properties
  before mixer initialization (the options strictly are only applied
  during mixer init)
- volume-max is 100 while the mixer is not active
---
 DOCS/man/input.rst | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

(limited to 'DOCS/man/input.rst')

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index c847b861b0..76678c2b3c 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -1224,11 +1224,30 @@ Property list
 ``hr-seek`` (RW)
     See ``--hr-seek``.
 
+``mixer-active``
+    Return ``yes`` if the audio mixer is active, ``no`` otherwise. This has
+    implications for ``--softvol=no`` mode: if the mixer is active, changing
+    ``volume`` doesn't actually change anything on the system mixer. If the
+    ``--volume`` or ``--mute`` option are used, these might not be applied
+    property until the mixer becomes active either. (The options, if set, will
+    just overwrite the mixer state at audio initialization.)
+
+    While the behavior with ``mixer-active==yes`` is relatively well-defined,
+    the ``no`` case will provide possibly wrong or insignificant values.
+
+    Note that an active mixer does not necessarily imply active audio output,
+    although this is implied in the current implementation.
+
 ``volume`` (RW)
-    Current volume (see ``--volume`` for details).
+    Current volume (see ``--volume`` for details). Also see ``mixer-active``
+    property.
+
+``volume-max``
+    Current maximum value the volume property can be set to. (This may depend
+    on the ``--softvol-max`` option.)
 
 ``mute`` (RW)
-    Current mute status (``yes``/``no``).
+    Current mute status (``yes``/``no``). Also see ``mixer-active`` property.
 
 ``audio-delay`` (RW)
     See ``--audio-delay``.
-- 
cgit v1.2.3