From 5d70f1226b9046d814a8efe4b00453b68805e34c Mon Sep 17 00:00:00 2001
From: Tanu Kaskinen <tanuk@iki.fi>
Date: Fri, 14 Feb 2020 11:01:04 +0200
Subject: [PATCH] alsa: Document that mixer elements can be identified by a
 combination of name and index

---
 src/modules/alsa/mixer/paths/analog-output.conf.common | 3 ++-
 src/modules/alsa/mixer/profile-sets/default.conf       | 6 ++++--
 src/modules/alsa/module-alsa-sink.c                    | 2 +-
 src/modules/alsa/module-alsa-source.c                  | 2 +-
 4 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/modules/alsa/mixer/paths/analog-output.conf.common b/src/modules/alsa/mixer/paths/analog-output.conf.common
index e52830d990ed..7bf346346fe3 100644
--- a/src/modules/alsa/mixer/paths/analog-output.conf.common
+++ b/src/modules/alsa/mixer/paths/analog-output.conf.common
@@ -85,7 +85,8 @@
 ; required-any = ignore | enumeration | any        # In this element, either this or another option must exist (or an element)
 ; required-absent = ignore | enumeration | any     # In this element, this option must not exist or the path will be invalid
 ;
-; [Element ...]                          # For each element that we shall control
+; [Element ...]                          # For each element that we shall control. The "..." here is the element name,
+;                                        # or name and index separated by a comma.
 ; required = ignore | switch | volume | enumeration | any     # If set, require this element to be of this kind and available,
 ;                                                             # otherwise don't consider this path valid for the card
 ; required-any = ignore | switch | volume | enumeration | any # If set, at least one of the elements or jacks with required-any in this
diff --git a/src/modules/alsa/mixer/profile-sets/default.conf b/src/modules/alsa/mixer/profile-sets/default.conf
index 34c51bc5bf0a..c73bf5cea33f 100644
--- a/src/modules/alsa/mixer/profile-sets/default.conf
+++ b/src/modules/alsa/mixer/profile-sets/default.conf
@@ -49,7 +49,8 @@
 ;                                           # If multiple are found to be working they will be available as device ports
 ; paths-output = ...
 ; element-input = ...                       # Instead of configuring a full mixer path simply configure a single
-;                                           # mixer element for volume/mute handling
+;                                           # mixer element for volume/mute handling. The value can be an element
+;                                           # name, or name and index separated by a comma.
 ; element-output = ...
 ; priority = ...
 ; direction = any | input | output          # Only useful for?
@@ -72,7 +73,8 @@
 ; [DecibelFix element]                      # Decibel fixes can be used to work around missing or incorrect dB
 ;                                           # information from alsa. A decibel fix is a table that maps volume steps
 ;                                           # to decibel values for one volume element. The "element" part in the
-;                                           # section title is the name of the volume element.
+;                                           # section title is the name of the volume element (or name and index
+;                                           # separated by a comma).
 ;                                           #
 ;                                           # NOTE: This feature is meant just as a help for figuring out the correct
 ;                                           # decibel values. PulseAudio is not the correct place to maintain the
diff --git a/src/modules/alsa/module-alsa-sink.c b/src/modules/alsa/module-alsa-sink.c
index 4d4beb3cd487..a90c5e493514 100644
--- a/src/modules/alsa/module-alsa-sink.c
+++ b/src/modules/alsa/module-alsa-sink.c
@@ -52,7 +52,7 @@ PA_MODULE_USAGE(
         "tsched_buffer_size=<buffer size when using timer based scheduling> "
         "tsched_buffer_watermark=<lower fill watermark> "
         "ignore_dB=<ignore dB information from the device?> "
-        "control=<name of mixer control> "
+        "control=<name of mixer control, or name and index separated by a comma> "
         "rewind_safeguard=<number of bytes that cannot be rewound> "
         "deferred_volume=<Synchronize software and hardware volume changes to avoid momentary jumps?> "
         "deferred_volume_safety_margin=<usec adjustment depending on volume direction> "
diff --git a/src/modules/alsa/module-alsa-source.c b/src/modules/alsa/module-alsa-source.c
index 747ba934212e..d15228316e09 100644
--- a/src/modules/alsa/module-alsa-source.c
+++ b/src/modules/alsa/module-alsa-source.c
@@ -61,7 +61,7 @@ PA_MODULE_USAGE(
         "tsched_buffer_size=<buffer size when using timer based scheduling> "
         "tsched_buffer_watermark=<upper fill watermark> "
         "ignore_dB=<ignore dB information from the device?> "
-        "control=<name of mixer control>"
+        "control=<name of mixer control, or name and index separated by a comma>"
         "deferred_volume=<Synchronize software and hardware volume changes to avoid momentary jumps?> "
         "deferred_volume_safety_margin=<usec adjustment depending on volume direction> "
         "deferred_volume_extra_delay=<usec adjustment to HW volume changes> "
-- 
2.16.4