[pulseaudio-discuss] [PATCH v2 16/18] stream: Improve pa_stream_connect_playback() documentation

[Tanu Kaskinen]

---
 src/pulse/stream.h | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/pulse/stream.h b/src/pulse/stream.h
index 9821ab8..9bf7dd2 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -466,7 +466,16 @@ int pa_stream_set_volume_channel_map(
  * an absolute device volume. Since 0.9.20 it is an absolute volume when
  * the sink is in flat volume mode, and relative otherwise, thus
  * making sure the volume passed here has always the same semantics as
- * the volume passed to pa_context_set_sink_input_volume(). */
+ * the volume passed to pa_context_set_sink_input_volume().
+ *
+ * Since 5.0, it's possible to specify a single-channel volume even if the
+ * stream has multiple channels. In that case the same volume is applied to all
+ * channels.
+ *
+ * If you create the stream with pa_stream_new_extended() and you don't specify
+ * the channel map for the stream, and you specify a multi-channel volume here,
+ * then you have to use pa_stream_set_volume_channel_map() so that the server
+ * can figure out what your multi-channel volume actually means. */
 int pa_stream_connect_playback(
         pa_stream *s                  /**< The stream to connect to a sink */,
         const char *dev               /**< Name of the sink to connect to, or NULL for default */ ,
-- 
1.8.3.1