LibVLC: improve mute documentation

diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h
index cc575218a9341d3f8371cff1c2e0e3440edca9f2..809ed5f199c09c5e11c2a8b8d952fbb2ea0bf0e8 100644 (file)
--- a/include/vlc/libvlc_media_player.h
+++ b/include/vlc/libvlc_media_player.h
@@ -1461,6 +1461,10 @@ LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *p_mi
  * Toggle mute status.
  *
  * \param p_mi media player
+ * \warning Toggling mute atomically is not always possible: On some platforms,
+ * other processes can mute the VLC audio playback stream asynchronously. Thus,
+ * there is a small race condition where toggling will not work.
+ * See also the limitations of libvlc_audio_set_mute().
  */
 LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
 
@@ -1468,9 +1472,7 @@ LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
  * Get current mute status.
  *
  * \param p_mi media player
- * \return the mute status (boolean)
- *
- * \libvlc_return_bool
+ * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
  */
 LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
 
@@ -1479,6 +1481,12 @@ LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
  *
  * \param p_mi media player
  * \param status If status is true then mute, otherwise unmute
+ * \warning This function does not always work. If there are no active audio
+ * playback stream, the mute status might not be available. If digital
+ * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
+ * some audio output plugins do not support muting at all.
+ * \note To force silent playback, disable all audio tracks. This is more
+ * efficient and reliable than mute.
  */
 LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
 

diff --git a/lib/audio.c b/lib/audio.c
index a26733ead28c8525332288046fcdc1bd73e45f24..c7cf02a250b834248c068d22c2edf10374e9946e 100644 (file)
--- a/lib/audio.c
+++ b/lib/audio.c
@@ -308,9 +308,6 @@ void libvlc_audio_output_set_device_type( libvlc_media_player_t *mp,
     vlc_object_release( p_aout );
 }
 
-/*****************************************************************************
- * libvlc_audio_get_mute : Get the volume state, true if muted
- *****************************************************************************/
 void libvlc_audio_toggle_mute( libvlc_media_player_t *mp )
 {
     aout_MuteToggle( mp );