LibVLC audio controls

Collaboration diagram for LibVLC audio controls:

Typedefs
typedef enum libvlc_audio_output_stereomode_t	libvlc_audio_output_stereomode_t
	Audio stereo modes.
typedef enum libvlc_audio_output_mixmode_t	libvlc_audio_output_mixmode_t
	Audio mix modes.
typedef enum libvlc_media_player_role	libvlc_media_player_role_t
	Media player roles.

Enumerations
enum	libvlc_audio_output_stereomode_t {   libvlc_AudioStereoMode_Unset = 0 , libvlc_AudioStereoMode_Stereo = 1 , libvlc_AudioStereoMode_RStereo = 2 , libvlc_AudioStereoMode_Left = 3 ,   libvlc_AudioStereoMode_Right = 4 , libvlc_AudioStereoMode_Dolbys = 5 , libvlc_AudioStereoMode_Mono = 7 }
	Audio stereo modes. More...
enum	libvlc_audio_output_mixmode_t {   libvlc_AudioMixMode_Unset = 0 , libvlc_AudioMixMode_Stereo = 1 , libvlc_AudioMixMode_Binaural = 2 , libvlc_AudioMixMode_4_0 = 3 ,   libvlc_AudioMixMode_5_1 = 4 , libvlc_AudioMixMode_7_1 = 5 }
	Audio mix modes. More...
enum	libvlc_media_player_role {   libvlc_role_None = 0 , libvlc_role_Music , libvlc_role_Video , libvlc_role_Communication ,   libvlc_role_Game , libvlc_role_Notification , libvlc_role_Animation , libvlc_role_Production ,   libvlc_role_Accessibility }
	Media player roles. More...

Functions
LIBVLC_API libvlc_audio_output_t *	libvlc_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_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 void	libvlc_audio_output_device_list_release (libvlc_audio_output_device_t *p_list)
	Frees a list of available audio output devices.
LIBVLC_API int	libvlc_audio_output_device_set (libvlc_media_player_t *mp, const char *device_id)
	Configures an explicit audio output device.
LIBVLC_API char *	libvlc_audio_output_device_get (libvlc_media_player_t *mp)
	Get the current audio output device identifier.
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 libvlc_audio_output_stereomode_t	libvlc_audio_get_stereomode (libvlc_media_player_t *p_mi)
	Get current audio stereo-mode.
LIBVLC_API int	libvlc_audio_set_stereomode (libvlc_media_player_t *p_mi, libvlc_audio_output_stereomode_t mode)
	Set current audio stereo-mode.
LIBVLC_API libvlc_audio_output_mixmode_t	libvlc_audio_get_mixmode (libvlc_media_player_t *p_mi)
	Get current audio mix-mode.
LIBVLC_API int	libvlc_audio_set_mixmode (libvlc_media_player_t *p_mi, libvlc_audio_output_mixmode_t mode)
	Set current audio mix-mode.
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_t *	libvlc_audio_equalizer_new (void)
	Create a new default equalizer, with all frequency values zeroed.
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.
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.
LIBVLC_API int	libvlc_media_player_get_role (libvlc_media_player_t *p_mi)
	Gets the media role.
LIBVLC_API int	libvlc_media_player_set_role (libvlc_media_player_t *p_mi, unsigned role)
	Sets the media role.
LIBVLC_API void	libvlc_media_player_record (libvlc_media_player_t *p_mi, bool enable, const char *dir_path)
	Start/stop recording.

Detailed Description

Typedef Documentation

libvlc_audio_output_mixmode_t

typedef enum libvlc_audio_output_mixmode_t libvlc_audio_output_mixmode_t

Audio mix modes.

libvlc_audio_output_stereomode_t

typedef enum libvlc_audio_output_stereomode_t libvlc_audio_output_stereomode_t

Audio stereo modes.

libvlc_media_player_role_t

typedef enum libvlc_media_player_role libvlc_media_player_role_t

Media player roles.

Version

LibVLC 3.0.0 and later.

See libvlc_media_player_set_role()

Enumeration Type Documentation

libvlc_audio_output_mixmode_t

enum libvlc_audio_output_mixmode_t

Audio mix modes.

Enumerator
libvlc_AudioMixMode_Unset
libvlc_AudioMixMode_Stereo
libvlc_AudioMixMode_Binaural
libvlc_AudioMixMode_4_0
libvlc_AudioMixMode_5_1
libvlc_AudioMixMode_7_1

libvlc_audio_output_stereomode_t

enum libvlc_audio_output_stereomode_t

Audio stereo modes.

Enumerator
libvlc_AudioStereoMode_Unset
libvlc_AudioStereoMode_Stereo
libvlc_AudioStereoMode_RStereo
libvlc_AudioStereoMode_Left
libvlc_AudioStereoMode_Right
libvlc_AudioStereoMode_Dolbys
libvlc_AudioStereoMode_Mono

libvlc_media_player_role

enum libvlc_media_player_role

Media player roles.

Version

LibVLC 3.0.0 and later.

See libvlc_media_player_set_role()

Enumerator
libvlc_role_None	Don't use a media player role.
libvlc_role_Music	Music (or radio) playback.
libvlc_role_Video	Video playback.
libvlc_role_Communication	Speech, real-time communication.
libvlc_role_Game	Video game.
libvlc_role_Notification	User interaction feedback.
libvlc_role_Animation	Embedded animation (e.g. in web page)
libvlc_role_Production	Audio editing/production.
libvlc_role_Accessibility	Accessibility.

Function Documentation

libvlc_audio_equalizer_get_amp_at_index()

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_equalizer	valid equalizer handle, must not be NULL
u_band	index, 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_audio_equalizer_get_band_count()

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_audio_equalizer_get_band_frequency()

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_index

index 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_audio_equalizer_get_preamp()

LIBVLC_API float libvlc_audio_equalizer_get_preamp

(

libvlc_equalizer_t *

p_equalizer

)

Get the current pre-amplification value from an equalizer.

Parameters

p_equalizer

valid equalizer handle, must not be NULL

Returns

preamp value (Hz)

Version

LibVLC 2.2.0 or later

libvlc_audio_equalizer_get_preset_count()

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_audio_equalizer_get_preset_name()

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_index

index 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_audio_equalizer_new()

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_audio_equalizer_new_from_preset()

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_index

index of the preset, counting from zero

Returns

opaque equalizer handle, or NULL on error (it must be released with libvlc_audio_equalizer_release())

Version

LibVLC 2.2.0 or later

libvlc_audio_equalizer_release()

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_equalizer

opaque equalizer handle, or NULL

Version

LibVLC 2.2.0 or later

libvlc_audio_equalizer_set_amp_at_index()

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_equalizer	valid equalizer handle, must not be NULL
f_amp	amplification value (-20.0 to 20.0 Hz)
u_band	index, counting from zero, of the frequency band to set

Returns

zero on success, -1 on error

Version

LibVLC 2.2.0 or later

libvlc_audio_equalizer_set_preamp()

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_equalizer	valid equalizer handle, must not be NULL
f_preamp	preamp value (-20.0 to 20.0 Hz)

Returns

zero on success, -1 on error

Version

LibVLC 2.2.0 or later

libvlc_audio_get_delay()

LIBVLC_API int64_t libvlc_audio_get_delay

(

libvlc_media_player_t *

p_mi

)

Get current audio delay.

Parameters

p_mi	media player

Returns

the audio delay (microseconds)

Version

LibVLC 1.1.1 or later

libvlc_audio_get_mixmode()

LIBVLC_API libvlc_audio_output_mixmode_t libvlc_audio_get_mixmode

(

libvlc_media_player_t *

p_mi

)

Get current audio mix-mode.

Parameters

p_mi	media player

Returns

the audio mix-mode,

See also

libvlc_audio_output_mixmode_t

Version

LibVLC 4.0.0 or later

libvlc_audio_get_mute()

LIBVLC_API int libvlc_audio_get_mute

(

libvlc_media_player_t *

p_mi

)

Get current mute status.

Parameters

p_mi	media player

Returns

the mute status (boolean) if defined, -1 if undefined/unapplicable

libvlc_audio_get_stereomode()

LIBVLC_API libvlc_audio_output_stereomode_t libvlc_audio_get_stereomode

(

libvlc_media_player_t *

p_mi

)

Get current audio stereo-mode.

Parameters

p_mi	media player

Returns

the audio stereo-mode,

See also

libvlc_audio_output_stereomode_t

Version

LibVLC 4.0.0 or later

libvlc_audio_get_volume()

LIBVLC_API int libvlc_audio_get_volume

(

libvlc_media_player_t *

p_mi

)

Get current software audio volume.

Parameters

p_mi	media player

Returns

the software volume in percents (0 = mute, 100 = nominal / 0dB)

libvlc_audio_output_device_enum()

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

mp	media player

Returns

A NULL-terminated linked list of potential audio output devices. It must be freed with libvlc_audio_output_device_list_release()

Version

LibVLC 2.2.0 or later.

libvlc_audio_output_device_get()

LIBVLC_API char * libvlc_audio_output_device_get

(

libvlc_media_player_t *

mp

)

Get the current audio output device identifier.

This complements libvlc_audio_output_device_set().

Warning

The initial value for the current audio output device identifier may not be set or may be some unknown value. A LibVLC application should compare this value against the known device identifiers (e.g. those that were previously retrieved by a call to libvlc_audio_output_device_enum) to find the current audio output device.

It is possible that the selected audio output device changes (an external change) without a call to libvlc_audio_output_device_set. That may make this method unsuitable to use if a LibVLC application is attempting to track dynamic audio device changes as they happen.

Parameters

mp	media player

Returns

the current audio output device identifier NULL if no device is selected or in case of error (the result must be released with free()).

Version

LibVLC 3.0.0 or later.

libvlc_audio_output_device_list_release()

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_list

list with audio outputs for release

Version

LibVLC 2.1.0 or later.

libvlc_audio_output_device_set()

LIBVLC_API int libvlc_audio_output_device_set	(	libvlc_media_player_t *	mp,
		const char *	device_id
	)

Configures an explicit audio output device.

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

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).

Version

This function originally expected three parameters. The middle parameter was removed from LibVLC 4.0 onward.

Parameters

mp	media player
device_id	device identifier string (see libvlc_audio_output_device_t::psz_device)

Returns

If the change of device was requested successfully, zero is returned (the actual change is asynchronous and not guaranteed to succeed). On error, a non-zero value is returned.

libvlc_audio_output_list_get()

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_instance

libvlc instance

Returns

list of available audio outputs. It must be freed with

See also

libvlc_audio_output_list_release

libvlc_audio_output_t . In case of error, NULL is returned.

libvlc_audio_output_list_release()

LIBVLC_API void libvlc_audio_output_list_release

(

libvlc_audio_output_t *

p_list

)

Frees the list of available audio output modules.

Parameters

p_list

list with audio outputs for release

libvlc_audio_output_set()

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_mi	media player
psz_name	name of audio output, use psz_name of

See also

libvlc_audio_output_t

Returns

0 if function succeeded, -1 on error

libvlc_audio_set_delay()

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_mi	media player
i_delay	the audio delay (microseconds)

Returns

0 on success, -1 on error

Version

LibVLC 1.1.1 or later

libvlc_audio_set_mixmode()

LIBVLC_API int libvlc_audio_set_mixmode	(	libvlc_media_player_t *	p_mi,
		libvlc_audio_output_mixmode_t	mode
	)

Set current audio mix-mode.

By default (libvlc_AudioMixMode_Unset), the audio output will keep its original channel configuration (play stereo as stereo, or 5.1 as 5.1). Yet, the OS and Audio API might refuse a channel configuration and asks VLC to adapt (Stereo played as 5.1 or vice-versa).

This function allows to force a channel configuration, it will only work if the OS and Audio API accept this configuration (otherwise, it won't have any effects). Here are some examples:

• Play multi-channels (5.1, 7.1...) as stereo (libvlc_AudioMixMode_Stereo)
• Play Stereo or 5.1 as 7.1 (libvlc_AudioMixMode_7_1)
• Play multi-channels as stereo with a binaural effect (libvlc_AudioMixMode_Binaural). It might be selected automatically if the OS and Audio API can detect if a headphone is plugged.

Parameters

p_mi	media player
mode	the audio mix-mode,

See also

libvlc_audio_output_mixmode_t

Returns

0 on success, -1 on error

Version

LibVLC 4.0.0 or later

libvlc_audio_set_mute()

LIBVLC_API void libvlc_audio_set_mute	(	libvlc_media_player_t *	p_mi,
		int	status
	)

Set mute status.

Parameters

p_mi	media player
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_audio_set_stereomode()

LIBVLC_API int libvlc_audio_set_stereomode	(	libvlc_media_player_t *	p_mi,
		libvlc_audio_output_stereomode_t	mode
	)

Set current audio stereo-mode.

Parameters

p_mi	media player
mode	the audio stereo-mode,

See also

libvlc_audio_output_stereomode_t

Returns

0 on success, -1 on error

Version

LibVLC 4.0.0 or later

libvlc_audio_set_volume()

LIBVLC_API int libvlc_audio_set_volume	(	libvlc_media_player_t *	p_mi,
		int	i_volume
	)

Set current software audio volume.

Parameters

p_mi	media player
i_volume	the volume in percents (0 = mute, 100 = 0dB)

Returns

0 if the volume was set, -1 if it was out of range

libvlc_audio_toggle_mute()

LIBVLC_API void libvlc_audio_toggle_mute

(

libvlc_media_player_t *

p_mi

)

Toggle mute status.

Parameters

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_media_player_get_role()

LIBVLC_API int libvlc_media_player_get_role

(

libvlc_media_player_t *

p_mi

)

Gets the media role.

Version

LibVLC 3.0.0 and later.

Parameters

p_mi	media player

Returns

the media player role (libvlc_media_player_role_t)

libvlc_media_player_record()

LIBVLC_API void libvlc_media_player_record	(	libvlc_media_player_t *	p_mi,
		bool	enable,
		const char *	dir_path
	)

Start/stop recording.

Note

The user should listen to the libvlc_MediaPlayerRecordChanged event, to monitor the recording state.

Version

LibVLC 4.0.0 and later.

Parameters

p_mi	media player
enable	true to start recording, false to stop
dir_path	path of the recording directory or NULL (use default path), has only an effect when first enabling recording.

libvlc_media_player_set_equalizer()

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_mi	opaque media player handle
p_equalizer	opaque 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

libvlc_media_player_set_role()

LIBVLC_API int libvlc_media_player_set_role	(	libvlc_media_player_t *	p_mi,
		unsigned	role
	)

Sets the media role.

Parameters

p_mi	media player
role	the media player role (libvlc_media_player_role_t)

Returns

0 on success, -1 on error