[pulseaudio-commits] src/pulse

[Tanu Kaskinen]

 src/pulse/introspect.h |   28 ++++++++++++++++++++++++++++
 src/pulse/stream.h     |   14 +++++++++++++-
 src/pulse/volume.h     |   15 +++++++++++++++
 3 files changed, 56 insertions(+), 1 deletion(-)

New commits:
commit 3535fd7a076228fdeae3755cf8ac6fdcfa28741d
Author: Alexander E. Patrakov <patrakov at gmail.com>
Date:   Tue Oct 22 00:19:27 2013 +0100

    Documentation of known misuse of PulseAudio API
    
    Hello.
    
    Over time, I became aware of several instances of tempting but
    semantically incorrect usage of PulseAudio API (one from my own bad
    proposal of "improving" Wine, one from Parole media player and one
    from Webkit-GTK). I want to document these gotchas so that other
    developers don't fall for that. See the attached patch.
    
    I have checked that the rendered HTML is correct, but need someone to
    confirm the factual accuracy of the proposed changes and, possibly, to
    improve the wording.
    
    --
    Alexander E. Patrakov

diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h
index 023b418..e7224c6 100644
--- a/src/pulse/introspect.h
+++ b/src/pulse/introspect.h
@@ -173,6 +173,34 @@
  * \li Sink input - pa_context_kill_sink_input()
  * \li Source output - pa_context_kill_source_output()
  *
+ * It is strongly recommended that all volume changes are done as a direct
+ * result of user input. With automated requests, such as those resulting
+ * from misguided attempts of crossfading, PulseAudio can store the stream
+ * volume at an inappropriate moment and restore it later. Besides, such
+ * attempts lead to OSD popups in some desktop environments.
+ *
+ * As a special case of the general rule above, it is recommended that your
+ * application leaves the task of saving and restoring the volume of its
+ * streams to PulseAudio and does not attempt to do it by itself. PulseAudio
+ * really knows better about events such as stream moving or headphone
+ * plugging that would make the volume stored by the application inapplicable
+ * to the new configuration.
+ *
+ * Another important case where setting a sink input volume may be a bad idea
+ * is related to interpreters that interpret potentially untrusted scripts.
+ * PulseAudio relies on your application not making malicious requests (such
+ * as repeatedly setting the volume to 100%). Thus, script interpreters that
+ * represent a security boundary must sandbox volume-changing requests coming
+ * from their scripts. In the worst case, it may be necessary to apply the
+ * script-requested volume to the script-produced sounds by altering the
+ * samples in the script interpreter and not touching the sink or sink input
+ * volume as seen by PulseAudio.
+ *
+ * If an application changes any volume, it should also listen to changes of
+ * the same volume originating from outside the application (e.g., from the
+ * system mixer application) and update its user interface accordingly. Use
+ * \ref subscribe to get such notifications.
+ *
  * \subsection module_subsec Modules
  *
  * Server modules can be remotely loaded and unloaded using
diff --git a/src/pulse/stream.h b/src/pulse/stream.h
index 9fab629..40cbe64 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -71,6 +71,16 @@
  * pa_stream_set_state_callback(), and wait for the stream to enter an active
  * state.
  *
+ * Note: there is a user-controllable slider in mixer applications such as
+ * pavucontrol corresponding to each of the created streams. Multiple
+ * (especially identically named) volume sliders for the same application might
+ * confuse the user. Also, the server supports only a limited number of
+ * simultaneous streams. Because of this, it is not always appropriate to
+ * create multiple streams in one application that needs to output multiple
+ * sounds. The rough guideline is: if there is no use case that would require
+ * separate user-initiated volume changes for each stream, perform the mixing
+ * inside the application.
+ *
  * \subsection bufattr_subsec Buffer Attributes
  *
  * Playback and record streams always have a server-side buffer as
@@ -435,7 +445,9 @@ int pa_stream_is_corked(pa_stream *s);
  * 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(). It is possible
+ * to figure out whether flat volume mode is in effect for a given sink
+ * by calling pa_context_get_sink_info_by_name(). */
 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 */ ,
diff --git a/src/pulse/volume.h b/src/pulse/volume.h
index ab6c59b..7806954 100644
--- a/src/pulse/volume.h
+++ b/src/pulse/volume.h
@@ -47,6 +47,21 @@
  * Volumes commonly span between muted (0%), and normal (100%). It is possible
  * to set volumes to higher than 100%, but clipping might occur.
  *
+ * There is no single well-defined meaning attached to the 100% volume for a
+ * sink input. In fact, it depends on the server configuration. With flat
+ * volumes enabled (the default in most Linux distributions), it means the
+ * maximum volume that the sound hardware is capable of, which is usually so
+ * high that you absolutely must not set sink input volume to 100% unless the
+ * the user explicitly requests that (note that usually you shouldn't set the
+ * volume anyway if the user doesn't explicitly request it, instead, let
+ * PulseAudio decide the volume for the sink input). With flat volumes disabled
+ * (the default in Ubuntu), the sink input volume is relative to the sink
+ * volume, so 100% sink input volume means that the sink input is played at the
+ * current sink volume level. In this case 100% is often a good default volume
+ * for a sink input, although you still should let PulseAudio decide the
+ * default volume. It is possible to figure out whether flat volume mode is in
+ * effect for a given sink by calling pa_context_get_sink_info_by_name().
+ *
  * \section calc_sec Calculations
  *
  * The volumes in PulseAudio are logarithmic in nature and applications