Add information about the -m option.

3 files changed, 129 insertions, 31 deletions

diff --git a/man/shairport-sync.7 b/man/shairport-sync.7
index 6cf9ce0..f41215d 100644
--- a/man/shairport-sync.7
+++ b/man/shairport-sync.7
@@ -94,21 +94,30 @@ Print debug information. Repeat up to three times to get more detail.
 Wait for commands specified using \fB-B\f1 or \fB-E\f1 to complete before continuing execution. 
 .SH AUDIO BACKEND OPTIONS
 These options are passed to the chosen audio backend. (At present, the only backend implemented is for ALSA.) The audio backend options are preceded by a \fB--\f1 symbol to introduce them and to separate them from any program options. In this way, option letters can be used as program options and also as audio backend options without ambiguity.
+
+In the ALSA backend, audio is sent to an output device which you can specify using the \fB-d\f1 option. The output level (the "volume") is controlled using a level control associated with a mixer. By default, the mixer is implemented in shairport-sync itself, i.e. the type of the mixer is "software". To use a level control on a mixer on the sound card, you must (a) specify that the mixer's type is "hardware" with the \fB-t\f1 option; (b) you must specify where the mixer is to be found using the \fB-m\f1 option and finally (c) you must specify the name of the level control you are using with the \fB-c\f1 option.
 .TP
 \fB-c \f1\fIcontrolname\f1
-Use the hardware volume control called \fIcontrolname\f1. This is needed if the output type is specified, using the \fB-t\f1 option, to be \fBhardware\f1. There is no default. 
+Use the level control called \fIcontrolname\f1 on the hardware mixer for controlling volume. This is needed if the mixer type is specified, using the \fB-t\f1 option, to be \fBhardware\f1. There is no default. 
 .TP
 \fB-d \f1\fIdevice\f1
-Use the specified output \fIdevice\f1. The default is the device named \fBdefault\f1. 
+Use the specified output \fIdevice\f1. You may specify a card, e.g. \fBhw:0\f1, in which case the default output device on the card will be chosen. Alternatively, you can specify a specific device on a card, e.g. \fBhw:0,0\f1. The default is the device named \fBdefault\f1. 
+.TP
+\fB-m \f1\fImixer\f1
+Use the specified hardware \fImixer\f1 for volume control. Use this to specify where the mixer is to be found. For example, if the mixer is associated with a card, as is often the case, specify the card, e.g. \fBhw:0\f1. If (unusually) the mixer is associated with a specific device on a card, specify the device, e.g. \fBhw:0,1\f1. The default is the device named in the \fB-d\f1 option, if given, or the device named \fBdefault\f1. 
 .TP
 \fB-t \f1\fIdevicetype\f1
-The type of the output device is \fIdevicetype\f1 which must be \fBhardware\f1 or \fBsoftware\f1. The default is \fBsoftware\f1. If you specify \fBhardware\f1 you must also specify the name of the volume control using the \fB-c\f1 option. 
+The type of the output device is \fIdevicetype\f1 which must be \fBhardware\f1 or \fBsoftware\f1. The default is \fBsoftware\f1. If you specify \fBhardware\f1 you must also specify the output device using the \fB-d\f1 option and the name of the volume control using the \fB-c\f1 option. You may also need to specify the mixer using the \fB-m\f1 option. 
 .SH EXAMPLES
-Here is a typical example:
+Here is a slightly contrived but typical example:
 
-shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1\f1 \fB-t hardware\f1 \fB-c PCM\f1
+shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1,0\f1 \fB-m hw:1\f1 \fB-t hardware\f1 \fB-c PCM\f1
 
-The program will run in daemon mode ( \fB-d\f1 ), will be visible as "Joe's Stereo" ( \fB-a "Joe's Stereo"\f1 ) and will use the SoX Resampler Library-based stuffing ( \fB-S soxr\f1 ). The audio backend options following the \fB--\f1 separator specify that the audio will be output on the ALSA device called hw:1 ( \fB-d hw:1\f1 ), and will take advantage of that device's hardware ( \fB-t hardware\f1 ) mixer named "PCM" ( \fB-c "PCM"\f1 ). 
+The program will run in daemon mode ( \fB-d\f1 ), will be visible as "Joe's Stereo" ( \fB-a "Joe's Stereo"\f1 ) and will use the SoX Resampler Library-based stuffing ( \fB-S soxr\f1 ). The audio backend options following the \fB--\f1 separator specify that the audio will be output on output 0 of soundcard 1 ( \fB-d hw:1,0\f1 ) and will take advantage of the same sound card's hardware (\fB-t hardware\f1) mixer ( \fB-m hw:1\f1 ) using the level control named "PCM" ( \fB-c "PCM"\f1 ). 
+
+The example above is slightly contrived in order to show the use of the \fB-m\f1 option. Typically, output 0 is the default output of a card, so the output device could be written \fB-d hw:1\f1 and then the mixer option would be unnecessary, giving the following, simpler, command:
+
+shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1\f1 \fB-t hardware\f1 \fB-c PCM\f1
 .SH CREDITS
 Mike Brady developed shairport-sync from the original shairport by James Laird.
 
diff --git a/man/shairport-sync.7.xml b/man/shairport-sync.7.xml
index 66e7b0e..b6a030f 100644
--- a/man/shairport-sync.7.xml
+++ b/man/shairport-sync.7.xml
@@ -284,13 +284,24 @@
   preceded by a <opt>--</opt> symbol to introduce them and to separate them from any
   program options. In this way, option letters can be used  as  program
   options and also as audio backend options without ambiguity.</p>
+  <p>In the ALSA backend, audio is sent to an output device
+  which you can specify using the <opt>-d</opt> option.
+  The output level (the "volume") is controlled using a level control associated with a mixer.
+  By default, the mixer is implemented in shairport-sync itself, i.e. the type of
+  the mixer is "software".
+  To use a level control on a mixer on the sound card, you must (a)
+  specify that the mixer's type is "hardware" with the <opt>-t</opt> option;
+  (b) you must specify where the mixer is to be found using the <opt>-m</opt> option
+  and finally (c) you must specify the name of the level control you are using
+  with the <opt>-c</opt> option.</p>
   </section>
   
   <option>
   <p><opt>-c </opt><arg>controlname</arg></p>
   <optdesc><p>
-  Use the hardware volume control called <arg>controlname</arg>. This is needed if
-  the output type is specified, using the <opt>-t</opt> option,
+  Use the level control called <arg>controlname</arg> on the hardware mixer for
+  controlling volume.
+  This is needed if the mixer type is specified, using the <opt>-t</opt> option,
   to be <opt>hardware</opt>. There is no default.
   </p></optdesc>
   </option>
@@ -298,39 +309,72 @@
   <option>
   <p><opt>-d </opt><arg>device</arg></p>
   <optdesc><p>
-  Use the specified output <arg>device</arg>.
+  Use the specified output <arg>device</arg>. You may specify a card, e.g. <opt>hw:0</opt>, in
+  which case the default output device on the card will be chosen.
+  Alternatively, you can specify a specific device on a card, e.g. <opt>hw:0,0</opt>.
   The default is the device named <opt>default</opt>.
   </p></optdesc>
   </option>
 
   <option>
-  <p><opt>-t </opt><arg>devicetype</arg></p>
+  <p><opt>-m </opt><arg>mixer</arg></p>
   <optdesc><p>
+  Use the specified hardware <arg>mixer</arg> for volume control. Use this to specify where
+  the mixer is to be found. For example, if the mixer is associated with a card,
+  as is often the case, specify the card, e.g. <opt>hw:0</opt>.
+  If (unusually) the mixer is associated with a specific device on a card,
+  specify the device, e.g. <opt>hw:0,1</opt>.
+  The default is the device named in the <opt>-d</opt> option,
+  if given, or the device named <opt>default</opt>.
+  </p></optdesc>
+  </option>
+
+  <option>
+  <p><opt>-t </opt><arg>devicetype</arg></p>
+  <optdesc>
+  <p>
   The type of the output device is <arg>devicetype</arg> which must be
   <opt>hardware</opt> or <opt>software</opt>. The default is <opt>software</opt>.
-  If you specify <opt>hardware</opt> you must also specify the name of the
-  volume control using the <opt>-c</opt> option.
+  If you specify <opt>hardware</opt> you must also specify the output device using the
+  <opt>-d</opt> option and the name of the volume control using the <opt>-c</opt> option.
+  You may also need to specify the mixer using the <opt>-m</opt> option.
   </p></optdesc>
   </option>
 	</options>
 
   <section name="Examples">
-  <p>Here is a typical example:</p>
+  <p>Here is a slightly contrived but typical example:</p>
       <cmd>shairport-sync  <opt>-d</opt>
       <opt>-a "Joe's Stereo"</opt>
       <opt>-S soxr</opt>
       <opt>--</opt>
-      <opt>-d hw:1</opt>
+      <opt>-d hw:1,0</opt>
+      <opt>-m hw:1</opt>
       <opt>-t hardware</opt>
       <opt>-c PCM</opt>      
       </cmd>
   <p>The program will run in daemon mode ( <opt>-d</opt> ), will be  visible  as
-  "Joe's Stereo" ( <opt>-a "Joe's Stereo"</opt> ) and will use the SoX Resampler Library-based stuffing ( <opt>-S soxr</opt> ).
-  The audio backend options following  the  <opt>--</opt>  separator  specify
-  that  the  audio will be output on the ALSA device called hw:1 (
-  <opt>-d hw:1</opt> ), and will take advantage of that device's  hardware  (
-  <opt>-t hardware</opt> ) mixer named "PCM" ( <opt>-c "PCM"</opt> ).
+  "Joe's Stereo" ( <opt>-a "Joe's Stereo"</opt> ) and will use the SoX Resampler
+  Library-based stuffing ( <opt>-S soxr</opt> ).
+  The audio backend options following the <opt>--</opt> separator specify
+  that  the  audio will be output on output 0 of soundcard 1 (
+  <opt>-d hw:1,0</opt> ) and will take advantage of the same sound card's hardware
+  (<opt>-t hardware</opt>) mixer ( <opt>-m hw:1</opt> )
+  using the level control named "PCM" ( <opt>-c "PCM"</opt> ).
   </p>
+  <p>The example above is slightly contrived in order to show the use of the <opt>-m</opt> option.
+  Typically, output 0 is the default output of a card,
+  so the output device could be written <opt>-d hw:1</opt> and
+  then the mixer option would be unnecessary, giving the following, simpler, command:</p>
+       <cmd>shairport-sync  <opt>-d</opt>
+      <opt>-a "Joe's Stereo"</opt>
+      <opt>-S soxr</opt>
+      <opt>--</opt>
+      <opt>-d hw:1</opt>
+      <opt>-t hardware</opt>
+      <opt>-c PCM</opt>      
+      </cmd>
+ 
   </section>
 
 	<section name="Credits">
diff --git a/man/shairport-sync.html b/man/shairport-sync.html
index 420e21b..2dcccb5 100644
--- a/man/shairport-sync.html
+++ b/man/shairport-sync.html
@@ -270,14 +270,25 @@
   preceded by a <b>--</b> symbol to introduce them and to separate them from any
   program options. In this way, option letters can be used  as  program
   options and also as audio backend options without ambiguity.</p>
+  <p>In the ALSA backend, audio is sent to an output device
+  which you can specify using the <b>-d</b> option.
+  The output level (the &quot;volume&quot;) is controlled using a level control associated with a mixer.
+  By default, the mixer is implemented in shairport-sync itself, i.e. the type of
+  the mixer is &quot;software&quot;.
+  To use a level control on a mixer on the sound card, you must (a)
+  specify that the mixer's type is &quot;hardware&quot; with the <b>-t</b> option;
+  (b) you must specify where the mixer is to be found using the <b>-m</b> option
+  and finally (c) you must specify the name of the level control you are using
+  with the <b>-c</b> option.</p>
   
 
   
   
   <p><b>-c </b><em>controlname</em></p>
   <p>
-  Use the hardware volume control called <em>controlname</em>. This is needed if
-  the output type is specified, using the <b>-t</b> option,
+  Use the level control called <em>controlname</em> on the hardware mixer for
+  controlling volume.
+  This is needed if the mixer type is specified, using the <b>-t</b> option,
   to be <b>hardware</b>. There is no default.
   </p>
   
@@ -285,41 +296,75 @@
   
   <p><b>-d </b><em>device</em></p>
   <p>
-  Use the specified output <em>device</em>.
+  Use the specified output <em>device</em>. You may specify a card, e.g. <b>hw:0</b>, in
+  which case the default output device on the card will be chosen.
+  Alternatively, you can specify a specific device on a card, e.g. <b>hw:0,0</b>.
   The default is the device named <b>default</b>.
   </p>
   
 
   
+  <p><b>-m </b><em>mixer</em></p>
+  <p>
+  Use the specified hardware <em>mixer</em> for volume control. Use this to specify where
+  the mixer is to be found. For example, if the mixer is associated with a card,
+  as is often the case, specify the card, e.g. <b>hw:0</b>.
+  If (unusually) the mixer is associated with a specific device on a card,
+  specify the device, e.g. <b>hw:0,1</b>.
+  The default is the device named in the <b>-d</b> option,
+  if given, or the device named <b>default</b>.
+  </p>
+  
+
+  
   <p><b>-t </b><em>devicetype</em></p>
+  
   <p>
   The type of the output device is <em>devicetype</em> which must be
   <b>hardware</b> or <b>software</b>. The default is <b>software</b>.
-  If you specify <b>hardware</b> you must also specify the name of the
-  volume control using the <b>-c</b> option.
+  If you specify <b>hardware</b> you must also specify the output device using the
+  <b>-d</b> option and the name of the volume control using the <b>-c</b> option.
+  You may also need to specify the mixer using the <b>-m</b> option.
   </p>
   
 	
 
   <h2>Examples</h2>
 
-  <p>Here is a typical example:</p>
+  <p>Here is a slightly contrived but typical example:</p>
       shairport-sync  <b>-d</b>
       <b>-a &quot;Joe's Stereo&quot;</b>
       <b>-S soxr</b>
       <b>--</b>
-      <b>-d hw:1</b>
+      <b>-d hw:1,0</b>
+      <b>-m hw:1</b>
       <b>-t hardware</b>
       <b>-c PCM</b>      
       <br>
 
   <p>The program will run in daemon mode ( <b>-d</b> ), will be  visible  as
-  &quot;Joe's Stereo&quot; ( <b>-a &quot;Joe's Stereo&quot;</b> ) and will use the SoX Resampler Library-based stuffing ( <b>-S soxr</b> ).
-  The audio backend options following  the  <b>--</b>  separator  specify
-  that  the  audio will be output on the ALSA device called hw:1 (
-  <b>-d hw:1</b> ), and will take advantage of that device's  hardware  (
-  <b>-t hardware</b> ) mixer named &quot;PCM&quot; ( <b>-c &quot;PCM&quot;</b> ).
+  &quot;Joe's Stereo&quot; ( <b>-a &quot;Joe's Stereo&quot;</b> ) and will use the SoX Resampler
+  Library-based stuffing ( <b>-S soxr</b> ).
+  The audio backend options following the <b>--</b> separator specify
+  that  the  audio will be output on output 0 of soundcard 1 (
+  <b>-d hw:1,0</b> ) and will take advantage of the same sound card's hardware
+  (<b>-t hardware</b>) mixer ( <b>-m hw:1</b> )
+  using the level control named &quot;PCM&quot; ( <b>-c &quot;PCM&quot;</b> ).
   </p>
+  <p>The example above is slightly contrived in order to show the use of the <b>-m</b> option.
+  Typically, output 0 is the default output of a card,
+  so the output device could be written <b>-d hw:1</b> and
+  then the mixer option would be unnecessary, giving the following, simpler, command:</p>
+       shairport-sync  <b>-d</b>
+      <b>-a &quot;Joe's Stereo&quot;</b>
+      <b>-S soxr</b>
+      <b>--</b>
+      <b>-d hw:1</b>
+      <b>-t hardware</b>
+      <b>-c PCM</b>      
+      <br>
+
+