VLC  3.0.0-git
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Typedefs | Enumerations | Functions
LibVLC audio controls
LibVLC media player
Collaboration diagram for LibVLC audio controls:

Typedefs

typedef enum
libvlc_audio_output_device_types_t 
libvlc_audio_output_device_types_t
 Audio device types.
typedef enum
libvlc_audio_output_channel_t 
libvlc_audio_output_channel_t
 Audio channels.

Enumerations

enum  libvlc_audio_output_device_types_t {
  libvlc_AudioOutputDevice_Error = -1, libvlc_AudioOutputDevice_Mono = 1, libvlc_AudioOutputDevice_Stereo = 2, libvlc_AudioOutputDevice_2F2R = 4,
  libvlc_AudioOutputDevice_3F2R = 5, libvlc_AudioOutputDevice_5_1 = 6, libvlc_AudioOutputDevice_6_1 = 7, libvlc_AudioOutputDevice_7_1 = 8,
  libvlc_AudioOutputDevice_SPDIF = 10
}
 Audio device types. More...
enum  libvlc_audio_output_channel_t {
  libvlc_AudioChannel_Error = -1, libvlc_AudioChannel_Stereo = 1, libvlc_AudioChannel_RStereo = 2, libvlc_AudioChannel_Left = 3,
  libvlc_AudioChannel_Right = 4, libvlc_AudioChannel_Dolbys = 5
}
 Audio channels. More...

Functions

LIBVLC_API libvlc_audio_output_tlibvlc_audio_output_list_get (libvlc_instance_t *p_instance)
 Gets the list of available audio output modules.
LIBVLC_API void libvlc_audio_output_list_release (libvlc_audio_output_t *p_list)
 Frees the list of available audio output modules.
LIBVLC_API int libvlc_audio_output_set (libvlc_media_player_t *p_mi, const char *psz_name)
 Selects an audio output module.
LIBVLC_DEPRECATED LIBVLC_API int libvlc_audio_output_device_count (libvlc_instance_t *, const char *)
 Backward compatibility stub.
LIBVLC_DEPRECATED LIBVLC_API char * libvlc_audio_output_device_longname (libvlc_instance_t *, const char *, int)
 Backward compatibility stub.
LIBVLC_DEPRECATED LIBVLC_API char * libvlc_audio_output_device_id (libvlc_instance_t *, const char *, int)
 Backward compatibility stub.
LIBVLC_API
libvlc_audio_output_device_t
libvlc_audio_output_device_enum (libvlc_media_player_t *mp)
 Gets a list of potential audio output devices,.
LIBVLC_API
libvlc_audio_output_device_t
libvlc_audio_output_device_list_get (libvlc_instance_t *p_instance, const char *aout)
 Gets a list of audio output devices for a given audio output module,.
LIBVLC_API void libvlc_audio_output_device_list_release (libvlc_audio_output_device_t *p_list)
 Frees a list of available audio output devices.
LIBVLC_API void libvlc_audio_output_device_set (libvlc_media_player_t *mp, const char *module, const char *device_id)
 Configures an explicit audio output device.
LIBVLC_DEPRECATED LIBVLC_API int libvlc_audio_output_get_device_type (libvlc_media_player_t *p_mi)
 Stub for backward compatibility.
LIBVLC_DEPRECATED LIBVLC_API void libvlc_audio_output_set_device_type (libvlc_media_player_t *, int)
 Stub for backward compatibility.
LIBVLC_API void libvlc_audio_toggle_mute (libvlc_media_player_t *p_mi)
 Toggle mute status.
LIBVLC_API int libvlc_audio_get_mute (libvlc_media_player_t *p_mi)
 Get current mute status.
LIBVLC_API void libvlc_audio_set_mute (libvlc_media_player_t *p_mi, int status)
 Set mute status.
LIBVLC_API int libvlc_audio_get_volume (libvlc_media_player_t *p_mi)
 Get current software audio volume.
LIBVLC_API int libvlc_audio_set_volume (libvlc_media_player_t *p_mi, int i_volume)
 Set current software audio volume.
LIBVLC_API int libvlc_audio_get_track_count (libvlc_media_player_t *p_mi)
 Get number of available audio tracks.
LIBVLC_API
libvlc_track_description_t
libvlc_audio_get_track_description (libvlc_media_player_t *p_mi)
 Get the description of available audio tracks.
LIBVLC_API int libvlc_audio_get_track (libvlc_media_player_t *p_mi)
 Get current audio track.
LIBVLC_API int libvlc_audio_set_track (libvlc_media_player_t *p_mi, int i_track)
 Set current audio track.
LIBVLC_API int libvlc_audio_get_channel (libvlc_media_player_t *p_mi)
 Get current audio channel.
LIBVLC_API int libvlc_audio_set_channel (libvlc_media_player_t *p_mi, int channel)
 Set current audio channel.
LIBVLC_API int64_t libvlc_audio_get_delay (libvlc_media_player_t *p_mi)
 Get current audio delay.
LIBVLC_API int libvlc_audio_set_delay (libvlc_media_player_t *p_mi, int64_t i_delay)
 Set current audio delay.
LIBVLC_API unsigned libvlc_audio_equalizer_get_preset_count (void)
 Get the number of equalizer presets.
LIBVLC_API const char * libvlc_audio_equalizer_get_preset_name (unsigned u_index)
 Get the name of a particular equalizer preset.
LIBVLC_API unsigned libvlc_audio_equalizer_get_band_count (void)
 Get the number of distinct frequency bands for an equalizer.
LIBVLC_API float libvlc_audio_equalizer_get_band_frequency (unsigned u_index)
 Get a particular equalizer band frequency.
LIBVLC_API libvlc_equalizer_tlibvlc_audio_equalizer_new (void)
 Create a new default equalizer, with all frequency values zeroed.
LIBVLC_API libvlc_equalizer_tlibvlc_audio_equalizer_new_from_preset (unsigned u_index)
 Create a new equalizer, with initial frequency values copied from an existing preset.
LIBVLC_API void libvlc_audio_equalizer_release (libvlc_equalizer_t *p_equalizer)
 Release a previously created equalizer instance.
LIBVLC_API int libvlc_audio_equalizer_set_preamp (libvlc_equalizer_t *p_equalizer, float f_preamp)
 Set a new pre-amplification value for an equalizer.
LIBVLC_API float libvlc_audio_equalizer_get_preamp (libvlc_equalizer_t *p_equalizer)
 Get the current pre-amplification value from an equalizer.
LIBVLC_API int libvlc_audio_equalizer_set_amp_at_index (libvlc_equalizer_t *p_equalizer, float f_amp, unsigned u_band)
 Set a new amplification value for a particular equalizer frequency band.
LIBVLC_API float libvlc_audio_equalizer_get_amp_at_index (libvlc_equalizer_t *p_equalizer, unsigned u_band)
 Get the amplification value for a particular equalizer frequency band.
LIBVLC_API int libvlc_media_player_set_equalizer (libvlc_media_player_t *p_mi, libvlc_equalizer_t *p_equalizer)
 Apply new equalizer settings to a media player.

Detailed Description

Typedef Documentation

Audio channels.

Audio device types.

Enumeration Type Documentation

Audio channels.

Enumerator:
libvlc_AudioChannel_Error 
libvlc_AudioChannel_Stereo 
libvlc_AudioChannel_RStereo 
libvlc_AudioChannel_Left 
libvlc_AudioChannel_Right 
libvlc_AudioChannel_Dolbys 

Audio device types.

Enumerator:
libvlc_AudioOutputDevice_Error 
libvlc_AudioOutputDevice_Mono 
libvlc_AudioOutputDevice_Stereo 
libvlc_AudioOutputDevice_2F2R 
libvlc_AudioOutputDevice_3F2R 
libvlc_AudioOutputDevice_5_1 
libvlc_AudioOutputDevice_6_1 
libvlc_AudioOutputDevice_7_1 
libvlc_AudioOutputDevice_SPDIF 

Function Documentation

LIBVLC_API float libvlc_audio_equalizer_get_amp_at_index ( libvlc_equalizer_t p_equalizer,
unsigned  u_band 
)

Get the amplification value for a particular equalizer frequency band.

Parameters
p_equalizervalid equalizer handle, must not be NULL
u_bandindex, counting from zero, of the frequency band to get
Returns
amplification value (Hz); NaN if there is no such frequency band
Version
LibVLC 2.2.0 or later
LIBVLC_API unsigned libvlc_audio_equalizer_get_band_count ( void  )

Get the number of distinct frequency bands for an equalizer.

Returns
number of frequency bands
Version
LibVLC 2.2.0 or later
LIBVLC_API float libvlc_audio_equalizer_get_band_frequency ( unsigned  u_index)

Get a particular equalizer band frequency.

This value can be used, for example, to create a label for an equalizer band control in a user interface.

Parameters
u_indexindex of the band, counting from zero
Returns
equalizer band frequency (Hz), or -1 if there is no such band
Version
LibVLC 2.2.0 or later
LIBVLC_API float libvlc_audio_equalizer_get_preamp ( libvlc_equalizer_t p_equalizer)

Get the current pre-amplification value from an equalizer.

Parameters
p_equalizervalid equalizer handle, must not be NULL
Returns
preamp value (Hz)
Version
LibVLC 2.2.0 or later
LIBVLC_API unsigned libvlc_audio_equalizer_get_preset_count ( void  )

Get the number of equalizer presets.

Returns
number of presets
Version
LibVLC 2.2.0 or later
LIBVLC_API const char* libvlc_audio_equalizer_get_preset_name ( unsigned  u_index)

Get the name of a particular equalizer preset.

This name can be used, for example, to prepare a preset label or menu in a user interface.

Parameters
u_indexindex of the preset, counting from zero
Returns
preset name, or NULL if there is no such preset
Version
LibVLC 2.2.0 or later
LIBVLC_API libvlc_equalizer_t* libvlc_audio_equalizer_new ( void  )

Create a new default equalizer, with all frequency values zeroed.

The new equalizer can subsequently be applied to a media player by invoking libvlc_media_player_set_equalizer().

The returned handle should be freed via libvlc_audio_equalizer_release() when it is no longer needed.

Returns
opaque equalizer handle, or NULL on error
Version
LibVLC 2.2.0 or later
LIBVLC_API libvlc_equalizer_t* libvlc_audio_equalizer_new_from_preset ( unsigned  u_index)

Create a new equalizer, with initial frequency values copied from an existing preset.

The new equalizer can subsequently be applied to a media player by invoking libvlc_media_player_set_equalizer().

The returned handle should be freed via libvlc_audio_equalizer_release() when it is no longer needed.

Parameters
u_indexindex of the preset, counting from zero
Returns
opaque equalizer handle, or NULL on error
Version
LibVLC 2.2.0 or later
LIBVLC_API void libvlc_audio_equalizer_release ( libvlc_equalizer_t p_equalizer)

Release a previously created equalizer instance.

The equalizer was previously created by using libvlc_audio_equalizer_new() or libvlc_audio_equalizer_new_from_preset().

It is safe to invoke this method with a NULL p_equalizer parameter for no effect.

Parameters
p_equalizeropaque equalizer handle, or NULL
Version
LibVLC 2.2.0 or later
LIBVLC_API int libvlc_audio_equalizer_set_amp_at_index ( libvlc_equalizer_t p_equalizer,
float  f_amp,
unsigned  u_band 
)

Set a new amplification value for a particular equalizer frequency band.

The new equalizer settings are subsequently applied to a media player by invoking libvlc_media_player_set_equalizer().

The supplied amplification value will be clamped to the -20.0 to +20.0 range.

Parameters
p_equalizervalid equalizer handle, must not be NULL
f_ampamplification value (-20.0 to 20.0 Hz)
u_bandindex, counting from zero, of the frequency band to set
Returns
zero on success, -1 on error
Version
LibVLC 2.2.0 or later
LIBVLC_API int libvlc_audio_equalizer_set_preamp ( libvlc_equalizer_t p_equalizer,
float  f_preamp 
)

Set a new pre-amplification value for an equalizer.

The new equalizer settings are subsequently applied to a media player by invoking libvlc_media_player_set_equalizer().

The supplied amplification value will be clamped to the -20.0 to +20.0 range.

Parameters
p_equalizervalid equalizer handle, must not be NULL
f_preamppreamp value (-20.0 to 20.0 Hz)
Returns
zero on success, -1 on error
Version
LibVLC 2.2.0 or later
LIBVLC_API int libvlc_audio_get_channel ( libvlc_media_player_t p_mi)

Get current audio channel.

Parameters
p_mimedia player
Returns
the audio channel
See Also
libvlc_audio_output_channel_t
LIBVLC_API int64_t libvlc_audio_get_delay ( libvlc_media_player_t p_mi)

Get current audio delay.

Parameters
p_mimedia player
Returns
the audio delay (microseconds)
Version
LibVLC 1.1.1 or later
LIBVLC_API int libvlc_audio_get_mute ( libvlc_media_player_t p_mi)

Get current mute status.

Parameters
p_mimedia player
Returns
the mute status (boolean) if defined, -1 if undefined/unapplicable
LIBVLC_API int libvlc_audio_get_track ( libvlc_media_player_t p_mi)

Get current audio track.

Parameters
p_mimedia player
Returns
the audio track ID or -1 if no active input.
LIBVLC_API int libvlc_audio_get_track_count ( libvlc_media_player_t p_mi)

Get number of available audio tracks.

Parameters
p_mimedia player
Returns
the number of available audio tracks (int), or -1 if unavailable
LIBVLC_API libvlc_track_description_t* libvlc_audio_get_track_description ( libvlc_media_player_t p_mi)

Get the description of available audio tracks.

Parameters
p_mimedia player
Returns
list with description of available audio tracks, or NULL
LIBVLC_API int libvlc_audio_get_volume ( libvlc_media_player_t p_mi)

Get current software audio volume.

Parameters
p_mimedia player
Returns
the software volume in percents (0 = mute, 100 = nominal / 0dB)
LIBVLC_DEPRECATED LIBVLC_API 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.

Returns
always 0.
LIBVLC_API libvlc_audio_output_device_t* libvlc_audio_output_device_enum ( libvlc_media_player_t mp)

Gets a list of potential audio output devices,.

See Also
libvlc_audio_output_device_set().
Note
Not all audio outputs support enumerating devices. The audio output may be functional even if the list is empty (NULL).
The list may 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.
Parameters
mpmedia player
Returns
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.2.0 or later.
LIBVLC_DEPRECATED LIBVLC_API char* libvlc_audio_output_device_id ( libvlc_instance_t ,
const char *  ,
int   
)

Backward compatibility stub.

Do not use in new code. Use libvlc_audio_output_device_list_get() instead.

Returns
always NULL.
LIBVLC_API libvlc_audio_output_device_t* libvlc_audio_output_device_list_get ( libvlc_instance_t p_instance,
const char *  aout 
)

Gets a list of audio output devices for a given audio output module,.

See Also
libvlc_audio_output_device_set().
Note
Not all audio outputs support this. In particular, an empty (NULL) list of devices does not imply that the specified audio output does not work.
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.
Parameters
p_instancelibvlc instance
psz_aoutaudio output name (as returned by libvlc_audio_output_list_get())
Returns
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 void libvlc_audio_output_device_list_release ( libvlc_audio_output_device_t p_list)

Frees a list of available audio output devices.

Parameters
p_listlist with audio outputs for release
Version
LibVLC 2.1.0 or later.
LIBVLC_DEPRECATED LIBVLC_API 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.

Returns
always NULL.
LIBVLC_API void libvlc_audio_output_device_set ( libvlc_media_player_t mp,
const char *  module,
const char *  device_id 
)

Configures an explicit audio output device.

If the module paramater is NULL, audio output will be moved to the device specified by the device identifier string immediately. This is the recommended usage.

A list of adequate potential device strings can be obtained with libvlc_audio_output_device_enum().

However passing NULL is supported in LibVLC version 2.2.0 and later only; in earlier versions, this function would have no effects when the module parameter was NULL.

If the module parameter is not NULL, the device parameter of the corresponding audio output, if it exists, will be set to the specified string. Note that some audio output modules do not have such a parameter (notably MMDevice and PulseAudio).

A list of adequate potential device strings 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.

Some audio output modules require further parameters (e.g. a channels map in the case of ALSA).

Parameters
mpmedia player
moduleIf NULL, current audio output module. if non-NULL, name of audio output module (
See Also
libvlc_audio_output_t)
Parameters
device_iddevice identifier string
Returns
Nothing. Errors are ignored (this is a design bug).
LIBVLC_DEPRECATED LIBVLC_API int libvlc_audio_output_get_device_type ( libvlc_media_player_t p_mi)

Stub for backward compatibility.

Returns
always -1.
LIBVLC_API libvlc_audio_output_t* libvlc_audio_output_list_get ( libvlc_instance_t p_instance)

Gets the list of available audio output modules.

Parameters
p_instancelibvlc instance
Returns
list of available audio outputs. It must be freed it with
See Also
libvlc_audio_output_list_release
libvlc_audio_output_t . In case of error, NULL is returned.
LIBVLC_API void libvlc_audio_output_list_release ( libvlc_audio_output_t p_list)

Frees the list of available audio output modules.

Parameters
p_listlist with audio outputs for release
LIBVLC_API int libvlc_audio_output_set ( libvlc_media_player_t p_mi,
const char *  psz_name 
)

Selects an audio output module.

Note
Any change will take be effect only after playback is stopped and restarted. Audio output cannot be changed while playing.
Parameters
p_mimedia player
psz_namename of audio output, use psz_name of
See Also
libvlc_audio_output_t
Returns
0 if function succeded, -1 on error
LIBVLC_DEPRECATED LIBVLC_API void libvlc_audio_output_set_device_type ( libvlc_media_player_t ,
int   
)

Stub for backward compatibility.

LIBVLC_API int libvlc_audio_set_channel ( libvlc_media_player_t p_mi,
int  channel 
)

Set current audio channel.

Parameters
p_mimedia player
channelthe audio channel,
See Also
libvlc_audio_output_channel_t
Returns
0 on success, -1 on error
LIBVLC_API int libvlc_audio_set_delay ( libvlc_media_player_t p_mi,
int64_t  i_delay 
)

Set current audio delay.

The audio delay will be reset to zero each time the media changes.

Parameters
p_mimedia player
i_delaythe audio delay (microseconds)
Returns
0 on success, -1 on error
Version
LibVLC 1.1.1 or later
LIBVLC_API void libvlc_audio_set_mute ( libvlc_media_player_t p_mi,
int  status 
)

Set mute status.

Parameters
p_mimedia player
statusIf 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 int libvlc_audio_set_track ( libvlc_media_player_t p_mi,
int  i_track 
)

Set current audio track.

Parameters
p_mimedia player
i_trackthe track ID (i_id field from track description)
Returns
0 on success, -1 on error
LIBVLC_API int libvlc_audio_set_volume ( libvlc_media_player_t p_mi,
int  i_volume 
)

Set current software audio volume.

Parameters
p_mimedia player
i_volumethe volume in percents (0 = mute, 100 = 0dB)
Returns
0 if the volume was set, -1 if it was out of range
LIBVLC_API void libvlc_audio_toggle_mute ( libvlc_media_player_t p_mi)

Toggle mute status.

Parameters
p_mimedia 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 int libvlc_media_player_set_equalizer ( libvlc_media_player_t p_mi,
libvlc_equalizer_t p_equalizer 
)

Apply new equalizer settings to a media player.

The equalizer is first created by invoking libvlc_audio_equalizer_new() or libvlc_audio_equalizer_new_from_preset().

It is possible to apply new equalizer settings to a media player whether the media player is currently playing media or not.

Invoking this method will immediately apply the new equalizer settings to the audio output of the currently playing media if there is any.

If there is no currently playing media, the new equalizer settings will be applied later if and when new media is played.

Equalizer settings will automatically be applied to subsequently played media.

To disable the equalizer for a media player invoke this method passing NULL for the p_equalizer parameter.

The media player does not keep a reference to the supplied equalizer so it is safe for an application to release the equalizer reference any time after this method returns.

Parameters
p_miopaque media player handle
p_equalizeropaque equalizer handle, or NULL to disable the equalizer for this media player
Returns
zero on success, -1 on error
Version
LibVLC 2.2.0 or later