[pulseaudio-discuss] [PATCH v3 3/3] pactl: Document ability to specify channel volumes individually

[Peter Meerwald]

Signed-off-by: Peter Meerwald <pmeerw at pmeerw.net>
---
 man/pactl.1.xml.in | 20 ++++++++++++--------
 src/utils/pactl.c  |  4 ++--
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in
index 29071b3..a195b1d 100644
--- a/man/pactl.1.xml.in
+++ b/man/pactl.1.xml.in
@@ -189,33 +189,37 @@ USA.
     </option>
 
     <option>
-      <p><opt>set-sink-volume</opt> <arg>SINK</arg> <arg>VOLUME</arg></p>
+      <p><opt>set-sink-volume</opt> <arg>SINK</arg> <arg>VOLUME [VOLUME ...]</arg></p>
       <optdesc><p>Set the volume of the specified sink (identified by its symbolic name or numerical index).
       <arg>VOLUME</arg> can be specified as an integer (e.g. 2000, 16384), a linear factor (e.g. 0.4, 1.100), a percentage
       (e.g.  10%, 100%) or a decibel value (e.g. 0dB, 20dB).  If the volume specification start with a + or - the volume
-      adjustment will be relative to the current sink volume.</p></optdesc>
+      adjustment will be relative to the current sink volume.  A single volume value affects all channels; if multiple
+      volume values are given their number has to match the sink's number of channels.</p></optdesc>
     </option>
 
     <option>
-      <p><opt>set-source-volume</opt> <arg>SOURCE</arg> <arg>VOLUME</arg></p>
+      <p><opt>set-source-volume</opt> <arg>SOURCE</arg> <arg>VOLUME [VOLUME ...]</arg></p>
       <optdesc><p>Set the volume of the specified source (identified by its symbolic name or numerical index).
       <arg>VOLUME</arg> can be specified as an integer (e.g. 2000, 16384), a linear factor (e.g. 0.4, 1.100), a percentage
       (e.g.  10%, 100%) or a decibel value (e.g. 0dB, 20dB).  If the volume specification start with a + or - the volume
-      adjustment will be relative to the current source volume.</p></optdesc> </option>
+      adjustment will be relative to the current source volume.  A single volume value affects all channels; if multiple
+      volume values are given their number has to match the source's number of channels.</p></optdesc> </option>
 
     <option>
-      <p><opt>set-sink-input-volume</opt> <arg>INPUT</arg> <arg>VOLUME</arg></p>
+      <p><opt>set-sink-input-volume</opt> <arg>INPUT</arg> <arg>VOLUME [VOLUME ...]</arg></p>
       <optdesc><p>Set the volume of the specified sink input (identified by its numerical index).
       <arg>VOLUME</arg> can be specified as an integer (e.g. 2000, 16384), a linear factor (e.g. 0.4, 1.100), a percentage
       (e.g.  10%, 100%) or a decibel value (e.g. 0dB, 20dB).  If the volume specification start with a + or - the volume
-      adjustment will be relative to the current sink input volume.</p></optdesc> </option>
+      adjustment will be relative to the current sink input volume.  A single volume value affects all channels; if multiple
+      volume values are given their number has to match the sink input's number of channels.</p></optdesc> </option>
 
     <option>
-      <p><opt>set-source-output-volume</opt> <arg>OUTPUT</arg> <arg>VOLUME</arg></p>
+      <p><opt>set-source-output-volume</opt> <arg>OUTPUT</arg> <arg>VOLUME [VOLUME ...]</arg></p>
       <optdesc><p>Set the volume of the specified source output (identified by its numerical index).
       <arg>VOLUME</arg> can be specified as an integer (e.g. 2000, 16384), a linear factor (e.g. 0.4, 1.100), a percentage
       (e.g.  10%, 100%) or a decibel value (e.g. 0dB, 20dB).  If the volume specification start with a + or - the volume
-      adjustment will be relative to the current source output volume.</p></optdesc>
+      adjustment will be relative to the current source output volume.  A single volume value affects all channels; if multiple
+      volume values are given their number has to match the source output's number of channels.</p></optdesc>
     </option>
 
     <option>
diff --git a/src/utils/pactl.c b/src/utils/pactl.c
index 83ab991..6111490 100644
--- a/src/utils/pactl.c
+++ b/src/utils/pactl.c
@@ -1577,8 +1577,8 @@ static void help(const char *argv0) {
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-card-profile ", _("CARD PROFILE"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-default-(sink|source)", _("NAME"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink|source)-port", _("NAME|#N PORT"));
-    printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink|source)-volume", _("NAME|#N VOLUME"));
-    printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink-input|source-output)-volume", _("#N VOLUME"));
+    printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink|source)-volume", _("NAME|#N VOLUME [VOLUME ...]"));
+    printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink-input|source-output)-volume", _("#N VOLUME [VOLUME ...]"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink|source)-mute", _("NAME|#N 1|0|toggle"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink-input|source-output)-mute", _("#N 1|0|toggle"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-sink-formats", _("#N FORMATS"));
-- 
1.9.1