libvlc: thread-safe and more straight-forward audio devices API

Also improve documentation, and deprecate the old broken functions.

include/vlc/libvlc_media_player.h

@@ -72,6 +72,17 @@ typedef struct libvlc_audio_output_t
 
 } libvlc_audio_output_t;
 
+/**
+ * Description for audio output device.
+ */
+typedef struct libvlc_audio_output_device_t
+{
+    struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */
+    char *psz_device; /**< Device identifier string */
+    char *psz_description; /**< User-friendly device description */
+    /* More fields may be added here in later versions */
+} libvlc_audio_output_device_t;
+
 /**
  * Rectangle type for video geometry
  */
@@ -1362,7 +1373,7 @@ typedef enum libvlc_audio_output_channel_t {
 
 
 /**
- * Get the list of available audio outputs
+ * Gets the list of available audio outputs
  *
  * \param p_instance libvlc instance
  * \return list of available audio outputs. It must be freed it with
@@ -1370,18 +1381,20 @@ typedef enum libvlc_audio_output_channel_t {
  *         In case of error, NULL is returned.
  */
 LIBVLC_API libvlc_audio_output_t *
-        libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
+libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
 
 /**
- * Free the list of available audio outputs
+ * Frees the list of available audio outputs
  *
  * \param p_list list with audio outputs for release
  */
-LIBVLC_API void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
+LIBVLC_API
+void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
 
 /**
- * Set the audio output.
- * Change will be applied after stop and play.
+ * Sets the audio output.
+ * \note Any change will take be effect only after playback is stopped and
+ * restarted. Audio output cannot be changed while playing.
  *
  * \param p_mi media player
  * \param psz_name name of audio output,
@@ -1392,46 +1405,81 @@ LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
                                         const char *psz_name );
 
 /**
- * Get count of devices for audio output, these devices are hardware oriented
- * like analor or digital output of sound card
- *
- * \param p_instance libvlc instance
- * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
- * \return number of devices
+ * Backward compatibility stub. Do not use in new code.
+ * Use libvlc_audio_output_device_list_get() instead.
+ * \return always 0.
+ */
+LIBVLC_DEPRECATED
+int libvlc_audio_output_device_count( libvlc_instance_t *, const char * );
+
+/**
+ * Backward compatibility stub. Do not use in new code.
+ * Use libvlc_audio_output_device_list_get() instead.
+ * \return always NULL.
+ */
+LIBVLC_DEPRECATED
+char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *,
+                                           int );
+
+/**
+ * Backward compatibility stub. Do not use in new code.
+ * Use libvlc_audio_output_device_list_get() instead.
+ * \return always NULL.
  */
-LIBVLC_API int libvlc_audio_output_device_count( libvlc_instance_t *p_instance,
-                                                     const char *psz_audio_output );
+LIBVLC_DEPRECATED
+char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int );
 
 /**
- * Get long name of device, if not available short name given
+ * Gets a list of audio output devices for a given audio output.
+ * \see libvlc_audio_output_device_set().
+ *
+ * \note Not all audio outputs support this. In particular, an empty (NULL)
+ * list of devices does <b>not</b> imply that the specified audio output does
+ * not work.
+ *
+ * \note The list might not be exhaustive.
+ *
+ * \warning Some audio output devices in the list might not actually work in
+ * some circumstances. By default, it is recommended to not specify any
+ * explicit audio device.
  *
  * \param p_instance libvlc instance
- * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
- * \param i_device device index
- * \return long name of device
+ * \param psz_aout audio output name
+ *                 (as returned by libvlc_audio_output_list_get())
+ * \return A NULL-terminated linked list of potential audio output devices.
+ * It must be freed it with libvlc_audio_output_device_list_release()
+ * \version LibVLC 2.1.0 or later.
  */
-LIBVLC_API char * libvlc_audio_output_device_longname( libvlc_instance_t *p_instance,
-                                                           const char *psz_audio_output,
-                                                           int i_device );
+LIBVLC_API libvlc_audio_output_device_t *
+libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
+                                     const char *aout );
 
 /**
- * Get id name of device
+ * Frees a list of available audio output devices.
  *
- * \param p_instance libvlc instance
- * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
- * \param i_device device index
- * \return id name of device, use for setting device, need to be free after use
+ * \param p_list list with audio outputs for release
+ * \version LibVLC 2.1.0 or later.
  */
-LIBVLC_API char * libvlc_audio_output_device_id( libvlc_instance_t *p_instance,
-                                                     const char *psz_audio_output,
-                                                     int i_device );
+LIBVLC_API void libvlc_audio_output_device_list_release(
+                                        libvlc_audio_output_device_t *p_list );
 
 /**
- * Set audio output device. Changes are only effective after stop and play.
+ * Configures an explicit audio output device for a given audio output plugin.
+ * A list of possible devices can be obtained with
+ * libvlc_audio_output_device_list_get().
+ *
+ * \note This function does not select the specified audio output plugin.
+ * libvlc_audio_output_set() is used for that purpose.
+ *
+ * \warning The syntax for the device parameter depends on the audio output.
+ * This is not portable. Only use this function if you know what you are doing.
+ * Some audio outputs do not support this function (e.g. PulseAudio, WASAPI).
+ * Some audio outputs require further parameters (e.g. ALSA: channels map).
  *
  * \param p_mi media player
  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
  * \param psz_device_id device
+ * \return Nothing. Errors are ignored.
  */
 LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi,
                                                 const char *psz_audio_output,

lib/audio.c

@@ -135,119 +135,71 @@ int libvlc_audio_output_set( libvlc_media_player_t *mp, const char *psz_name )
     return 0;
 }
 
-/****************************
- * Get count of devices.
- *****************************/
-int libvlc_audio_output_device_count( libvlc_instance_t *p_instance,
-                                      const char *psz_audio_output )
+libvlc_audio_output_device_t *
+libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
+                                     const char *aout )
 {
-    char *psz_config_name;
-    if( !psz_audio_output )
-        return 0;
-    if( asprintf( &psz_config_name, "%s-audio-device", psz_audio_output ) == -1 )
-        return 0;
-
-    module_config_t *p_module_config = config_FindConfig(
-        VLC_OBJECT( p_instance->p_libvlc_int ), psz_config_name );
+    char varname[32];
+    if( (size_t)snprintf( varname, sizeof(varname), "%s-output-device", aout )
+                                                           >= sizeof(varname) )
+        return NULL;
 
-    if( p_module_config && p_module_config->pf_update_list )
+    libvlc_audio_output_device_t *list = NULL, **pp = &list;
+    char **values, **texts;
+    ssize_t count = config_GetPszChoices( VLC_OBJECT(p_instance->p_libvlc_int),
+                                          varname, &values, &texts );
+    for( ssize_t i = 0; i < count; i++ )
     {
-        vlc_value_t val;
-        val.psz_string = strdup( p_module_config->value.psz );
-
-        p_module_config->pf_update_list(
-            VLC_OBJECT( p_instance->p_libvlc_int ), psz_config_name, val, val, NULL );
-        free( val.psz_string );
-        free( psz_config_name );
+        libvlc_audio_output_device_t *item = malloc( sizeof(*item) );
+        if( unlikely(item == NULL) )
+            break;
 
-        return p_module_config->i_list;
+        *pp = item;
+        pp = &item->p_next;
+        item->psz_device = values[i];
+        item->psz_description = texts[i];
     }
 
-    free( psz_config_name );
-    return 0;
+    *pp = NULL;
+    free( texts );
+    free( values );
+    (void) p_instance;
+    return list;
 }
 
-/********************************
- * Get long name of device
- *********************************/
-char * libvlc_audio_output_device_longname( libvlc_instance_t *p_instance,
-                                            const char *psz_audio_output,
-                                            int i_device )
+void libvlc_audio_output_device_list_release( libvlc_audio_output_device_t *l )
 {
-    char *psz_config_name;
-    if( !psz_audio_output )
-        return NULL;
-    if( asprintf( &psz_config_name, "%s-audio-device", psz_audio_output ) == -1 )
-        return NULL;
-
-    module_config_t *p_module_config = config_FindConfig(
-        VLC_OBJECT( p_instance->p_libvlc_int ), psz_config_name );
-
-    if( p_module_config )
-    {
-        // refresh if there arent devices
-        if( p_module_config->i_list < 2 && p_module_config->pf_update_list )
-        {
-            vlc_value_t val;
-            val.psz_string = strdup( p_module_config->value.psz );
-
-            p_module_config->pf_update_list(
-                VLC_OBJECT( p_instance->p_libvlc_int ), psz_config_name, val, val, NULL );
-            free( val.psz_string );
-        }
-
-        if( i_device >= 0 && i_device < p_module_config->i_list )
+    while( l != NULL )
     {
-            free( psz_config_name );
+        libvlc_audio_output_device_t *next = l->p_next;
 
-            if( p_module_config->ppsz_list_text[i_device] )
-                return strdup( p_module_config->ppsz_list_text[i_device] );
-            else
-                return strdup( p_module_config->ppsz_list[i_device] );
-        }
+        free( l->psz_description );
+        free( l->psz_device );
+        free( l );
+        l = next;
     }
+}
 
-    free( psz_config_name );
-    return NULL;
+int libvlc_audio_output_device_count( libvlc_instance_t *p_instance,
+                                      const char *psz_audio_output )
+{
+    (void) p_instance; (void) psz_audio_output;
+    return 0;
 }
 
-/********************************
- * Get id name of device
- *********************************/
-char * libvlc_audio_output_device_id( libvlc_instance_t *p_instance,
+char *libvlc_audio_output_device_longname( libvlc_instance_t *p_instance,
                                            const char *psz_audio_output,
                                            int i_device )
 {
-    char *psz_config_name;
-    if( !psz_audio_output )
+    (void) p_instance; (void) psz_audio_output; (void) i_device;
     return NULL;
-    if( asprintf( &psz_config_name, "%s-audio-device", psz_audio_output ) == -1)
-        return NULL;
-
-    module_config_t *p_module_config = config_FindConfig(
-        VLC_OBJECT( p_instance->p_libvlc_int ), psz_config_name );
-
-    if( p_module_config )
-    {
-        // refresh if there arent devices
-        if( p_module_config->i_list < 2 && p_module_config->pf_update_list )
-        {
-            vlc_value_t val;
-            val.psz_string = strdup( p_module_config->value.psz );
-
-            p_module_config->pf_update_list(
-                VLC_OBJECT( p_instance->p_libvlc_int ), psz_config_name, val, val, NULL );
-            free( val.psz_string );
-        }
-
-        if( i_device >= 0 && i_device < p_module_config->i_list )
-        {
-            free( psz_config_name );
-            return strdup( p_module_config->ppsz_list[i_device] );
-        }
-    }
+}
 
-    free( psz_config_name );
+char *libvlc_audio_output_device_id( libvlc_instance_t *p_instance,
+                                     const char *psz_audio_output,
+                                     int i_device )
+{
+    (void) p_instance; (void) psz_audio_output; (void) i_device;
     return NULL;
 }
 

lib/libvlc.sym

@@ -5,6 +5,8 @@ libvlc_vprinterr
 libvlc_add_intf
 libvlc_audio_output_device_count
 libvlc_audio_output_device_id
+libvlc_audio_output_device_list_get
+libvlc_audio_output_device_list_release
 libvlc_audio_output_device_longname
 libvlc_audio_output_device_set
 libvlc_audio_output_get_device_type