} 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
*/
/**
- * 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
* 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,
* \return 0 if function succeded, -1 on error
*/
LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
- const char *psz_name );
+ 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,
- const char *psz_device_id );
+ const char *psz_audio_output,
+ const char *psz_device_id );
/**
* Get current audio device type. Device type describes something like
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 )
+ while( l != NULL )
{
- // 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 );
+ 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;
}
-/********************************
- * Get id name of device
- *********************************/
-char * libvlc_audio_output_device_id( libvlc_instance_t *p_instance,
- const char *psz_audio_output,
- int i_device )
+int libvlc_audio_output_device_count( libvlc_instance_t *p_instance,
+ const char *psz_audio_output )
{
- 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 );
- }
+ (void) p_instance; (void) psz_audio_output;
+ return 0;
+}
- if( i_device >= 0 && i_device < p_module_config->i_list )
- {
- free( psz_config_name );
- return strdup( p_module_config->ppsz_list[i_device] );
- }
- }
+char *libvlc_audio_output_device_longname( 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;
+}
- 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;
}
projects / vlc / commitdiff