LibVLC media player

A LibVLC media player plays one media (usually in a custom drawable). More...

Collaboration diagram for LibVLC media player:

Modules
	LibVLC video controls
	LibVLC audio controls
	LibVLC media player time watch API
	LibVLC media player concurrency API

Files
file	libvlc_media_player.h
	LibVLC simple media player external API.

Data Structures
struct	libvlc_title_description_t
struct	libvlc_chapter_description_t
	Description for chapters. More...
struct	libvlc_audio_output_t
	Description for audio output. More...
struct	libvlc_audio_output_device_t
	Description for audio output device. More...
struct	libvlc_video_setup_device_cfg_t
struct	libvlc_video_setup_device_info_t
struct	libvlc_video_render_cfg_t
struct	libvlc_video_output_cfg_t
struct	libvlc_video_frame_hdr10_metadata_t
struct	libvlc_player_program_t

Typedefs
typedef struct libvlc_media_player_t	libvlc_media_player_t
typedef struct libvlc_title_description_t	libvlc_title_description_t
typedef struct libvlc_chapter_description_t	libvlc_chapter_description_t
	Description for chapters.
typedef struct libvlc_audio_output_t	libvlc_audio_output_t
	Description for audio output.
typedef struct libvlc_audio_output_device_t	libvlc_audio_output_device_t
	Description for audio output device.
typedef enum libvlc_video_marquee_option_t	libvlc_video_marquee_option_t
	Marq options definition.
typedef enum libvlc_navigate_mode_t	libvlc_navigate_mode_t
	Navigation mode.
typedef enum libvlc_position_t	libvlc_position_t
	Enumeration of values used to set position (e.g.
typedef enum libvlc_video_fit_mode_t	libvlc_video_fit_mode_t
	Enumeration of values used to set the video fitting inside the display area.
typedef enum libvlc_teletext_key_t	libvlc_teletext_key_t
	Enumeration of teletext keys than can be passed via libvlc_video_set_teletext()
typedef enum libvlc_abloop_t	libvlc_abloop_t
	A to B loop state.
typedef struct libvlc_equalizer_t	libvlc_equalizer_t
	Opaque equalizer handle.
typedef enum libvlc_video_color_primaries_t	libvlc_video_color_primaries_t
	Enumeration of the Video color primaries.
typedef enum libvlc_video_color_space_t	libvlc_video_color_space_t
	Enumeration of the Video color spaces.
typedef enum libvlc_video_transfer_func_t	libvlc_video_transfer_func_t
	Enumeration of the Video transfer functions.
typedef void *(*	libvlc_video_lock_cb) (void *opaque, void **planes)
	Callback prototype to allocate and lock a picture buffer.
typedef void(*	libvlc_video_unlock_cb) (void *opaque, void *picture, void *const *planes)
	Callback prototype to unlock a picture buffer.
typedef void(*	libvlc_video_display_cb) (void *opaque, void *picture)
	Callback prototype to display a picture.
typedef unsigned(*	libvlc_video_format_cb) (void **opaque, char *chroma, unsigned *width, unsigned *height, unsigned *pitches, unsigned *lines)
	Callback prototype to configure picture buffers format.
typedef void(*	libvlc_video_cleanup_cb) (void *opaque)
	Callback prototype to configure picture buffers format.
typedef struct libvlc_video_setup_device_cfg_t	libvlc_video_setup_device_cfg_t
typedef struct libvlc_video_setup_device_info_t	libvlc_video_setup_device_info_t
typedef bool(*	libvlc_video_output_setup_cb) (void **opaque, const libvlc_video_setup_device_cfg_t *cfg, libvlc_video_setup_device_info_t *out)
	Callback prototype called to initialize user data.
typedef void(*	libvlc_video_output_cleanup_cb) (void *opaque)
	Callback prototype called to release user data.
typedef struct libvlc_video_render_cfg_t	libvlc_video_render_cfg_t
typedef struct libvlc_video_output_cfg_t	libvlc_video_output_cfg_t
typedef bool(*	libvlc_video_update_output_cb) (void *opaque, const libvlc_video_render_cfg_t *cfg, libvlc_video_output_cfg_t *output)
	Callback prototype called on video size changes.
typedef void(*	libvlc_video_swap_cb) (void *opaque)
	Callback prototype called after performing drawing calls.
typedef bool(*	libvlc_video_makeCurrent_cb) (void *opaque, bool enter)
	Callback prototype to set up the OpenGL context for rendering.
typedef void *(*	libvlc_video_getProcAddress_cb) (void *opaque, const char *fct_name)
	Callback prototype to load opengl functions.
typedef struct libvlc_video_frame_hdr10_metadata_t	libvlc_video_frame_hdr10_metadata_t
typedef enum libvlc_video_metadata_type_t	libvlc_video_metadata_type_t
typedef void(*	libvlc_video_frameMetadata_cb) (void *opaque, libvlc_video_metadata_type_t type, const void *metadata)
	Callback prototype to receive metadata before rendering.
typedef enum libvlc_video_engine_t	libvlc_video_engine_t
	Enumeration of the Video engine to be used on output.
typedef void(*	libvlc_video_output_resize_cb) (void *report_opaque, unsigned width, unsigned height)
	Callback type that can be called to request a render size changes.
typedef enum libvlc_video_output_mouse_button_t	libvlc_video_output_mouse_button_t
	Enumeration of the different mouse buttons that can be reported for user interaction can be passed to libvlc_video_output_mouse_press_cb and libvlc_video_output_mouse_release_cb.
typedef void(*	libvlc_video_output_mouse_move_cb) (void *opaque, int x, int y)
	Callback type that can be called to notify the mouse position when hovering the render surface.
typedef void(*	libvlc_video_output_mouse_press_cb) (void *opaque, libvlc_video_output_mouse_button_t button)
	Callback type that can be called to notify when a mouse button is pressed in the rendering surface.
typedef void(*	libvlc_video_output_mouse_release_cb) (void *opaque, libvlc_video_output_mouse_button_t button)
	Callback type that can be called to notify when a mouse button is released in the rendering surface.
typedef void(*	libvlc_video_output_set_window_cb) (void *opaque, libvlc_video_output_resize_cb report_size_change, libvlc_video_output_mouse_move_cb report_mouse_move, libvlc_video_output_mouse_press_cb report_mouse_pressed, libvlc_video_output_mouse_release_cb report_mouse_released, void *report_opaque)
	Set the callback to call when the host app resizes the rendering area.
typedef bool(*	libvlc_video_output_select_plane_cb) (void *opaque, size_t plane, void *output)
	Tell the host the rendering for the given plane is about to start.
typedef void(*	libvlc_audio_play_cb) (void *data, const void *samples, unsigned count, int64_t pts)
	Callback prototype for audio playback.
typedef void(*	libvlc_audio_pause_cb) (void *data, int64_t pts)
	Callback prototype for audio pause.
typedef void(*	libvlc_audio_resume_cb) (void *data, int64_t pts)
	Callback prototype for audio resumption.
typedef void(*	libvlc_audio_flush_cb) (void *data, int64_t pts)
	Callback prototype for audio buffer flush.
typedef void(*	libvlc_audio_drain_cb) (void *data)
	Callback prototype for audio buffer drain.
typedef void(*	libvlc_audio_set_volume_cb) (void *data, float volume, bool mute)
	Callback prototype for audio volume change.
typedef int(*	libvlc_audio_setup_cb) (void **opaque, char *format, unsigned *rate, unsigned *channels)
	Callback prototype to setup the audio playback.
typedef void(*	libvlc_audio_cleanup_cb) (void *opaque)
	Callback prototype for audio playback cleanup.
typedef struct libvlc_player_program_t	libvlc_player_program_t
typedef struct libvlc_player_programlist_t	libvlc_player_programlist_t
	Opaque struct containing a list of program.

Enumerations
enum	{ libvlc_title_menu = 0x01 , libvlc_title_interactive = 0x02 }
	Description for titles. More...
enum	libvlc_video_marquee_option_t {   libvlc_marquee_Enable = 0 , libvlc_marquee_Text , libvlc_marquee_Color , libvlc_marquee_Opacity ,   libvlc_marquee_Position , libvlc_marquee_Refresh , libvlc_marquee_Size , libvlc_marquee_Timeout ,   libvlc_marquee_X , libvlc_marquee_Y }
	Marq options definition. More...
enum	libvlc_navigate_mode_t {   libvlc_navigate_activate = 0 , libvlc_navigate_up , libvlc_navigate_down , libvlc_navigate_left ,   libvlc_navigate_right , libvlc_navigate_popup }
	Navigation mode. More...
enum	libvlc_position_t {   libvlc_position_disable =-1 , libvlc_position_center , libvlc_position_left , libvlc_position_right ,   libvlc_position_top , libvlc_position_top_left , libvlc_position_top_right , libvlc_position_bottom ,   libvlc_position_bottom_left , libvlc_position_bottom_right }
	Enumeration of values used to set position (e.g. More...
enum	libvlc_video_fit_mode_t {   libvlc_video_fit_none = 0 , libvlc_video_fit_smaller , libvlc_video_fit_larger , libvlc_video_fit_width ,   libvlc_video_fit_height }
	Enumeration of values used to set the video fitting inside the display area. More...
enum	libvlc_teletext_key_t {   libvlc_teletext_key_red = 'r' << 16 , libvlc_teletext_key_green = 'g' << 16 , libvlc_teletext_key_yellow = 'y' << 16 , libvlc_teletext_key_blue = 'b' << 16 ,   libvlc_teletext_key_index = 'i' << 16 }
	Enumeration of teletext keys than can be passed via libvlc_video_set_teletext() More...
enum	libvlc_abloop_t { libvlc_abloop_none , libvlc_abloop_a , libvlc_abloop_b }
	A to B loop state. More...
enum	libvlc_video_color_primaries_t {   libvlc_video_primaries_BT601_525 = 1 , libvlc_video_primaries_BT601_625 = 2 , libvlc_video_primaries_BT709 = 3 , libvlc_video_primaries_BT2020 = 4 ,   libvlc_video_primaries_DCI_P3 = 5 , libvlc_video_primaries_BT470_M = 6 }
	Enumeration of the Video color primaries. More...
enum	libvlc_video_color_space_t { libvlc_video_colorspace_BT601 = 1 , libvlc_video_colorspace_BT709 = 2 , libvlc_video_colorspace_BT2020 = 3 }
	Enumeration of the Video color spaces. More...
enum	libvlc_video_transfer_func_t {   libvlc_video_transfer_func_LINEAR = 1 , libvlc_video_transfer_func_SRGB = 2 , libvlc_video_transfer_func_BT470_BG = 3 , libvlc_video_transfer_func_BT470_M = 4 ,   libvlc_video_transfer_func_BT709 = 5 , libvlc_video_transfer_func_PQ = 6 , libvlc_video_transfer_func_SMPTE_240 = 7 , libvlc_video_transfer_func_HLG = 8 }
	Enumeration of the Video transfer functions. More...
enum	libvlc_video_metadata_type_t { libvlc_video_metadata_frame_hdr10 }
enum	libvlc_video_engine_t {   libvlc_video_engine_disable , libvlc_video_engine_opengl , libvlc_video_engine_gles2 , libvlc_video_engine_d3d11 ,   libvlc_video_engine_d3d9 }
	Enumeration of the Video engine to be used on output. More...
enum	libvlc_video_output_mouse_button_t { libvlc_video_output_mouse_button_left = 0 , libvlc_video_output_mouse_button_middle = 1 , libvlc_video_output_mouse_button_right = 2 }
	Enumeration of the different mouse buttons that can be reported for user interaction can be passed to libvlc_video_output_mouse_press_cb and libvlc_video_output_mouse_release_cb. More...

Functions
LIBVLC_API libvlc_media_player_t *	libvlc_media_player_new (libvlc_instance_t *p_libvlc_instance)
	Create an empty Media Player object.
LIBVLC_API libvlc_media_player_t *	libvlc_media_player_new_from_media (libvlc_instance_t *inst, libvlc_media_t *p_md)
	Create a Media Player object from a Media.
LIBVLC_API void	libvlc_media_player_release (libvlc_media_player_t *p_mi)
	Release a media_player after use Decrement the reference count of a media player object.
LIBVLC_API libvlc_media_player_t *	libvlc_media_player_retain (libvlc_media_player_t *p_mi)
	Retain a reference to a media player object.
LIBVLC_API void	libvlc_media_player_set_media (libvlc_media_player_t *p_mi, libvlc_media_t *p_md)
	Set the media that will be used by the media_player.
LIBVLC_API libvlc_media_t *	libvlc_media_player_get_media (libvlc_media_player_t *p_mi)
	Get the media used by the media_player.
LIBVLC_API libvlc_event_manager_t *	libvlc_media_player_event_manager (libvlc_media_player_t *p_mi)
	Get the Event Manager from which the media player send event.
LIBVLC_API bool	libvlc_media_player_is_playing (libvlc_media_player_t *p_mi)
	is_playing
LIBVLC_API int	libvlc_media_player_play (libvlc_media_player_t *p_mi)
	Play.
LIBVLC_API void	libvlc_media_player_set_pause (libvlc_media_player_t *mp, int do_pause)
	Pause or resume (no effect if there is no media)
LIBVLC_API void	libvlc_media_player_pause (libvlc_media_player_t *p_mi)
	Toggle pause (no effect if there is no media)
LIBVLC_API int	libvlc_media_player_stop_async (libvlc_media_player_t *p_mi)
	Stop asynchronously.
LIBVLC_API int	libvlc_media_player_set_renderer (libvlc_media_player_t *p_mi, libvlc_renderer_item_t *p_item)
	Set a renderer to the media player.
LIBVLC_API void	libvlc_video_set_callbacks (libvlc_media_player_t *mp, libvlc_video_lock_cb lock, libvlc_video_unlock_cb unlock, libvlc_video_display_cb display, void *opaque)
	Set callbacks and private data to render decoded video to a custom area in memory.
LIBVLC_API void	libvlc_video_set_format (libvlc_media_player_t *mp, const char *chroma, unsigned width, unsigned height, unsigned pitch)
	Set decoded video chroma and dimensions.
LIBVLC_API void	libvlc_video_set_format_callbacks (libvlc_media_player_t *mp, libvlc_video_format_cb setup, libvlc_video_cleanup_cb cleanup)
	Set decoded video chroma and dimensions.
LIBVLC_API bool	libvlc_video_set_output_callbacks (libvlc_media_player_t *mp, libvlc_video_engine_t engine, libvlc_video_output_setup_cb setup_cb, libvlc_video_output_cleanup_cb cleanup_cb, libvlc_video_output_set_window_cb window_cb, libvlc_video_update_output_cb update_output_cb, libvlc_video_swap_cb swap_cb, libvlc_video_makeCurrent_cb makeCurrent_cb, libvlc_video_getProcAddress_cb getProcAddress_cb, libvlc_video_frameMetadata_cb metadata_cb, libvlc_video_output_select_plane_cb select_plane_cb, void *opaque)
	Set callbacks and data to render decoded video to a custom texture.
LIBVLC_API void	libvlc_media_player_set_nsobject (libvlc_media_player_t *p_mi, void *drawable)
	Set the handler where the media player should display its video output.
LIBVLC_API void *	libvlc_media_player_get_nsobject (libvlc_media_player_t *p_mi)
	Get the NSView handler previously set with libvlc_media_player_set_nsobject().
LIBVLC_API void	libvlc_media_player_set_xwindow (libvlc_media_player_t *p_mi, uint32_t drawable)
	Set an X Window System drawable where the media player should render its video output.
LIBVLC_API uint32_t	libvlc_media_player_get_xwindow (libvlc_media_player_t *p_mi)
	Get the X Window System window identifier previously set with libvlc_media_player_set_xwindow().
LIBVLC_API void	libvlc_media_player_set_hwnd (libvlc_media_player_t *p_mi, void *drawable)
	Set a Win32/Win64 API window handle (HWND) where the media player should render its video output.
LIBVLC_API void *	libvlc_media_player_get_hwnd (libvlc_media_player_t *p_mi)
	Get the Windows API window handle (HWND) previously set with libvlc_media_player_set_hwnd().
LIBVLC_API void	libvlc_media_player_set_android_context (libvlc_media_player_t *p_mi, void *p_awindow_handler)
	Set the android context.
LIBVLC_API void	libvlc_audio_set_callbacks (libvlc_media_player_t *mp, libvlc_audio_play_cb play, libvlc_audio_pause_cb pause, libvlc_audio_resume_cb resume, libvlc_audio_flush_cb flush, libvlc_audio_drain_cb drain, void *opaque)
	Sets callbacks and private data for decoded audio.
LIBVLC_API void	libvlc_audio_set_volume_callback (libvlc_media_player_t *mp, libvlc_audio_set_volume_cb set_volume)
	Set callbacks and private data for decoded audio.
LIBVLC_API void	libvlc_audio_set_format_callbacks (libvlc_media_player_t *mp, libvlc_audio_setup_cb setup, libvlc_audio_cleanup_cb cleanup)
	Sets decoded audio format via callbacks.
LIBVLC_API void	libvlc_audio_set_format (libvlc_media_player_t *mp, const char *format, unsigned rate, unsigned channels)
	Sets a fixed decoded audio format.
LIBVLC_API libvlc_time_t	libvlc_media_player_get_length (libvlc_media_player_t *p_mi)
	Get the current movie length (in ms).
LIBVLC_API libvlc_time_t	libvlc_media_player_get_time (libvlc_media_player_t *p_mi)
	Get the current movie time (in ms).
LIBVLC_API int	libvlc_media_player_set_time (libvlc_media_player_t *p_mi, libvlc_time_t i_time, bool b_fast)
	Set the movie time (in ms).
LIBVLC_API int	libvlc_media_player_jump_time (libvlc_media_player_t *p_mi, libvlc_time_t i_time)
	Jump the movie time (in ms).
LIBVLC_API double	libvlc_media_player_get_position (libvlc_media_player_t *p_mi)
	Get movie position as percentage between 0.0 and 1.0.
LIBVLC_API int	libvlc_media_player_set_position (libvlc_media_player_t *p_mi, double f_pos, bool b_fast)
	Set movie position as percentage between 0.0 and 1.0.
LIBVLC_API int	libvlc_media_player_set_abloop (libvlc_media_player_t *p_mi, libvlc_abloop_t abloop)
	Enable A to B loop for the current media.
LIBVLC_API libvlc_abloop_t	libvlc_media_player_get_abloop (libvlc_media_player_t *p_mi, libvlc_time_t *a_time, double *a_pos, libvlc_time_t *b_time, double *b_pos)
	Get the A to B loop status.
LIBVLC_API void	libvlc_media_player_set_chapter (libvlc_media_player_t *p_mi, int i_chapter)
	Set movie chapter (if applicable).
LIBVLC_API int	libvlc_media_player_get_chapter (libvlc_media_player_t *p_mi)
	Get movie chapter.
LIBVLC_API int	libvlc_media_player_get_chapter_count (libvlc_media_player_t *p_mi)
	Get movie chapter count.
LIBVLC_API int	libvlc_media_player_get_chapter_count_for_title (libvlc_media_player_t *p_mi, int i_title)
	Get title chapter count.
LIBVLC_API void	libvlc_media_player_set_title (libvlc_media_player_t *p_mi, int i_title)
	Set movie title.
LIBVLC_API int	libvlc_media_player_get_title (libvlc_media_player_t *p_mi)
	Get movie title.
LIBVLC_API int	libvlc_media_player_get_title_count (libvlc_media_player_t *p_mi)
	Get movie title count.
LIBVLC_API void	libvlc_media_player_previous_chapter (libvlc_media_player_t *p_mi)
	Set previous chapter (if applicable)
LIBVLC_API void	libvlc_media_player_next_chapter (libvlc_media_player_t *p_mi)
	Set next chapter (if applicable)
LIBVLC_API float	libvlc_media_player_get_rate (libvlc_media_player_t *p_mi)
	Get the requested movie play rate.
LIBVLC_API int	libvlc_media_player_set_rate (libvlc_media_player_t *p_mi, float rate)
	Set movie play rate.
LIBVLC_API libvlc_state_t	libvlc_media_player_get_state (libvlc_media_player_t *p_mi)
	Get current movie state.
LIBVLC_API unsigned	libvlc_media_player_has_vout (libvlc_media_player_t *p_mi)
	How many video outputs does this media player have?
LIBVLC_API bool	libvlc_media_player_is_seekable (libvlc_media_player_t *p_mi)
	Is this media player seekable?
LIBVLC_API bool	libvlc_media_player_can_pause (libvlc_media_player_t *p_mi)
	Can this media player be paused?
LIBVLC_API bool	libvlc_media_player_program_scrambled (libvlc_media_player_t *p_mi)
	Check if the current program is scrambled.
LIBVLC_API void	libvlc_media_player_next_frame (libvlc_media_player_t *p_mi)
	Display the next frame (if supported)
LIBVLC_API void	libvlc_media_player_navigate (libvlc_media_player_t *p_mi, unsigned navigate)
	Navigate through DVD Menu.
LIBVLC_API void	libvlc_media_player_set_video_title_display (libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout)
	Set if, and how, the video title will be shown when media is played.
LIBVLC_API libvlc_media_tracklist_t *	libvlc_media_player_get_tracklist (libvlc_media_player_t *p_mi, libvlc_track_type_t type, bool selected)
	Get the track list for one type.
LIBVLC_API libvlc_media_track_t *	libvlc_media_player_get_selected_track (libvlc_media_player_t *p_mi, libvlc_track_type_t type)
	Get the selected track for one type.
LIBVLC_API libvlc_media_track_t *	libvlc_media_player_get_track_from_id (libvlc_media_player_t *p_mi, const char *psz_id)
LIBVLC_API void	libvlc_media_player_select_track (libvlc_media_player_t *p_mi, const libvlc_media_track_t *track)
	Select a track.
LIBVLC_API void	libvlc_media_player_unselect_track_type (libvlc_media_player_t *p_mi, libvlc_track_type_t type)
	Unselect all tracks for a given type.
LIBVLC_API void	libvlc_media_player_select_tracks (libvlc_media_player_t *p_mi, libvlc_track_type_t type, const libvlc_media_track_t **tracks, size_t track_count)
	Select multiple tracks for one type.
LIBVLC_API void	libvlc_media_player_select_tracks_by_ids (libvlc_media_player_t *p_mi, libvlc_track_type_t type, const char *psz_ids)
	Select tracks by their string identifier.
LIBVLC_API int	libvlc_media_player_add_slave (libvlc_media_player_t *p_mi, libvlc_media_slave_type_t i_type, const char *psz_uri, bool b_select)
	Add a slave to the current media player.
LIBVLC_API void	libvlc_player_program_delete (libvlc_player_program_t *program)
	Delete a program struct.
LIBVLC_API size_t	libvlc_player_programlist_count (const libvlc_player_programlist_t *list)
	Get the number of programs in a programlist.
LIBVLC_API libvlc_player_program_t *	libvlc_player_programlist_at (libvlc_player_programlist_t *list, size_t index)
	Get a program at a specific index.
LIBVLC_API void	libvlc_player_programlist_delete (libvlc_player_programlist_t *list)
	Release a programlist.
LIBVLC_API void	libvlc_media_player_select_program_id (libvlc_media_player_t *p_mi, int i_group_id)
	Select program with a given program id.
LIBVLC_API libvlc_player_program_t *	libvlc_media_player_get_selected_program (libvlc_media_player_t *p_mi)
	Get the selected program.
LIBVLC_API libvlc_player_program_t *	libvlc_media_player_get_program_from_id (libvlc_media_player_t *p_mi, int i_group_id)
	Get a program struct from a program id.
LIBVLC_API libvlc_player_programlist_t *	libvlc_media_player_get_programlist (libvlc_media_player_t *p_mi)
	Get the program list.

Detailed Description

A LibVLC media player plays one media (usually in a custom drawable).

Typedef Documentation

libvlc_abloop_t

typedef enum libvlc_abloop_t libvlc_abloop_t

A to B loop state.

libvlc_audio_cleanup_cb

typedef void(* libvlc_audio_cleanup_cb) (void *opaque)

Callback prototype for audio playback cleanup.

This is called when the media player no longer needs an audio output.

Parameters

[in]

opaque

data pointer as passed to libvlc_audio_set_callbacks()

libvlc_audio_drain_cb

typedef void(* libvlc_audio_drain_cb) (void *data)

Callback prototype for audio buffer drain.

LibVLC may invoke this callback when the decoded audio track is ending. There will be no further decoded samples for the track, but playback should nevertheless continue until all already pending buffers are rendered.

Parameters

[in]

data

data pointer as passed to libvlc_audio_set_callbacks()

libvlc_audio_flush_cb

typedef void(* libvlc_audio_flush_cb) (void *data, int64_t pts)

Callback prototype for audio buffer flush.

LibVLC invokes this callback if it needs to discard all pending buffers and stop playback as soon as possible. This typically occurs when the media is stopped.

Parameters

[in]

data

data pointer as passed to libvlc_audio_set_callbacks()

libvlc_audio_output_device_t

typedef struct libvlc_audio_output_device_t libvlc_audio_output_device_t

Description for audio output device.

libvlc_audio_output_t

typedef struct libvlc_audio_output_t libvlc_audio_output_t

Description for audio output.

It contains name, description and pointer to next record.

libvlc_audio_pause_cb

typedef void(* libvlc_audio_pause_cb) (void *data, int64_t pts)

Callback prototype for audio pause.

LibVLC invokes this callback to pause audio playback.

Note

The pause callback is never called if the audio is already paused.

Parameters

[in]	data	data pointer as passed to libvlc_audio_set_callbacks()
	pts	time stamp of the pause request (should be elapsed already)

libvlc_audio_play_cb

typedef void(* libvlc_audio_play_cb) (void *data, const void *samples, unsigned count, int64_t pts)

Callback prototype for audio playback.

The LibVLC media player decodes and post-processes the audio signal asynchronously (in an internal thread). Whenever audio samples are ready to be queued to the output, this callback is invoked.

The number of samples provided per invocation may depend on the file format, the audio coding algorithm, the decoder plug-in, the post-processing filters and timing. Application must not assume a certain number of samples.

The exact format of audio samples is determined by libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() as is the channels layout.

Note that the number of samples is per channel. For instance, if the audio track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds of audio signal - regardless of the number of audio channels.

Parameters

[in]	data	data pointer as passed to libvlc_audio_set_callbacks()
[in]	samples	pointer to a table of audio samples to play back
	count	number of audio samples to play back
	pts	expected play time stamp (see libvlc_delay())

libvlc_audio_resume_cb

typedef void(* libvlc_audio_resume_cb) (void *data, int64_t pts)

Callback prototype for audio resumption.

LibVLC invokes this callback to resume audio playback after it was previously paused.

Note

The resume callback is never called if the audio is not paused.

Parameters

[in]	data	data pointer as passed to libvlc_audio_set_callbacks()
	pts	time stamp of the resumption request (should be elapsed already)

libvlc_audio_set_volume_cb

typedef void(* libvlc_audio_set_volume_cb) (void *data, float volume, bool mute)

Callback prototype for audio volume change.

Parameters

[in]	data	data pointer as passed to libvlc_audio_set_callbacks()
	volume	software volume (1. = nominal, 0. = mute)
	mute	muted flag

libvlc_audio_setup_cb

typedef int(* libvlc_audio_setup_cb) (void **opaque, char *format, unsigned *rate, unsigned *channels)

Callback prototype to setup the audio playback.

This is called when the media player needs to create a new audio output.

Parameters

[in,out]	opaque	pointer to the data pointer passed to libvlc_audio_set_callbacks()
[in,out]	format	4 bytes sample format
[in,out]	rate	sample rate
[in,out]	channels	channels count

Returns

0 on success, anything else to skip audio playback

libvlc_chapter_description_t

typedef struct libvlc_chapter_description_t libvlc_chapter_description_t

Description for chapters.

libvlc_equalizer_t

typedef struct libvlc_equalizer_t libvlc_equalizer_t

Opaque equalizer handle.

Equalizer settings can be applied to a media player.

libvlc_media_player_t

typedef struct libvlc_media_player_t libvlc_media_player_t

libvlc_navigate_mode_t

typedef enum libvlc_navigate_mode_t libvlc_navigate_mode_t

Navigation mode.

libvlc_player_program_t

typedef struct libvlc_player_program_t libvlc_player_program_t

libvlc_player_programlist_t

typedef struct libvlc_player_programlist_t libvlc_player_programlist_t

Opaque struct containing a list of program.

libvlc_position_t

typedef enum libvlc_position_t libvlc_position_t

Enumeration of values used to set position (e.g.

of video title).

libvlc_teletext_key_t

typedef enum libvlc_teletext_key_t libvlc_teletext_key_t

Enumeration of teletext keys than can be passed via libvlc_video_set_teletext()

libvlc_title_description_t

typedef struct libvlc_title_description_t libvlc_title_description_t

libvlc_video_cleanup_cb

typedef void(* libvlc_video_cleanup_cb) (void *opaque)

Callback prototype to configure picture buffers format.

Parameters

[in]

opaque

private pointer as passed to libvlc_video_set_format_callbacks() (and possibly modified by libvlc_video_format_cb)

libvlc_video_color_primaries_t

typedef enum libvlc_video_color_primaries_t libvlc_video_color_primaries_t

Enumeration of the Video color primaries.

libvlc_video_color_space_t

typedef enum libvlc_video_color_space_t libvlc_video_color_space_t

Enumeration of the Video color spaces.

libvlc_video_display_cb

typedef void(* libvlc_video_display_cb) (void *opaque, void *picture)

Callback prototype to display a picture.

When the video frame needs to be shown, as determined by the media playback clock, the display callback is invoked.

Parameters

[in]	opaque	private pointer as passed to libvlc_video_set_callbacks()
[in]	picture	private pointer returned from the libvlc_video_lock_cb callback

libvlc_video_engine_t

typedef enum libvlc_video_engine_t libvlc_video_engine_t

Enumeration of the Video engine to be used on output.

can be passed to libvlc_video_set_output_callbacks

libvlc_video_fit_mode_t

typedef enum libvlc_video_fit_mode_t libvlc_video_fit_mode_t

Enumeration of values used to set the video fitting inside the display area.

libvlc_video_format_cb

typedef unsigned(* libvlc_video_format_cb) (void **opaque, char *chroma, unsigned *width, unsigned *height, unsigned *pitches, unsigned *lines)

Callback prototype to configure picture buffers format.

This callback gets the format of the video as output by the video decoder and the chain of video filters (if any). It can opt to change any parameter as it needs. In that case, LibVLC will attempt to convert the video format (rescaling and chroma conversion) but these operations can be CPU intensive.

Parameters

[in,out]	opaque	pointer to the private pointer passed to libvlc_video_set_callbacks()
[in,out]	chroma	pointer to the 4 bytes video format identifier
[in,out]	width	pointer to the buffer width in pixels
[in,out]	height	pointer to the buffer height in pixels
[out]	pitches	table of scanline pitches in bytes for each pixel plane (the table is allocated by LibVLC)
[out]	lines	table of scanlines count for each plane

Returns

the number of picture buffers allocated, 0 indicates failure

Version

LibVLC 4.0.0 and later.

Parameters

[in]	width	pointer to display width - 1 in pixels
[in]	height	pointer to display height - 1 in pixels

Note

For each pixels plane, the scanline pitch must be bigger than or equal to the number of bytes per pixel multiplied by the pixel width. Similarly, the number of scanlines must be bigger than of equal to the pixel height. Furthermore, we recommend that pitches and lines be multiple of 32 to not break assumptions that might be held by optimized code in the video decoders, video filters and/or video converters.

libvlc_video_frame_hdr10_metadata_t

typedef struct libvlc_video_frame_hdr10_metadata_t libvlc_video_frame_hdr10_metadata_t

libvlc_video_frameMetadata_cb

typedef void(* libvlc_video_frameMetadata_cb) (void *opaque, libvlc_video_metadata_type_t type, const void *metadata)

Callback prototype to receive metadata before rendering.

Parameters

[in]	opaque	private pointer passed to the libvlc_video_set_output_callbacks()
[in]	type	type of data passed in metadata
[in]	metadata	the type of metadata

Version

LibVLC 4.0.0 or later

libvlc_video_getProcAddress_cb

typedef void *(* libvlc_video_getProcAddress_cb) (void *opaque, const char *fct_name)

Callback prototype to load opengl functions.

Parameters

[in]	opaque	private pointer set on the opaque parameter of libvlc_video_output_setup_cb()
	fct_name	name of the opengl function to load

Returns

a pointer to the named OpenGL function the NULL otherwise

Version

LibVLC 4.0.0 or later

libvlc_video_lock_cb

typedef void *(* libvlc_video_lock_cb) (void *opaque, void **planes)

Callback prototype to allocate and lock a picture buffer.

Whenever a new video frame needs to be decoded, the lock callback is invoked. Depending on the video chroma, one or three pixel planes of adequate dimensions must be returned via the second parameter. Those planes must be aligned on 32-bytes boundaries.

Parameters

[in]	opaque	private pointer as passed to libvlc_video_set_callbacks()
[out]	planes	start address of the pixel planes (LibVLC allocates the array of void pointers, this callback must initialize the array)

Returns

a private pointer for the display and unlock callbacks to identify the picture buffers

libvlc_video_makeCurrent_cb

typedef bool(* libvlc_video_makeCurrent_cb) (void *opaque, bool enter)

Callback prototype to set up the OpenGL context for rendering.

Tell the host the rendering is about to start/has finished.

Parameters

[in]	opaque	private pointer set on the opaque parameter of libvlc_video_output_setup_cb()
[in]	enter	true to set the context as current, false to unset it

Returns

true on success

Version

LibVLC 4.0.0 or later

On Direct3D11 the following may change on the provided ID3D11DeviceContext* between enter being true and enter being false:

• IASetPrimitiveTopology()
• IASetInputLayout()
• IASetVertexBuffers()
• IASetIndexBuffer()
• VSSetConstantBuffers()
• VSSetShader()
• PSSetSamplers()
• PSSetConstantBuffers()
• PSSetShaderResources()
• PSSetShader()
• RSSetViewports()
• DrawIndexed()

libvlc_video_marquee_option_t

typedef enum libvlc_video_marquee_option_t libvlc_video_marquee_option_t

Marq options definition.

libvlc_video_metadata_type_t

typedef enum libvlc_video_metadata_type_t libvlc_video_metadata_type_t

libvlc_video_output_cfg_t

typedef struct libvlc_video_output_cfg_t libvlc_video_output_cfg_t

libvlc_video_output_cleanup_cb

typedef void(* libvlc_video_output_cleanup_cb) (void *opaque)

Callback prototype called to release user data.

Parameters

[in]

opaque

private pointer set on the opaque parameter of libvlc_video_output_setup_cb()

Version

LibVLC 4.0.0 or later

libvlc_video_output_mouse_button_t

typedef enum libvlc_video_output_mouse_button_t libvlc_video_output_mouse_button_t

Enumeration of the different mouse buttons that can be reported for user interaction can be passed to libvlc_video_output_mouse_press_cb and libvlc_video_output_mouse_release_cb.

libvlc_video_output_mouse_move_cb

typedef void(* libvlc_video_output_mouse_move_cb) (void *opaque, int x, int y)

Callback type that can be called to notify the mouse position when hovering the render surface.

libvlc will provide a callback of this type when calling libvlc_video_output_set_window_cb.

The position (0,0) denotes the top left corner, bottom right corner position is (width,height) as reported by libvlc_video_output_resize_cb.

Parameters

opaque	parameter passed to libvlc_video_output_set_window_cb. [IN]
x	horizontal mouse position in libvlc_video_output_resize_cb coordinates. [IN]
y	vertical mouse position in libvlc_video_output_resize_cb coordinates. [IN]

libvlc_video_output_mouse_press_cb

typedef void(* libvlc_video_output_mouse_press_cb) (void *opaque, libvlc_video_output_mouse_button_t button)

Callback type that can be called to notify when a mouse button is pressed in the rendering surface.

libvlc will provide a callback of this type when calling libvlc_video_output_set_window_cb.

The button event will be reported at the last position provided by libvlc_video_output_mouse_move_cb

Parameters

opaque	parameter passed to libvlc_video_output_set_window_cb. [IN]
button	represent the button pressed, see libvlc_video_output_mouse_button_t for available buttons. [IN]

libvlc_video_output_mouse_release_cb

typedef void(* libvlc_video_output_mouse_release_cb) (void *opaque, libvlc_video_output_mouse_button_t button)

Callback type that can be called to notify when a mouse button is released in the rendering surface.

libvlc will provide a callback of this type when calling libvlc_video_output_set_window_cb.

The button event will be reported at the last position provided by libvlc_video_output_mouse_move_cb.

Parameters

opaque	parameter passed to libvlc_video_output_set_window_cb. [IN]
button	represent the button released, see libvlc_video_output_mouse_button_t for available buttons. [IN]

libvlc_video_output_resize_cb

typedef void(* libvlc_video_output_resize_cb) (void *report_opaque, unsigned width, unsigned height)

Callback type that can be called to request a render size changes.

libvlc will provide a callback of this type when calling libvlc_video_output_set_window_cb.

Parameters

report_opaque	parameter passed to libvlc_video_output_set_window_cb. [IN]
width	new rendering width requested. [IN]
height	new rendering height requested. [IN]

libvlc_video_output_select_plane_cb

typedef bool(* libvlc_video_output_select_plane_cb) (void *opaque, size_t plane, void *output)

Tell the host the rendering for the given plane is about to start.

Parameters

[in]	opaque	private pointer set on the opaque parameter of libvlc_video_output_setup_cb()
	plane	number of the rendering plane to select
	output	handle of the rendering output for the given plane

Returns

true on success

Version

LibVLC 4.0.0 or later

Note

This is only used with libvlc_video_engine_d3d11.

The output parameter receives the ID3D11RenderTargetView* to use for rendering the plane.

If this callback is not used (set to NULL in libvlc_video_set_output_callbacks()) OMSetRenderTargets has to be set during the libvlc_video_makeCurrent_cb() entering call.

The number of planes depend on the DXGI_FORMAT returned during the libvlc_video_update_output_cb() call. It's usually one plane except for semi-planar formats like DXGI_FORMAT_NV12 or DXGI_FORMAT_P010.

This callback is called between libvlc_video_makeCurrent_cb current/not-current calls.

libvlc_video_output_set_window_cb

typedef void(* libvlc_video_output_set_window_cb) (void *opaque, libvlc_video_output_resize_cb report_size_change, libvlc_video_output_mouse_move_cb report_mouse_move, libvlc_video_output_mouse_press_cb report_mouse_pressed, libvlc_video_output_mouse_release_cb report_mouse_released, void *report_opaque)

Set the callback to call when the host app resizes the rendering area.

This allows text rendering and aspect ratio to be handled properly when the host rendering size changes and to provide mouse.

It may be called before the libvlc_video_output_setup_cb callback.

Warning

These callbacks cannot be called concurrently, the caller is responsible for serialization

Parameters

[in]	opaque	private pointer set on the opaque parameter of libvlc_video_output_setup_cb()
[in]	report_size_change	callback which must be called when the host size changes. The callback is valid until another call to libvlc_video_output_set_window_cb is done. This may be called from any thread.
[in]	report_mouse_move	callback which must be called when the mouse position change on the video surface. The coordinates are relative to the size reported through the report_size_change. This may be called from any thread.
[in]	report_mouse_pressed	callback which must be called when a mouse button is pressed on the video surface, The position of the event is the last position reported by the report_mouse_move callback. This may be called from any thread.
[in]	report_mouse_released	callback which must be called when a mouse button is released on the video surface, The position of the event is the last position reported by the report_mouse_move callback. This may be called from any thread.
[in]	report_opaque	private pointer to pass to the report_size_change callback.

libvlc_video_output_setup_cb

typedef bool(* libvlc_video_output_setup_cb) (void **opaque, const libvlc_video_setup_device_cfg_t *cfg, libvlc_video_setup_device_info_t *out)

Callback prototype called to initialize user data.

Setup the rendering environment.

Parameters

[in,out]	opaque	private pointer passed to the libvlc_video_set_output_callbacks() on input. The callback can change this value on output to be passed to all the other callbacks set on libvlc_video_set_output_callbacks().
[in]	cfg	requested configuration of the video device
[out]	out	libvlc_video_setup_device_info_t* to fill

Returns

true on success

Version

LibVLC 4.0.0 or later

For libvlc_video_engine_d3d9 the output must be a IDirect3D9*. A reference to this object is held until the libvlc_video_output_cleanup_cb is called. the device must be created with D3DPRESENT_PARAMETERS.hDeviceWindow set to 0.

For libvlc_video_engine_d3d11 the output must be a ID3D11DeviceContext*. A reference to this object is held until the libvlc_video_output_cleanup_cb is called. The ID3D11Device used to create ID3D11DeviceContext must have multithreading enabled.

If the ID3D11DeviceContext is used outside of the callbacks called by libvlc, the host MUST use a mutex to protect the access to the ID3D11DeviceContext of libvlc. This mutex value is set on d3d11.context_mutex. If the ID3D11DeviceContext is not used outside of the callbacks, the mutex d3d11.context_mutex may be NULL.

libvlc_video_render_cfg_t

typedef struct libvlc_video_render_cfg_t libvlc_video_render_cfg_t

libvlc_video_setup_device_cfg_t

typedef struct libvlc_video_setup_device_cfg_t libvlc_video_setup_device_cfg_t

libvlc_video_setup_device_info_t

typedef struct libvlc_video_setup_device_info_t libvlc_video_setup_device_info_t

libvlc_video_swap_cb

typedef void(* libvlc_video_swap_cb) (void *opaque)

Callback prototype called after performing drawing calls.

This callback is called outside of libvlc_video_makeCurrent_cb current/not-current calls.

Parameters

[in]

opaque

private pointer set on the opaque parameter of libvlc_video_output_setup_cb()

Version

LibVLC 4.0.0 or later

libvlc_video_transfer_func_t

typedef enum libvlc_video_transfer_func_t libvlc_video_transfer_func_t

Enumeration of the Video transfer functions.

libvlc_video_unlock_cb

typedef void(* libvlc_video_unlock_cb) (void *opaque, void *picture, void *const *planes)

Callback prototype to unlock a picture buffer.

When the video frame decoding is complete, the unlock callback is invoked. This callback might not be needed at all. It is only an indication that the application can now read the pixel values if it needs to.

Note

A picture buffer is unlocked after the picture is decoded, but before the picture is displayed.

Parameters

[in]	opaque	private pointer as passed to libvlc_video_set_callbacks()
[in]	picture	private pointer returned from the libvlc_video_lock_cb callback
[in]	planes	pixel planes as defined by the libvlc_video_lock_cb callback (this parameter is only for convenience)

libvlc_video_update_output_cb

typedef bool(* libvlc_video_update_output_cb) (void *opaque, const libvlc_video_render_cfg_t *cfg, libvlc_video_output_cfg_t *output)

Callback prototype called on video size changes.

Update the rendering output setup.

Parameters

[in]	opaque	private pointer set on the opaque parameter of libvlc_video_output_setup_cb()
[in]	cfg	configuration of the video that will be rendered
[out]	output	configuration describing with how the rendering is setup

Version

LibVLC 4.0.0 or later

Note

the configuration device for Direct3D9 is the IDirect3DDevice9 that VLC uses to render. The host must set a Render target and call Present() when it needs the drawing from VLC to be done. This object is not valid anymore after Cleanup is called.

Tone mapping, range and color conversion will be done depending on the values set in the output structure.

Enumeration Type Documentation

anonymous enum

anonymous enum

Description for titles.

Enumerator
libvlc_title_menu
libvlc_title_interactive

libvlc_abloop_t

enum libvlc_abloop_t

A to B loop state.

Enumerator
libvlc_abloop_none
libvlc_abloop_a
libvlc_abloop_b

libvlc_navigate_mode_t

enum libvlc_navigate_mode_t

Navigation mode.

Enumerator
libvlc_navigate_activate
libvlc_navigate_up
libvlc_navigate_down
libvlc_navigate_left
libvlc_navigate_right
libvlc_navigate_popup

libvlc_position_t

enum libvlc_position_t

Enumeration of values used to set position (e.g.

of video title).

Enumerator
libvlc_position_disable
libvlc_position_center
libvlc_position_left
libvlc_position_right
libvlc_position_top
libvlc_position_top_left
libvlc_position_top_right
libvlc_position_bottom
libvlc_position_bottom_left
libvlc_position_bottom_right

libvlc_teletext_key_t

enum libvlc_teletext_key_t

Enumeration of teletext keys than can be passed via libvlc_video_set_teletext()

Enumerator
libvlc_teletext_key_red
libvlc_teletext_key_green
libvlc_teletext_key_yellow
libvlc_teletext_key_blue
libvlc_teletext_key_index

libvlc_video_color_primaries_t

enum libvlc_video_color_primaries_t

Enumeration of the Video color primaries.

Enumerator
libvlc_video_primaries_BT601_525
libvlc_video_primaries_BT601_625
libvlc_video_primaries_BT709
libvlc_video_primaries_BT2020
libvlc_video_primaries_DCI_P3
libvlc_video_primaries_BT470_M

libvlc_video_color_space_t

enum libvlc_video_color_space_t

Enumeration of the Video color spaces.

Enumerator
libvlc_video_colorspace_BT601
libvlc_video_colorspace_BT709
libvlc_video_colorspace_BT2020

libvlc_video_engine_t

enum libvlc_video_engine_t

Enumeration of the Video engine to be used on output.

can be passed to libvlc_video_set_output_callbacks

Enumerator
libvlc_video_engine_disable	Disable rendering engine.
libvlc_video_engine_opengl
libvlc_video_engine_gles2
libvlc_video_engine_d3d11	Direct3D11 rendering engine.
libvlc_video_engine_d3d9	Direct3D9 rendering engine.

libvlc_video_fit_mode_t

enum libvlc_video_fit_mode_t

Enumeration of values used to set the video fitting inside the display area.

Enumerator
libvlc_video_fit_none	Explicit zoom set by libvlc_video_set_scale.
libvlc_video_fit_smaller	Fit inside / to smallest display dimension.
libvlc_video_fit_larger	Fit outside / to largest display dimension.
libvlc_video_fit_width	Fit to display width.
libvlc_video_fit_height	Fit to display height.

libvlc_video_marquee_option_t

enum libvlc_video_marquee_option_t

Marq options definition.

Enumerator
libvlc_marquee_Enable
libvlc_marquee_Text
libvlc_marquee_Color	string argument
libvlc_marquee_Opacity
libvlc_marquee_Position
libvlc_marquee_Refresh
libvlc_marquee_Size
libvlc_marquee_Timeout
libvlc_marquee_X
libvlc_marquee_Y

libvlc_video_metadata_type_t

enum libvlc_video_metadata_type_t

Enumerator
libvlc_video_metadata_frame_hdr10	libvlc_video_frame_hdr10_metadata_t

libvlc_video_output_mouse_button_t

enum libvlc_video_output_mouse_button_t

Enumeration of the different mouse buttons that can be reported for user interaction can be passed to libvlc_video_output_mouse_press_cb and libvlc_video_output_mouse_release_cb.

Enumerator
libvlc_video_output_mouse_button_left
libvlc_video_output_mouse_button_middle
libvlc_video_output_mouse_button_right

libvlc_video_transfer_func_t

enum libvlc_video_transfer_func_t

Enumeration of the Video transfer functions.

Enumerator
libvlc_video_transfer_func_LINEAR
libvlc_video_transfer_func_SRGB
libvlc_video_transfer_func_BT470_BG
libvlc_video_transfer_func_BT470_M
libvlc_video_transfer_func_BT709
libvlc_video_transfer_func_PQ
libvlc_video_transfer_func_SMPTE_240
libvlc_video_transfer_func_HLG

Function Documentation

libvlc_audio_set_callbacks()

LIBVLC_API void libvlc_audio_set_callbacks	(	libvlc_media_player_t *	mp,
		libvlc_audio_play_cb	play,
		libvlc_audio_pause_cb	pause,
		libvlc_audio_resume_cb	resume,
		libvlc_audio_flush_cb	flush,
		libvlc_audio_drain_cb	drain,
		void *	opaque
	)

Sets callbacks and private data for decoded audio.

Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() to configure the decoded audio format.

Note

The audio callbacks override any other audio output mechanism. If the callbacks are set, LibVLC will not output audio in any way.

Parameters

mp	the media player
play	callback to play audio samples (must not be NULL)
pause	callback to pause playback (or NULL to ignore)
resume	callback to resume playback (or NULL to ignore)
flush	callback to flush audio buffers (or NULL to ignore)
drain	callback to drain audio buffers (or NULL to ignore)
opaque	private pointer for the audio callbacks (as first parameter)

Version

LibVLC 2.0.0 or later

libvlc_audio_set_format()

LIBVLC_API void libvlc_audio_set_format	(	libvlc_media_player_t *	mp,
		const char *	format,
		unsigned	rate,
		unsigned	channels
	)

Sets a fixed decoded audio format.

This only works in combination with libvlc_audio_set_callbacks(), and is mutually exclusive with libvlc_audio_set_format_callbacks().

The supported formats are:

• "S16N" for signed 16-bit PCM
• "S32N" for signed 32-bit PCM
• "FL32" for single precision IEEE 754

All supported formats use the native endianness. If there are more than one channel, samples are interleaved.

Parameters

mp	the media player
format	a four-characters string identifying the sample format
rate	sample rate (expressed in Hz)
channels	channels count

Version

LibVLC 2.0.0 or later

libvlc_audio_set_format_callbacks()

LIBVLC_API void libvlc_audio_set_format_callbacks	(	libvlc_media_player_t *	mp,
		libvlc_audio_setup_cb	setup,
		libvlc_audio_cleanup_cb	cleanup
	)

Sets decoded audio format via callbacks.

This only works in combination with libvlc_audio_set_callbacks().

Parameters

mp	the media player
setup	callback to select the audio format (cannot be NULL)
cleanup	callback to release any allocated resources (or NULL)

Version

LibVLC 2.0.0 or later

libvlc_audio_set_volume_callback()

LIBVLC_API void libvlc_audio_set_volume_callback	(	libvlc_media_player_t *	mp,
		libvlc_audio_set_volume_cb	set_volume
	)

Set callbacks and private data for decoded audio.

This only works in combination with libvlc_audio_set_callbacks(). Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() to configure the decoded audio format.

Parameters

mp	the media player
set_volume	callback to apply audio volume, or NULL to apply volume in software

Version

LibVLC 2.0.0 or later

libvlc_media_player_add_slave()

LIBVLC_API int libvlc_media_player_add_slave	(	libvlc_media_player_t *	p_mi,
		libvlc_media_slave_type_t	i_type,
		const char *	psz_uri,
		bool	b_select
	)

Add a slave to the current media player.

Note

If the player is playing, the slave will be added directly. This call will also update the slave list of the attached libvlc_media_t.

Version

LibVLC 3.0.0 and later.

See also

libvlc_media_slaves_add

Parameters

p_mi	the media player
i_type	subtitle or audio
psz_uri	Uri of the slave (should contain a valid scheme).
b_select	True if this slave should be selected when it's loaded

Returns

0 on success, -1 on error.

libvlc_media_player_can_pause()

LIBVLC_API bool libvlc_media_player_can_pause

(

libvlc_media_player_t *

p_mi

)

Can this media player be paused?

Parameters

p_mi	the media player

Return values

true	media player can be paused
false	media player cannot be paused

libvlc_media_player_event_manager()

LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager

(

libvlc_media_player_t *

p_mi

)

Get the Event Manager from which the media player send event.

Parameters

p_mi	the Media Player

Returns

the event manager associated with p_mi

libvlc_media_player_get_abloop()

LIBVLC_API libvlc_abloop_t libvlc_media_player_get_abloop	(	libvlc_media_player_t *	p_mi,
		libvlc_time_t *	a_time,
		double *	a_pos,
		libvlc_time_t *	b_time,
		double *	b_pos
	)

Get the A to B loop status.

Note

If the returned status is VLC_PLAYER_ABLOOP_A, then a_time and a_pos will be valid. If the returned status is VLC_PLAYER_ABLOOP_B, then all output parameters are valid. If the returned status is VLC_PLAYER_ABLOOP_NONE, then all output parameters are invalid.

See also

vlc_player_cbs.on_atobloop_changed

Parameters

p_mi	the Media Player
a_time	A time (in ms) or -1 (if the media doesn't have valid times)
a_pos	A position
b_time	B time (in ms) or -1 (if the media doesn't have valid times)
b_pos	B position

Returns

A to B loop status

Version

LibVLC 4.0.0 and later.

libvlc_media_player_get_chapter()

LIBVLC_API int libvlc_media_player_get_chapter

(

libvlc_media_player_t *

p_mi

)

Get movie chapter.

Parameters

p_mi	the Media Player

Returns

chapter number currently playing, or -1 if there is no media.

libvlc_media_player_get_chapter_count()

LIBVLC_API int libvlc_media_player_get_chapter_count

(

libvlc_media_player_t *

p_mi

)

Get movie chapter count.

Parameters

p_mi	the Media Player

Returns

number of chapters in movie, or -1.

libvlc_media_player_get_chapter_count_for_title()

LIBVLC_API int libvlc_media_player_get_chapter_count_for_title	(	libvlc_media_player_t *	p_mi,
		int	i_title
	)

Get title chapter count.

Parameters

p_mi	the Media Player
i_title	title

Returns

number of chapters in title, or -1

libvlc_media_player_get_hwnd()

LIBVLC_API void * libvlc_media_player_get_hwnd

(

libvlc_media_player_t *

p_mi

)

Get the Windows API window handle (HWND) previously set with libvlc_media_player_set_hwnd().

The handle will be returned even if LibVLC is not currently outputting any video to it.

Parameters

p_mi	the Media Player

Returns

a window handle or NULL if there are none.

libvlc_media_player_get_length()

LIBVLC_API libvlc_time_t libvlc_media_player_get_length

(

libvlc_media_player_t *

p_mi

)

Get the current movie length (in ms).

Bug:

This might go away ... to be replaced by a broader system

Parameters

p_mi	the Media Player

Returns

the movie length (in ms), or -1 if there is no media.

libvlc_media_player_get_media()

LIBVLC_API libvlc_media_t * libvlc_media_player_get_media

(

libvlc_media_player_t *

p_mi

)

Get the media used by the media_player.

Warning

Calling this function just after libvlc_media_player_set_media() will return the media that was just set, but this media might not be currently used internally by the player. To detect such case, the user should listen to the libvlc_MediaPlayerMediaChanged event.

Parameters

p_mi	the Media Player

Returns

the media associated with p_mi, or NULL if no media is associated

libvlc_media_player_get_nsobject()

LIBVLC_API void * libvlc_media_player_get_nsobject

(

libvlc_media_player_t *

p_mi

)

Get the NSView handler previously set with libvlc_media_player_set_nsobject().

Parameters

p_mi	the Media Player

Returns

the NSView handler or 0 if none where set

libvlc_media_player_get_position()

LIBVLC_API double libvlc_media_player_get_position

(

libvlc_media_player_t *

p_mi

)

Get movie position as percentage between 0.0 and 1.0.

Parameters

p_mi	the Media Player

Returns

movie position, or -1. in case of error

libvlc_media_player_get_program_from_id()

LIBVLC_API libvlc_player_program_t * libvlc_media_player_get_program_from_id	(	libvlc_media_player_t *	p_mi,
		int	i_group_id
	)

Get a program struct from a program id.

Version

LibVLC 4.0.0 or later

Parameters

p_mi	opaque media player handle
i_group_id	program id

Returns

a valid program struct or NULL if the i_group_id is not found. The program need to be freed with libvlc_player_program_delete().

libvlc_media_player_get_programlist()

LIBVLC_API libvlc_player_programlist_t * libvlc_media_player_get_programlist

(

libvlc_media_player_t *

p_mi

)

Get the program list.

Version

LibVLC 4.0.0 and later.

Note

This program list is a snapshot of the current programs when this function is called. If a program is updated after this call, the user will need to call this function again to get the updated program.

The program list can be used to get program information and to select specific programs.

Parameters

p_mi	the media player

Returns

a valid libvlc_media_programlist_t or NULL in case of error or empty list, delete with libvlc_media_programlist_delete()

libvlc_media_player_get_rate()

LIBVLC_API float libvlc_media_player_get_rate

(

libvlc_media_player_t *

p_mi

)

Get the requested movie play rate.

Warning

Depending on the underlying media, the requested rate may be different from the real playback rate.

Parameters

p_mi	the Media Player

Returns

movie play rate

libvlc_media_player_get_selected_program()

LIBVLC_API libvlc_player_program_t * libvlc_media_player_get_selected_program

(

libvlc_media_player_t *

p_mi

)

Get the selected program.

Version

LibVLC 4.0.0 or later

Parameters

p_mi	opaque media player handle

Returns

a valid program struct or NULL if no programs are selected. The program need to be freed with libvlc_player_program_delete().

libvlc_media_player_get_selected_track()

LIBVLC_API libvlc_media_track_t * libvlc_media_player_get_selected_track	(	libvlc_media_player_t *	p_mi,
		libvlc_track_type_t	type
	)

Get the selected track for one type.

Version

LibVLC 4.0.0 and later.

Warning

More than one tracks can be selected for one type. In that case, libvlc_media_player_get_tracklist() should be used.

Parameters

p_mi	the media player
type	type of the selected track

Returns

a valid track or NULL if there is no selected tracks for this type, release it with libvlc_media_track_release().

libvlc_media_player_get_state()

LIBVLC_API libvlc_state_t libvlc_media_player_get_state

(

libvlc_media_player_t *

p_mi

)

Get current movie state.

Parameters

p_mi	the Media Player

Returns

the current state of the media player (playing, paused, ...)

See also

libvlc_state_t

libvlc_media_player_get_time()

LIBVLC_API libvlc_time_t libvlc_media_player_get_time

(

libvlc_media_player_t *

p_mi

)

Get the current movie time (in ms).

Parameters

p_mi	the Media Player

Returns

the movie time (in ms), or -1 if there is no media.

libvlc_media_player_get_title()

LIBVLC_API int libvlc_media_player_get_title

(

libvlc_media_player_t *

p_mi

)

Get movie title.

Parameters

p_mi	the Media Player

Returns

title number currently playing, or -1

libvlc_media_player_get_title_count()

LIBVLC_API int libvlc_media_player_get_title_count

(

libvlc_media_player_t *

p_mi

)

Get movie title count.

Parameters

p_mi	the Media Player

Returns

title number count, or -1

libvlc_media_player_get_track_from_id()

LIBVLC_API libvlc_media_track_t * libvlc_media_player_get_track_from_id	(	libvlc_media_player_t *	p_mi,
		const char *	psz_id
	)

libvlc_media_player_get_tracklist()

LIBVLC_API libvlc_media_tracklist_t * libvlc_media_player_get_tracklist	(	libvlc_media_player_t *	p_mi,
		libvlc_track_type_t	type,
		bool	selected
	)

Get the track list for one type.

Version

LibVLC 4.0.0 and later.

Note

You need to call libvlc_media_parse_request() or play the media at least once before calling this function. Not doing this will result in an empty list.

This track list is a snapshot of the current tracks when this function is called. If a track is updated after this call, the user will need to call this function again to get the updated track.

The track list can be used to get track information and to select specific tracks.

Parameters

p_mi	the media player
type	type of the track list to request
selected	filter only selected tracks if true (return all tracks, even selected ones if false)

Returns

a valid libvlc_media_tracklist_t or NULL in case of error, if there is no track for a category, the returned list will have a size of 0, delete with libvlc_media_tracklist_delete()

libvlc_media_player_get_xwindow()

LIBVLC_API uint32_t libvlc_media_player_get_xwindow

(

libvlc_media_player_t *

p_mi

)

Get the X Window System window identifier previously set with libvlc_media_player_set_xwindow().

Note that this will return the identifier even if VLC is not currently using it (for instance if it is playing an audio-only input).

Parameters

p_mi	the Media Player

Returns

an X window ID, or 0 if none where set.

libvlc_media_player_has_vout()

LIBVLC_API unsigned libvlc_media_player_has_vout

(

libvlc_media_player_t *

p_mi

)

How many video outputs does this media player have?

Parameters

p_mi	the media player

Returns

the number of video outputs

libvlc_media_player_is_playing()

LIBVLC_API bool libvlc_media_player_is_playing

(

libvlc_media_player_t *

p_mi

)

is_playing

Parameters

p_mi	the Media Player

Return values

true	media player is playing
false	media player is not playing

libvlc_media_player_is_seekable()

LIBVLC_API bool libvlc_media_player_is_seekable

(

libvlc_media_player_t *

p_mi

)

Is this media player seekable?

Parameters

p_mi	the media player

Return values

true	media player can seek
false	media player cannot seek

libvlc_media_player_jump_time()

LIBVLC_API int libvlc_media_player_jump_time	(	libvlc_media_player_t *	p_mi,
		libvlc_time_t	i_time
	)

Jump the movie time (in ms).

This will trigger a precise and relative seek (from the current time). This has no effect if no media is being played. Not all formats and protocols support this.

Parameters

p_mi	the Media Player
i_time	the movie time (in ms).

Returns

0 on success, -1 on error

Version

LibVLC 4.0.0 and later.

libvlc_media_player_navigate()

LIBVLC_API void libvlc_media_player_navigate	(	libvlc_media_player_t *	p_mi,
		unsigned	navigate
	)

Navigate through DVD Menu.

Parameters

p_mi	the Media Player
navigate	the Navigation mode

Version

libVLC 2.0.0 or later

libvlc_media_player_new()

LIBVLC_API libvlc_media_player_t * libvlc_media_player_new

(

libvlc_instance_t *

p_libvlc_instance

)

Create an empty Media Player object.

Parameters

p_libvlc_instance

the libvlc instance in which the Media Player should be created.

Returns

a new media player object, or NULL on error. It must be released by libvlc_media_player_release().

libvlc_media_player_new_from_media()

LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media	(	libvlc_instance_t *	inst,
		libvlc_media_t *	p_md
	)

Create a Media Player object from a Media.

Parameters

inst	LibVLC instance to create a media player with
p_md	the media. Afterwards the p_md can be safely destroyed.

Returns

a new media player object, or NULL on error. It must be released by libvlc_media_player_release().

libvlc_media_player_next_chapter()

LIBVLC_API void libvlc_media_player_next_chapter

(

libvlc_media_player_t *

p_mi

)

Set next chapter (if applicable)

Parameters

p_mi	the Media Player

libvlc_media_player_next_frame()

LIBVLC_API void libvlc_media_player_next_frame

(

libvlc_media_player_t *

p_mi

)

Display the next frame (if supported)

Parameters

p_mi	the media player

libvlc_media_player_pause()

LIBVLC_API void libvlc_media_player_pause

(

libvlc_media_player_t *

p_mi

)

Toggle pause (no effect if there is no media)

Parameters

p_mi	the Media Player

libvlc_media_player_play()

LIBVLC_API int libvlc_media_player_play

(

libvlc_media_player_t *

p_mi

)

Play.

Parameters

p_mi	the Media Player

Returns

0 if playback started (and was already started), or -1 on error.

libvlc_media_player_previous_chapter()

LIBVLC_API void libvlc_media_player_previous_chapter

(

libvlc_media_player_t *

p_mi

)

Set previous chapter (if applicable)

Parameters

p_mi	the Media Player

libvlc_media_player_program_scrambled()

LIBVLC_API bool libvlc_media_player_program_scrambled

(

libvlc_media_player_t *

p_mi

)

Check if the current program is scrambled.

Parameters

p_mi	the media player

Return values

true	current program is scrambled
false	current program is not scrambled

Version

LibVLC 2.2.0 or later

libvlc_media_player_release()

LIBVLC_API void libvlc_media_player_release

(

libvlc_media_player_t *

p_mi

)

Release a media_player after use Decrement the reference count of a media player object.

If the reference count is 0, then libvlc_media_player_release() will release the media player object. If the media player object has been released, then it should not be used again.

Parameters

p_mi	the Media Player to free

libvlc_media_player_retain()

LIBVLC_API libvlc_media_player_t * libvlc_media_player_retain

(

libvlc_media_player_t *

p_mi

)

Retain a reference to a media player object.

Use libvlc_media_player_release() to decrement reference count.

Parameters

p_mi	media player object

Returns

the same object

libvlc_media_player_select_program_id()

LIBVLC_API void libvlc_media_player_select_program_id	(	libvlc_media_player_t *	p_mi,
		int	i_group_id
	)

Select program with a given program id.

Note

program ids are sent via the libvlc_MediaPlayerProgramAdded event or can be fetch via libvlc_media_player_get_programlist()

Version

LibVLC 4.0.0 or later

Parameters

p_mi	opaque media player handle
i_group_id	program id

libvlc_media_player_select_track()

LIBVLC_API void libvlc_media_player_select_track	(	libvlc_media_player_t *	p_mi,
		const libvlc_media_track_t *	track
	)

Select a track.

This will unselected the current track.

Version

LibVLC 4.0.0 and later.

Note

Use libvlc_media_player_select_tracks() for multiple selection

Warning

Only use a libvlc_media_track_t retrieved with libvlc_media_player_get_tracklist

Parameters

p_mi	the media player
track	track to select, can't be NULL

libvlc_media_player_select_tracks()

LIBVLC_API void libvlc_media_player_select_tracks	(	libvlc_media_player_t *	p_mi,
		libvlc_track_type_t	type,
		const libvlc_media_track_t **	tracks,
		size_t	track_count
	)

Select multiple tracks for one type.

Version

LibVLC 4.0.0 and later.

Note

The internal track list can change between the calls of libvlc_media_player_get_tracklist() and libvlc_media_player_set_tracks(). If a track selection change but the track is not present anymore, the player will just ignore it.

selecting multiple audio tracks is currently not supported.

Warning

Only use a libvlc_media_track_t retrieved with libvlc_media_player_get_tracklist

Parameters

p_mi	the media player
type	type of the selected track
tracks	pointer to the track array, or NULL if track_count is 0
track_count	number of tracks in the track array

libvlc_media_player_select_tracks_by_ids()

LIBVLC_API void libvlc_media_player_select_tracks_by_ids	(	libvlc_media_player_t *	p_mi,
		libvlc_track_type_t	type,
		const char *	psz_ids
	)

Select tracks by their string identifier.

Version

LibVLC 4.0.0 and later.

This function can be used pre-select a list of tracks before starting the player. It has only effect for the current media. It can also be used when the player is already started.

'str_ids' can contain more than one track id, delimited with ','. "" or any invalid track id will cause the player to unselect all tracks of that category. NULL will disable the preference for newer tracks without unselecting any current tracks.

Example:

• (libvlc_track_video, "video/1,video/2") will select these 2 video tracks. If there is only one video track with the id "video/0", no tracks will be selected.
• (libvlc_track_type_t, "${slave_url_md5sum}/spu/0) will select one spu added by an input slave with the corresponding url.

Note

The string identifier of a track can be found via psz_id from libvlc_media_track_t

selecting multiple audio tracks is currently not supported.

Warning

Only use a libvlc_media_track_t id retrieved with libvlc_media_player_get_tracklist

Parameters

p_mi	the media player
type	type to select
psz_ids	list of string identifier or NULL

libvlc_media_player_set_abloop()

LIBVLC_API int libvlc_media_player_set_abloop	(	libvlc_media_player_t *	p_mi,
		libvlc_abloop_t	abloop
	)

Enable A to B loop for the current media.

This function need to be called 2 times with libvlc_abloop_a and libvlc_abloop_b to setup an A to B loop. It uses and stores the current time/position when called. The B time must be higher than the A time.

Parameters

p_mi	the Media Player
abloop	select which A/B cursor to set

Returns

0 on success, -1 on error

Version

LibVLC 4.0.0 and later.

libvlc_media_player_set_android_context()

LIBVLC_API void libvlc_media_player_set_android_context	(	libvlc_media_player_t *	p_mi,
		void *	p_awindow_handler
	)

Set the android context.

Version

LibVLC 3.0.0 and later.

Parameters

p_mi	the media player
p_awindow_handler	org.videolan.libvlc.AWindow jobject owned by the org.videolan.libvlc.MediaPlayer class from the libvlc-android project.

libvlc_media_player_set_chapter()

LIBVLC_API void libvlc_media_player_set_chapter	(	libvlc_media_player_t *	p_mi,
		int	i_chapter
	)

Set movie chapter (if applicable).

Parameters

p_mi	the Media Player
i_chapter	chapter number to play

libvlc_media_player_set_hwnd()

LIBVLC_API void libvlc_media_player_set_hwnd	(	libvlc_media_player_t *	p_mi,
		void *	drawable
	)

Set a Win32/Win64 API window handle (HWND) where the media player should render its video output.

If LibVLC was built without Win32/Win64 API output support, then this has no effects.

Warning

the HWND must have the WS_CLIPCHILDREN set in its style.

Parameters

p_mi	the Media Player
drawable	windows handle of the drawable

libvlc_media_player_set_media()

LIBVLC_API void libvlc_media_player_set_media	(	libvlc_media_player_t *	p_mi,
		libvlc_media_t *	p_md
	)

Set the media that will be used by the media_player.

If any, previous md will be released.

Note

The user should listen to the libvlc_MediaPlayerMediaChanged event, to know when the new media is actually used by the player (or to known that the older media is no longer used).

Parameters

p_mi	the Media Player
p_md	the Media. Afterwards the p_md can be safely destroyed.

libvlc_media_player_set_nsobject()

LIBVLC_API void libvlc_media_player_set_nsobject	(	libvlc_media_player_t *	p_mi,
		void *	drawable
	)

Set the handler where the media player should display its video output.

The drawable is an NSObject that require responding to two selectors like in this protocol:

@protocol VLCDrawable <NSObject>
- (void)addSubview:(VLCView *)view;
- (CGRect)bounds;
@end

In this protocol VLCView type can either be a UIView or a NSView type class. VLCDrawable protocol conformance isn't mandatory but a drawable must respond to both addSubview: and bounds selectors.

Additionally, a drawable can also conform to the VLCPictureInPictureDrawable protocol to allow picture in picture support :

@protocol VLCPictureInPictureMediaControlling <NSObject>
- (void)play;
- (void)pause;
- (void)seekBy:(int64_t)offset;
- (int64_t)mediaLength;
- (int64_t)mediaTime;
- (BOOL)isMediaPlaying;
@end
 
@protocol VLCPictureInPictureWindowControlling <NSObject>
- (void)startPictureInPicture;
- (void)stopPictureInPicture;
- (void)invalidatePlaybackState;
@end
 
@protocol VLCPictureInPictureDrawable <NSObject>
- (id<VLCPictureInPictureMediaControlling>) mediaController;
- (void (^)(id<VLCPictureInPictureWindowControlling>)) pictureInPictureReady;
@end

Be aware that full VLCPictureInPictureDrawable conformance is mandatory to enable picture in picture support and that time values in VLCPictureInPictureMediaControlling methods are expressed in milliseconds.

If you want to use it along with Qt see the QMacCocoaViewContainer. Then the following code should work:

{
    NSView *video = [[NSView alloc] init];
    QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
    libvlc_media_player_set_nsobject(mp, video);
    [video release];
}

You can find a live example in VLCVideoView in VLCKit.framework.

Parameters

p_mi	the Media Player
drawable	the drawable that is either an NSView, a UIView or any NSObject responding to addSubview: and bounds selectors

libvlc_media_player_set_pause()

LIBVLC_API void libvlc_media_player_set_pause	(	libvlc_media_player_t *	mp,
		int	do_pause
	)

Pause or resume (no effect if there is no media)

Parameters

mp	the Media Player
do_pause	play/resume if zero, pause if non-zero

Version

LibVLC 1.1.1 or later

libvlc_media_player_set_position()

LIBVLC_API int libvlc_media_player_set_position	(	libvlc_media_player_t *	p_mi,
		double	f_pos,
		bool	b_fast
	)

Set movie position as percentage between 0.0 and 1.0.

This has no effect if playback is not enabled. This might not work depending on the underlying input format and protocol.

Parameters

p_mi	the Media Player
b_fast	prefer fast seeking or precise seeking
f_pos	the position

Returns

0 on success, -1 on error

libvlc_media_player_set_rate()

LIBVLC_API int libvlc_media_player_set_rate	(	libvlc_media_player_t *	p_mi,
		float	rate
	)

Set movie play rate.

Parameters

p_mi	the Media Player
rate	movie play rate to set

Returns

-1 if an error was detected, 0 otherwise (but even then, it might not actually work depending on the underlying media protocol)

libvlc_media_player_set_renderer()

LIBVLC_API int libvlc_media_player_set_renderer	(	libvlc_media_player_t *	p_mi,
		libvlc_renderer_item_t *	p_item
	)

Set a renderer to the media player.

Note

must be called before the first call of libvlc_media_player_play() to take effect.

See also

libvlc_renderer_discoverer_new

Parameters

p_mi	the Media Player
p_item	an item discovered by libvlc_renderer_discoverer_start()

Returns

0 on success, -1 on error.

Version

LibVLC 3.0.0 or later

libvlc_media_player_set_time()

LIBVLC_API int libvlc_media_player_set_time	(	libvlc_media_player_t *	p_mi,
		libvlc_time_t	i_time,
		bool	b_fast
	)

Set the movie time (in ms).

This has no effect if no media is being played. Not all formats and protocols support this.

Parameters

p_mi	the Media Player
i_time	the movie time (in ms).
b_fast	prefer fast seeking or precise seeking

Returns

0 on success, -1 on error

libvlc_media_player_set_title()

LIBVLC_API void libvlc_media_player_set_title	(	libvlc_media_player_t *	p_mi,
		int	i_title
	)

Set movie title.

Parameters

p_mi	the Media Player
i_title	title number to play

libvlc_media_player_set_video_title_display()

LIBVLC_API void libvlc_media_player_set_video_title_display	(	libvlc_media_player_t *	p_mi,
		libvlc_position_t	position,
		unsigned int	timeout
	)

Set if, and how, the video title will be shown when media is played.

Parameters

p_mi	the media player
position	position at which to display the title, or libvlc_position_disable to prevent the title from being displayed
timeout	title display timeout in milliseconds (ignored if libvlc_position_disable)

Version

libVLC 2.1.0 or later

libvlc_media_player_set_xwindow()

LIBVLC_API void libvlc_media_player_set_xwindow	(	libvlc_media_player_t *	p_mi,
		uint32_t	drawable
	)

Set an X Window System drawable where the media player should render its video output.

The call takes effect when the playback starts. If it is already started, it might need to be stopped before changes apply. If LibVLC was built without X11 output support, then this function has no effects.

By default, LibVLC will capture input events on the video rendering area. Use libvlc_video_set_mouse_input() and libvlc_video_set_key_input() to disable that and deliver events to the parent window / to the application instead. By design, the X11 protocol delivers input events to only one recipient.

Warning

The application must call the XInitThreads() function from Xlib before libvlc_new(), and before any call to XOpenDisplay() directly or via any other library. Failure to call XInitThreads() will seriously impede LibVLC performance. Calling XOpenDisplay() before XInitThreads() will eventually crash the process. That is a limitation of Xlib.

Parameters

p_mi	media player
drawable	X11 window ID

Note

The specified identifier must correspond to an existing Input/Output class X11 window. Pixmaps are not currently supported. The default X11 server is assumed, i.e. that specified in the DISPLAY environment variable.

Warning

LibVLC can deal with invalid X11 handle errors, however some display drivers (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle must remain valid until playback is stopped, otherwise the process may abort or crash.

Bug:

No more than one window handle per media player instance can be specified. If the media has multiple simultaneously active video tracks, extra tracks will be rendered into external windows beyond the control of the application.

libvlc_media_player_stop_async()

LIBVLC_API int libvlc_media_player_stop_async

(

libvlc_media_player_t *

p_mi

)

Stop asynchronously.

Note

This function is asynchronous. In case of success, the user should wait for the libvlc_MediaPlayerStopped event to know when the stop is finished.

Parameters

p_mi	the Media Player

Returns

0 if the player is being stopped, -1 otherwise (no-op)

Version

LibVLC 4.0.0 or later

libvlc_media_player_unselect_track_type()

LIBVLC_API void libvlc_media_player_unselect_track_type	(	libvlc_media_player_t *	p_mi,
		libvlc_track_type_t	type
	)

Unselect all tracks for a given type.

Version

LibVLC 4.0.0 and later.

Parameters

p_mi	the media player
type	type to unselect

libvlc_player_program_delete()

LIBVLC_API void libvlc_player_program_delete

(

libvlc_player_program_t *

program

)

Delete a program struct.

Version

LibVLC 4.0.0 and later.

Parameters

program

returned by libvlc_media_player_get_selected_program() or libvlc_media_player_get_program_from_id()

libvlc_player_programlist_at()

LIBVLC_API libvlc_player_program_t * libvlc_player_programlist_at	(	libvlc_player_programlist_t *	list,
		size_t	index
	)

Get a program at a specific index.

Warning

The behaviour is undefined if the index is not valid.

Version

LibVLC 4.0.0 and later.

Parameters

list	valid programlist
index	valid index in the range [0; count[

Returns

a valid program (can't be NULL if libvlc_player_programlist_count() returned a valid count)

libvlc_player_programlist_count()

LIBVLC_API size_t libvlc_player_programlist_count

(

const libvlc_player_programlist_t *

list

)

Get the number of programs in a programlist.

Version

LibVLC 4.0.0 and later.

Parameters

list	valid programlist

Returns

number of programs, or 0 if the list is empty

libvlc_player_programlist_delete()

LIBVLC_API void libvlc_player_programlist_delete

(

libvlc_player_programlist_t *

list

)

Release a programlist.

Note

program structs from the list are also deleted.

Version

LibVLC 4.0.0 and later.

See also

libvlc_media_player_get_programlist

Parameters

list	valid programlist

libvlc_video_set_callbacks()

LIBVLC_API void libvlc_video_set_callbacks	(	libvlc_media_player_t *	mp,
		libvlc_video_lock_cb	lock,
		libvlc_video_unlock_cb	unlock,
		libvlc_video_display_cb	display,
		void *	opaque
	)

Set callbacks and private data to render decoded video to a custom area in memory.

Use libvlc_video_set_format() or libvlc_video_set_format_callbacks() to configure the decoded format.

Warning

Rendering video into custom memory buffers is considerably less efficient than rendering in a custom window as normal.

For optimal performances, VLC media player renders into a custom window, and does not use this function and associated callbacks. It is highly recommended that other LibVLC-based application do likewise. To embed video in a window, use libvlc_media_player_set_xwindow() or equivalent depending on the operating system.

If window embedding does not fit the application use case, then a custom LibVLC video output display plugin is required to maintain optimal video rendering performances.

The following limitations affect performance:

• Hardware video decoding acceleration will either be disabled completely, or require (relatively slow) copy from video/DSP memory to main memory.
• Sub-pictures (subtitles, on-screen display, etc.) must be blent into the main picture by the CPU instead of the GPU.
• Depending on the video format, pixel format conversion, picture scaling, cropping and/or picture re-orientation, must be performed by the CPU instead of the GPU.
• Memory copying is required between LibVLC reference picture buffers and application buffers (between lock and unlock callbacks).

Parameters

mp	the media player
lock	callback to lock video memory (must not be NULL)
unlock	callback to unlock video memory (or NULL if not needed)
display	callback to display video (or NULL if not needed)
opaque	private pointer for the three callbacks (as first parameter)

Version

LibVLC 1.1.1 or later

libvlc_video_set_format()

LIBVLC_API void libvlc_video_set_format	(	libvlc_media_player_t *	mp,
		const char *	chroma,
		unsigned	width,
		unsigned	height,
		unsigned	pitch
	)

Set decoded video chroma and dimensions.

This only works in combination with libvlc_video_set_callbacks(), and is mutually exclusive with libvlc_video_set_format_callbacks().

Parameters

mp	the media player
chroma	a four-characters string identifying the chroma (e.g. "RV32" or "YUYV")
width	pixel width
height	pixel height
pitch	line pitch (in bytes)

Version

LibVLC 1.1.1 or later

Bug:

All pixel planes are expected to have the same pitch. To use the YCbCr color space with chrominance subsampling, consider using libvlc_video_set_format_callbacks() instead.

libvlc_video_set_format_callbacks()

LIBVLC_API void libvlc_video_set_format_callbacks	(	libvlc_media_player_t *	mp,
		libvlc_video_format_cb	setup,
		libvlc_video_cleanup_cb	cleanup
	)

Set decoded video chroma and dimensions.

This only works in combination with libvlc_video_set_callbacks().

Parameters

mp	the media player
setup	callback to select the video format (cannot be NULL)
cleanup	callback to release any allocated resources (or NULL)

Version

LibVLC 2.0.0 or later

libvlc_video_set_output_callbacks()

LIBVLC_API bool libvlc_video_set_output_callbacks	(	libvlc_media_player_t *	mp,
		libvlc_video_engine_t	engine,
		libvlc_video_output_setup_cb	setup_cb,
		libvlc_video_output_cleanup_cb	cleanup_cb,
		libvlc_video_output_set_window_cb	window_cb,
		libvlc_video_update_output_cb	update_output_cb,
		libvlc_video_swap_cb	swap_cb,
		libvlc_video_makeCurrent_cb	makeCurrent_cb,
		libvlc_video_getProcAddress_cb	getProcAddress_cb,
		libvlc_video_frameMetadata_cb	metadata_cb,
		libvlc_video_output_select_plane_cb	select_plane_cb,
		void *	opaque
	)

Set callbacks and data to render decoded video to a custom texture.

Warning

VLC will perform video rendering in its own thread and at its own rate, You need to provide your own synchronisation mechanism.

Parameters

mp	the media player
engine	the GPU engine to use
setup_cb	callback called to initialize user data
cleanup_cb	callback called to clean up user data
window_cb	callback called to setup the window
update_output_cb	callback to get the rendering format of the host (cannot be NULL)
swap_cb	callback called after rendering a video frame (cannot be NULL)
makeCurrent_cb	callback called to enter/leave the rendering context (cannot be NULL)
getProcAddress_cb	opengl function loading callback (cannot be NULL for libvlc_video_engine_opengl and for libvlc_video_engine_gles2)
metadata_cb	callback to provide frame metadata (D3D11 only)
select_plane_cb	callback to select different D3D11 rendering targets
opaque	private pointer passed to callbacks

Note

the setup_cb and cleanup_cb may be called more than once per playback.

Return values

true	engine selected and callbacks set
false	engine type unknown, callbacks not set

Version

LibVLC 4.0.0 or later