LibVLC media player time watch API

Collaboration diagram for LibVLC media player time watch API:

Data Structures
struct	libvlc_media_player_time_point_t
	Media Player timer point. More...

Typedefs
typedef struct libvlc_media_player_time_point_t	libvlc_media_player_time_point_t
	Media Player timer point.
typedef void(*	libvlc_media_player_watch_time_on_update) (const libvlc_media_player_time_point_t *value, void *data)
	Callback prototype that notify when the player state or time changed.
typedef void(*	libvlc_media_player_watch_time_on_paused) (int64_t system_date_us, void *data)
	Callback prototype that notify when the timer is paused.
typedef void(*	libvlc_media_player_watch_time_on_seek) (const libvlc_media_player_time_point_t *value, void *data)
	Callback prototype that notify when the player is seeking or finished seeking.

Functions
LIBVLC_API int	libvlc_media_player_watch_time (libvlc_media_player_t *p_mi, int64_t min_period_us, libvlc_media_player_watch_time_on_update on_update, libvlc_media_player_watch_time_on_paused on_paused, libvlc_media_player_watch_time_on_seek on_seek, void *cbs_data)
	Watch for times updates.
LIBVLC_API void	libvlc_media_player_unwatch_time (libvlc_media_player_t *p_mi)
	Unwatch time updates.
LIBVLC_API int	libvlc_media_player_time_point_interpolate (const libvlc_media_player_time_point_t *point, int64_t system_now_us, int64_t *out_ts_us, double *out_pos)
	Interpolate a timer value to now.
LIBVLC_API int64_t	libvlc_media_player_time_point_get_next_date (const libvlc_media_player_time_point_t *point, int64_t system_now_us, int64_t interpolated_ts_us, int64_t next_interval_us)
	Get the date of the next interval.

Detailed Description

Typedef Documentation

libvlc_media_player_time_point_t

typedef struct libvlc_media_player_time_point_t libvlc_media_player_time_point_t

Media Player timer point.

Note

ts and system_date values should not be used directly by the user. libvlc_media_player_time_point_interpolate() will read these values and return an interpolated ts.

See also

libvlc_media_player_watch_time_on_update

libvlc_media_player_watch_time_on_paused

typedef void(* libvlc_media_player_watch_time_on_paused) (int64_t system_date_us, void *data)

Callback prototype that notify when the timer is paused.

This event is sent when the player is paused or stopping. The player user should stop its "interpolate" timer.

Note

libvlc_media_player_watch_time_on_update() can be called when paused for those 2 reasons:

• playback is resumed (libvlc_media_player_time_point_t.system_date is valid)
• a track, likely video (next-frame) is outputted when paused (libvlc_media_player_time_point_t.system_date = INT64_MAX)

Warning

It is forbidden to call any Media Player functions from here.

Parameters

system_date_us	system date, in us, of this event, only valid (> 0) when paused. It can be used to interpolate the last updated point to this date in order to get the last paused ts/position.
data	opaque pointer set by libvlc_media_player_watch_time()

libvlc_media_player_watch_time_on_seek

typedef void(* libvlc_media_player_watch_time_on_seek) (const libvlc_media_player_time_point_t *value, void *data)

Callback prototype that notify when the player is seeking or finished seeking.

Warning

It is forbidden to call any Media Player functions from here.

Note

It is not possible to receive points via on_update() while seeking.

Parameters

value	point of the seek request or NULL when seeking is finished
data	opaque pointer set by libvlc_media_player_watch_time()

libvlc_media_player_watch_time_on_update

typedef void(* libvlc_media_player_watch_time_on_update) (const libvlc_media_player_time_point_t *value, void *data)

Callback prototype that notify when the player state or time changed.

Get notified when the time is updated by the input or output source. The input source is the 'demux' or the 'access_demux'. The output source are audio and video outputs: an update is received each time a video frame is displayed or an audio sample is written. The delay between each updates may depend on the input and source type (it can be every 5ms, 30ms, 1s or 10s...). Users of this timer may need to update the position at a higher frequency from their own mainloop via libvlc_media_player_time_point_interpolate().

Warning

It is forbidden to call any Media Player functions from here.

Parameters

value	always valid, the time corresponding to the state
data	opaque pointer set by libvlc_media_player_watch_time()

Function Documentation

libvlc_media_player_time_point_get_next_date()

LIBVLC_API int64_t libvlc_media_player_time_point_get_next_date	(	const libvlc_media_player_time_point_t *	point,
		int64_t	system_now_us,
		int64_t	interpolated_ts_us,
		int64_t	next_interval_us
	)

Get the date of the next interval.

Can be used to setup an UI timer in order to update some widgets at specific interval. A next_interval of VLC_TICK_FROM_SEC(1) can be used to update a time widget when the media reaches a new second.

Note

The media time doesn't necessarily correspond to the system time, that is why this function is needed and uses the rate of the current point.

Parameters

point	time update obtained via the libvlc_media_player_watch_time_on_update()
system_now_us	same system date used by libvlc_media_player_time_point_interpolate()
interpolated_ts_us	ts returned by libvlc_media_player_time_point_interpolate()
next_interval_us	next interval, in us

Returns

the absolute system date, in us, of the next interval, use libvlc_delay() to get a relative delay.

Version

LibVLC 4.0.0 or later

libvlc_media_player_time_point_interpolate()

LIBVLC_API int libvlc_media_player_time_point_interpolate	(	const libvlc_media_player_time_point_t *	point,
		int64_t	system_now_us,
		int64_t *	out_ts_us,
		double *	out_pos
	)

Interpolate a timer value to now.

Parameters

point	time update obtained via the libvlc_media_player_watch_time_on_update() callback
system_now_us	current system date, in us, returned by libvlc_clock()
out_ts_us	pointer where to set the interpolated ts, in us
out_pos	pointer where to set the interpolated position

Returns

0 in case of success, -1 if the interpolated ts is negative (could happen during the buffering step)

Version

LibVLC 4.0.0 or later

libvlc_media_player_unwatch_time()

LIBVLC_API void libvlc_media_player_unwatch_time

(

libvlc_media_player_t *

p_mi

)

Unwatch time updates.

Parameters

p_mi	the media player

Version

LibVLC 4.0.0 or later

libvlc_media_player_watch_time()

LIBVLC_API int libvlc_media_player_watch_time	(	libvlc_media_player_t *	p_mi,
		int64_t	min_period_us,
		libvlc_media_player_watch_time_on_update	on_update,
		libvlc_media_player_watch_time_on_paused	on_paused,
		libvlc_media_player_watch_time_on_seek	on_seek,
		void *	cbs_data
	)

Watch for times updates.

Warning

Only one watcher can be registered at a time. Calling this function a second time (if libvlc_media_player_unwatch_time() was not called in-between) will fail.

Parameters

p_mi	the media player
min_period_us	corresponds to the minimum period, in us, between each updates, use it to avoid flood from too many source updates, set it to 0 to receive all updates.
on_update	callback to listen to update events (must not be NULL)
on_paused	callback to listen to paused events (can be NULL)
on_seek	callback to listen to seek events (can be NULL)
cbs_data	opaque pointer used by the callbacks

Returns

0 on success, -1 on error (allocation error, or if already watching)

Version

LibVLC 4.0.0 or later