Player callbacks. More...

#include <vlc_player.h>

Data Fields
void(*	on_current_media_changed )(vlc_player_t player, input_item_t new_media, void *data)
	Called when the current media has changed.

void(*	on_state_changed )(vlc_player_t player, enum vlc_player_state new_state, void data)
	Called when the player state has changed.

void(*	on_error_changed )(vlc_player_t player, enum vlc_player_error error, void data)
	Called when a media triggered an error.

void(*	on_buffering_changed )(vlc_player_t player, float new_buffering, void data)
	Called when the player buffering (or cache) has changed.

void(*	on_rate_changed )(vlc_player_t player, float new_rate, void data)
	Called when the player rate has changed.

void(*	on_capabilities_changed )(vlc_player_t player, int old_caps, int new_caps, void data)
	Called when the media capabilities has changed.

void(*	on_position_changed )(vlc_player_t player, vlc_tick_t new_time, double new_pos, void data)
	Called when the player position has changed.

void(*	on_length_changed )(vlc_player_t player, vlc_tick_t new_length, void data)
	Called when the media length has changed.

void(*	on_track_list_changed )(vlc_player_t player, enum vlc_player_list_action action, const struct vlc_player_track track, void *data)
	Called when a track is added, removed, or updated.

void(*	on_track_selection_changed )(vlc_player_t player, vlc_es_id_t unselected_id, vlc_es_id_t selected_id, void data)
	Called when a new track is selected and/or unselected.

void(*	on_track_delay_changed )(vlc_player_t player, vlc_es_id_t es_id, vlc_tick_t delay, void *data)
	Called when a track delay has changed.

void(*	on_program_list_changed )(vlc_player_t player, enum vlc_player_list_action action, const struct vlc_player_program prgm, void *data)
	Called when a new program is added, removed or updated.

void(*	on_program_selection_changed )(vlc_player_t player, int unselected_id, int selected_id, void data)
	Called when a new program is selected and/or unselected.

void(*	on_titles_changed )(vlc_player_t player, vlc_player_title_list titles, void *data)
	Called when the media titles has changed.

void(*	on_title_selection_changed )(vlc_player_t player, const struct vlc_player_title new_title, size_t new_idx, void *data)
	Called when a new title is selected.

void(*	on_chapter_selection_changed )(vlc_player_t player, const struct vlc_player_title title, size_t title_idx, const struct vlc_player_chapter new_chapter, size_t new_chapter_idx, void data)
	Called when a new chapter is selected.

void(*	on_teletext_menu_changed )(vlc_player_t player, bool has_teletext_menu, void data)
	Called when the media has a teletext menu.

void(*	on_teletext_enabled_changed )(vlc_player_t player, bool enabled, void data)
	Called when teletext is enabled or disabled.

void(*	on_teletext_page_changed )(vlc_player_t player, unsigned new_page, void data)
	Called when the teletext page has changed.

void(*	on_teletext_transparency_changed )(vlc_player_t player, bool enabled, void data)
	Called when the teletext transparency has changed.

void(*	on_category_delay_changed )(vlc_player_t player, enum es_format_category_e cat, vlc_tick_t new_delay, void data)
	Called when the player category delay has changed for the current media.

void(*	on_associated_subs_fps_changed )(vlc_player_t player, float subs_fps, void data)
	Called when associated subtitle has changed.

void(*	on_renderer_changed )(vlc_player_t player, vlc_renderer_item_t new_item, void *data)
	Called when a new renderer item is set.

void(*	on_recording_changed )(vlc_player_t player, bool recording, void data)
	Called when the player recording state has changed.

void(*	on_signal_changed )(vlc_player_t player, float quality, float strength, void data)
	Called when the media signal has changed.

void(*	on_statistics_changed )(vlc_player_t player, const struct input_stats_t stats, void *data)
	Called when the player has new statisics.

void(*	on_atobloop_changed )(vlc_player_t player, enum vlc_player_abloop new_state, vlc_tick_t time, double pos, void data)
	Called when the A to B loop has changed.

void(*	on_media_meta_changed )(vlc_player_t player, input_item_t media, void *data)
	Called when the media meta and/or info has changed.

void(*	on_media_epg_changed )(vlc_player_t player, input_item_t media, void *data)
	Called when media epg has changed.

void(*	on_media_subitems_changed )(vlc_player_t player, input_item_t media, input_item_node_t new_subitems, void data)
	Called when the media has new subitems.

void(*	on_media_attachments_added )(vlc_player_t player, input_item_t media, input_attachment_t const array, size_t count, void *data)
	Called when new attachments are added to the media.

void(*	on_vout_changed )(vlc_player_t player, enum vlc_player_vout_action action, vout_thread_t vout, enum vlc_vout_order order, vlc_es_id_t es_id, void data)
	Called when a vout is started or stopped.

void(*	on_cork_changed )(vlc_player_t player, unsigned cork_count, void data)
	Called when the player is corked.

void(*	on_playback_restore_queried )(vlc_player_t player, void data)
	Called to query the user about restoring the previous playback position.

void(*	on_stopping_current_media )(vlc_player_t player, input_item_t current_media, void *data)
	Called when the player will stop the current media.

Detailed Description

Player callbacks.

Can be registered with vlc_player_AddListener().

All callbacks are called with the player locked (cf. vlc_player_Lock()) and from any threads (and even synchronously from a vlc_player function in some cases). It is safe to call any vlc_player functions from these callbacks except vlc_player_Delete().

Warning: To avoid deadlocks, users should never call vlc_player functions with an external mutex locked and lock this same mutex from a player callback.

Field Documentation

◆ on_associated_subs_fps_changed

void(* vlc_player_cbs::on_associated_subs_fps_changed) (vlc_player_t *player, float subs_fps, void *data)

Called when associated subtitle has changed.

See also: vlc_player_SetAssociatedSubsFPS()

Parameters

player	locked player instance
sub_fps	subtitle fps
data	opaque pointer set by vlc_player_AddListener()

◆ on_atobloop_changed

void(* vlc_player_cbs::on_atobloop_changed) (vlc_player_t *player, enum vlc_player_abloop new_state, vlc_tick_t time, double pos, void *data)

Called when the A to B loop has changed.

See also: vlc_player_SetAtoBLoop()

Parameters

player	locked player instance
state	A, when only A is set, B when both A and B are set, None by default
time	valid time or VLC_TICK_INVALID of the current state
pos	valid pos of the current state
data	opaque pointer set by vlc_player_AddListener()

◆ on_buffering_changed

void(* vlc_player_cbs::on_buffering_changed) (vlc_player_t *player, float new_buffering, void *data)

Called when the player buffering (or cache) has changed.

This event is always called with the 0 and 1 values before a playback (in case of success). Values in between depends on the media type.

Parameters

player	locked player instance
new_buffering	buffering in the range [0:1]
data	opaque pointer set by vlc_player_AddListener()

◆ on_capabilities_changed

void(* vlc_player_cbs::on_capabilities_changed) (vlc_player_t *player, int old_caps, int new_caps, void *data)

Called when the media capabilities has changed.

Always called when the media is opening or stopping. Can be called during playback.

Parameters

player	locked player instance
old_caps	old player capabilities
new_caps	new player capabilities
data	opaque pointer set by vlc_player_AddListener()

◆ on_category_delay_changed

void(* vlc_player_cbs::on_category_delay_changed) (vlc_player_t *player, enum es_format_category_e cat, vlc_tick_t new_delay, void *data)

Called when the player category delay has changed for the current media.

See also: vlc_player_SetCategoryDelay()

Parameters

player	locked player instance
cat	AUDIO_ES or SPU_ES
new_delay	audio delay
data	opaque pointer set by vlc_player_AddListener()

◆ on_chapter_selection_changed

void(* vlc_player_cbs::on_chapter_selection_changed) (vlc_player_t *player, const struct vlc_player_title *title, size_t title_idx, const struct vlc_player_chapter *new_chapter, size_t new_chapter_idx, void *data)

Called when a new chapter is selected.

There are no events when a chapter is unselected. Chapters are automatically unselected when the title list changes. Titles, chapters and indexes are always valid inside the vlc_player_title_list sent by vlc_player_cbs.on_titles_changed.

Parameters

player	locked player instance
title	selected title
title_idx	selected title index
chapter	new selected chapter
chapter_idx	new selected chapter index
data	opaque pointer set by vlc_player_AddListener()

◆ on_cork_changed

void(* vlc_player_cbs::on_cork_changed) (vlc_player_t *player, unsigned cork_count, void *data)

Called when the player is corked.

The player can be corked when the audio output loose focus or when a renderer was paused from the outside.

Note: called only if pause on cork was not set to true (by vlc_player_SetPauseOnCork()); a cork_count higher than 0 means the player is corked. In that case, the user should pause the player and release all external resource needed by the player. A value higher than 1 mean that the player was corked more than one time (for different reasons). A value of 0 means the player is no longer corked. In that case, the user could resume the player.

Parameters

player	locked player instance
cork_count	0 for uncorked, > 0 for corked
data	opaque pointer set by vlc_player_AddListener()

◆ on_current_media_changed

void(* vlc_player_cbs::on_current_media_changed) (vlc_player_t *player, input_item_t *new_media, void *data)

Called when the current media has changed.

Note: This can be called from the PLAYING state (when the player plays the next media internally) or from the STOPPED state (from vlc_player_SetCurrentMedia() or from an internal transition).

The user could set the next media via vlc_player_SetNextMedia() from the current callback or anytime before the current media is stopped.

See also: vlc_player_SetCurrentMedia()

Parameters

player	locked player instance
new_media	new media currently played or NULL (when there is no more media to play)
data	opaque pointer set by vlc_player_AddListener()

◆ on_error_changed

void(* vlc_player_cbs::on_error_changed) (vlc_player_t *player, enum vlc_player_error error, void *data)

Called when a media triggered an error.

Can be called from any states. When it happens the player will stop itself. It is safe to play an other media or event restart the player (This will reset the error state).

Parameters

player	locked player instance
error	player error
data	opaque pointer set by vlc_player_AddListener()

◆ on_length_changed

void(* vlc_player_cbs::on_length_changed) (vlc_player_t *player, vlc_tick_t new_length, void *data)

Called when the media length has changed.

May be called when the media is opening or during playback.

Note: A started and playing media doesn't have necessarily a valid length.

Parameters

player	locked player instance
new_length	a valid time or VLC_TICK_INVALID
data	opaque pointer set by vlc_player_AddListener()

◆ on_media_attachments_added

void(* vlc_player_cbs::on_media_attachments_added) (vlc_player_t *player, input_item_t *media, input_attachment_t *const *array, size_t count, void *data)

Called when new attachments are added to the media.

Note: It can be called several times for one parse request. The array contains only new elements after a second call.

Parameters

player	locked player instance
media	current media
array	valid array containing new elements, should only be used within the callback. One and all elements can be held and stored on a new variable or new array.
count	number of elements in the array
data	opaque pointer set by vlc_player_AddListener()

◆ on_media_epg_changed

void(* vlc_player_cbs::on_media_epg_changed) (vlc_player_t *player, input_item_t *media, void *data)

Called when media epg has changed.

Parameters

player	locked player instance
media	current media
data	opaque pointer set by vlc_player_AddListener()

◆ on_media_meta_changed

void(* vlc_player_cbs::on_media_meta_changed) (vlc_player_t *player, input_item_t *media, void *data)

Called when the media meta and/or info has changed.

Parameters

player	locked player instance
media	current media
data	opaque pointer set by vlc_player_AddListener()

◆ on_media_subitems_changed

void(* vlc_player_cbs::on_media_subitems_changed) (vlc_player_t *player, input_item_t *media, input_item_node_t *new_subitems, void *data)

Called when the media has new subitems.

Parameters

player	locked player instance
media	current media
new_subitems	node representing all media subitems
data	opaque pointer set by vlc_player_AddListener()

◆ on_playback_restore_queried

void(* vlc_player_cbs::on_playback_restore_queried) (vlc_player_t *player, void *data)

Called to query the user about restoring the previous playback position.

If this callback isn't provided, the user won't be asked to restore the previous playback position, effectively causing VLC_PLAYER_RESTORE_PLAYBACK_POS_ASK to be handled as VLC_PLAYER_RESTORE_PLAYBACK_POS_NEVER

The implementation can react to this callback by calling vlc_player_RestorePlaybackPos(), or by discarding the event.

Parameters

player	locked player instance
data	opaque pointer set by vlc_player_AddListener()

◆ on_position_changed

void(* vlc_player_cbs::on_position_changed) (vlc_player_t *player, vlc_tick_t new_time, double new_pos, void *data)

Called when the player position has changed.

Note: A started and playing media doesn't have necessarily a valid time.

Parameters

player	locked player instance
new_time	a valid time or VLC_TICK_INVALID
new_pos	a valid position
data	opaque pointer set by vlc_player_AddListener()

◆ on_program_list_changed

void(* vlc_player_cbs::on_program_list_changed) (vlc_player_t *player, enum vlc_player_list_action action, const struct vlc_player_program *prgm, void *data)

Called when a new program is added, removed or updated.

Note: The program is only valid from this callback context. Users should duplicate this program via vlc_player_program_Dup() if they want to use it from an other context.

Parameters

player	locked player instance
action	added, removed or updated
prgm	valid program
data	opaque pointer set by vlc_player_AddListener()

◆ on_program_selection_changed

void(* vlc_player_cbs::on_program_selection_changed) (vlc_player_t *player, int unselected_id, int selected_id, void *data)

Called when a new program is selected and/or unselected.

Note: This event can be called with both unselected_id and selected_id valid. This mean that a new program is replacing the old one.

Parameters

player	locked player instance
unselected_id	valid program id or -1 (when nothing is unselected)
selected_id	valid program id or -1 (when nothing is selected)
data	opaque pointer set by vlc_player_AddListener()

◆ on_rate_changed

void(* vlc_player_cbs::on_rate_changed) (vlc_player_t *player, float new_rate, void *data)

Called when the player rate has changed.

Triggered by vlc_player_ChangeRate(), not sent when the media starts with the default rate (1.f)

Parameters

player	locked player instance
new_rate	player
data	opaque pointer set by vlc_player_AddListener()

◆ on_recording_changed

void(* vlc_player_cbs::on_recording_changed) (vlc_player_t *player, bool recording, void *data)

Called when the player recording state has changed.

See also: vlc_player_SetRecordingEnabled()

Parameters

player	locked player instance
recording	true if recording is enabled
data	opaque pointer set by vlc_player_AddListener()

◆ on_renderer_changed

void(* vlc_player_cbs::on_renderer_changed) (vlc_player_t *player, vlc_renderer_item_t *new_item, void *data)

Called when a new renderer item is set.

See also: vlc_player_SetRenderer()

Parameters

player	locked player instance
new_item	a valid renderer item or NULL (if unset)
data	opaque pointer set by vlc_player_AddListener()

◆ on_signal_changed

void(* vlc_player_cbs::on_signal_changed) (vlc_player_t *player, float quality, float strength, void *data)

Called when the media signal has changed.

Parameters

player	locked player instance
new_quality	signal quality
new_strength	signal strength,
data	opaque pointer set by vlc_player_AddListener()

◆ on_state_changed

void(* vlc_player_cbs::on_state_changed) (vlc_player_t *player, enum vlc_player_state new_state, void *data)

Called when the player state has changed.

See also: vlc_player_state

Parameters

player	locked player instance
new_state	new player state
data	opaque pointer set by vlc_player_AddListener()

Referenced by vlm_MediaInstanceNew().

◆ on_statistics_changed

void(* vlc_player_cbs::on_statistics_changed) (vlc_player_t *player, const struct input_stats_t *stats, void *data)

Called when the player has new statisics.

Note: The stats structure is only valid from this callback context. It can be copied in order to use it from an other context.

Parameters

player	locked player instance
stats	valid stats, only valid from this context
data	opaque pointer set by vlc_player_AddListener()

◆ on_stopping_current_media

void(* vlc_player_cbs::on_stopping_current_media) (vlc_player_t *player, input_item_t *current_media, void *data)

Called when the player will stop the current media.

Note: This can be called from the PLAYING state, before the player requests the next media, or from the STOPPING state, ie. when the player is stopping.

See also: vlc_player_SetCurrentMedia(); vlc_player_Stop()

Parameters

player	locked player instance
prev_media	media currently stopping
data	opaque pointer set by vlc_player_AddListener()

◆ on_teletext_enabled_changed

void(* vlc_player_cbs::on_teletext_enabled_changed) (vlc_player_t *player, bool enabled, void *data)

Called when teletext is enabled or disabled.

See also: vlc_player_SetTeletextEnabled()

Parameters

player	locked player instance
enabled	true if teletext is enabled
data	opaque pointer set by vlc_player_AddListener()

◆ on_teletext_menu_changed

void(* vlc_player_cbs::on_teletext_menu_changed) (vlc_player_t *player, bool has_teletext_menu, void *data)

Called when the media has a teletext menu.

Parameters

player	locked player instance
has_teletext_menu	true if the media has a teletext menu
data	opaque pointer set by vlc_player_AddListener()

◆ on_teletext_page_changed

void(* vlc_player_cbs::on_teletext_page_changed) (vlc_player_t *player, unsigned new_page, void *data)

Called when the teletext page has changed.

See also: vlc_player_SelectTeletextPage()

Parameters

player	locked player instance
new_page	page in the range ]0;888]
data	opaque pointer set by vlc_player_AddListener()

◆ on_teletext_transparency_changed

void(* vlc_player_cbs::on_teletext_transparency_changed) (vlc_player_t *player, bool enabled, void *data)

Called when the teletext transparency has changed.

See also: vlc_player_SetTeletextTransparency()

Parameters

player	locked player instance
enabled	true is the teletext overlay is transparent
data	opaque pointer set by vlc_player_AddListener()

◆ on_title_selection_changed

void(* vlc_player_cbs::on_title_selection_changed) (vlc_player_t *player, const struct vlc_player_title *new_title, size_t new_idx, void *data)

Called when a new title is selected.

There are no events when a title is unselected. Titles are automatically unselected when the title list changes. Titles and indexes are always valid inside the vlc_player_title_list sent by vlc_player_cbs.on_titles_changed.

Parameters

player	locked player instance
new_title	new selected title
new_idx	index of this title
data	opaque pointer set by vlc_player_AddListener()

◆ on_titles_changed

void(* vlc_player_cbs::on_titles_changed) (vlc_player_t *player, vlc_player_title_list *titles, void *data)

Called when the media titles has changed.

This event is not called when the opening media doesn't have any titles. This title list and all its elements are constant. If an element is to be updated, a new list will be sent from this callback.

Note: Users should hold this list with vlc_player_title_list_Hold() if they want to use it from an other context.

Parameters

player	locked player instance
titles	valid title list or NULL
data	opaque pointer set by vlc_player_AddListener()

◆ on_track_delay_changed

void(* vlc_player_cbs::on_track_delay_changed) (vlc_player_t *player, vlc_es_id_t *es_id, vlc_tick_t delay, void *data)

Called when a track delay has changed.

Parameters

player	locked player instance
es_id	valid track id
delay	a valid delay or INT64_MAX if the delay of this track is canceled

◆ on_track_list_changed

void(* vlc_player_cbs::on_track_list_changed) (vlc_player_t *player, enum vlc_player_list_action action, const struct vlc_player_track *track, void *data)

Called when a track is added, removed, or updated.

Note: The track is only valid from this callback context. Users should duplicate this track via vlc_player_track_Dup() if they want to use it from an other context.

Parameters

player	locked player instance
action	added, removed or updated
track	valid track
data	opaque pointer set by vlc_player_AddListener()

◆ on_track_selection_changed

void(* vlc_player_cbs::on_track_selection_changed) (vlc_player_t *player, vlc_es_id_t *unselected_id, vlc_es_id_t *selected_id, void *data)

Called when a new track is selected and/or unselected.

Note: This event can be called with both unselected_id and selected_id valid. This mean that a new track is replacing the old one.

Parameters

player	locked player instance
unselected_id	valid track id or NULL (when nothing is unselected)
selected_id	valid track id or NULL (when nothing is selected)
data	opaque pointer set by vlc_player_AddListener()

◆ on_vout_changed

void(* vlc_player_cbs::on_vout_changed) (vlc_player_t *player, enum vlc_player_vout_action action, vout_thread_t *vout, enum vlc_vout_order order, vlc_es_id_t *es_id, void *data)

Called when a vout is started or stopped.

Note: In case, several media with only one video track are played successively, the same vout instance will be started and stopped several time.

Parameters

player	locked player instance
action	started or stopped
vout	vout (can't be NULL)
order	vout order
es_id	the ES id associated with this vout
data	opaque pointer set by vlc_player_AddListener()

The documentation for this struct was generated from the following file:

include/vlc_player.h

Data Fields

Detailed Description

Field Documentation

◆ on_associated_subs_fps_changed

◆ on_atobloop_changed

◆ on_buffering_changed

◆ on_capabilities_changed

◆ on_category_delay_changed

◆ on_chapter_selection_changed

◆ on_cork_changed

◆ on_current_media_changed

◆ on_error_changed

◆ on_length_changed

◆ on_media_attachments_added

◆ on_media_epg_changed

◆ on_media_meta_changed

◆ on_media_subitems_changed

◆ on_playback_restore_queried

◆ on_position_changed

◆ on_program_list_changed

◆ on_program_selection_changed

◆ on_rate_changed

◆ on_recording_changed

◆ on_renderer_changed

◆ on_signal_changed

◆ on_state_changed

◆ on_statistics_changed

◆ on_stopping_current_media

◆ on_teletext_enabled_changed

◆ on_teletext_menu_changed

◆ on_teletext_page_changed

◆ on_teletext_transparency_changed

◆ on_title_selection_changed

◆ on_titles_changed

◆ on_track_delay_changed

◆ on_track_list_changed

◆ on_track_selection_changed

◆ on_vout_changed