The Subtitle API provides functions to control the subtitle.

Required Header

#include <player.h>

Functions
int	player_set_subtitle_path (player_h player, const char *path)
	Sets a subtitle path.
int	player_set_subtitle_updated_cb (player_h player, player_subtitle_updated_cb callback, void *user_data)
	Registers a callback function to be invoked when a subtitle updates.
int	player_unset_subtitle_updated_cb (player_h player)
	Unregisters the callback function.
int	player_set_subtitle_position_offset (player_h player, int millisecond)
	Sets the seek position for the subtitle.
int	player_set_video_stream_changed_cb (player_h player, player_video_stream_changed_cb callback, void *user_data)
	Registers a callback function to be invoked when video stream is changed.
int	player_unset_video_stream_changed_cb (player_h player)
	Unregisters the video stream changed callback function.
int	player_get_current_track (player_h player, player_stream_type_e type, int *index)
	Gets current track index.
int	player_get_track_language_code (player_h player, player_stream_type_e type, int index, char **code)
	Gets language code of a track.
int	player_get_track_count (player_h player, player_stream_type_e type, int *count)
	Gets the track count.
int	player_select_track (player_h player, player_stream_type_e type, int index)
	Selects a track to play.
int	player_foreach_adaptive_variant (player_h player, player_adaptive_variant_cb callback, void *user_data)
	Retrieves all the streaming variant information.
int	player_set_max_adaptive_variant_limit (player_h player, int bandwidth, int width, int height)
	Sets the maximum limit of the streaming variant.
int	player_get_max_adaptive_variant_limit (player_h player, int bandwidth, int width, int *height)
	Gets the maximum limit of the streaming variant.
int	player_set_audio_only (player_h player, bool audio_only)
	Sets the audio only mode.
int	player_is_audio_only (player_h player, bool *audio_only)
	Gets the audio only mode status.
int	player_set_streaming_buffering_time (player_h player, int prebuffer_ms, int rebuffer_ms)
	Sets the streaming buffering time.
int	player_get_streaming_buffering_time (player_h player, int prebuffer_ms, int rebuffer_ms)
	Gets the streaming buffering time.
Typedefs
typedef void(*	player_subtitle_updated_cb )(unsigned long duration, char text, void user_data)
	Called when the subtitle is updated.

Typedef Documentation

typedef void(* player_subtitle_updated_cb)(unsigned long duration, char *text, void *user_data)

Called when the subtitle is updated.

Since :: 2.3

Parameters:

[in]	duration	The duration of the updated subtitle
[in]	text	The text of the updated subtitle
[in]	user_data	The user data passed from the callback registration function

See also:: player_set_subtitle_updated_cb(); player_unset_subtitle_updated_cb()

Function Documentation

int player_foreach_adaptive_variant	(	player_h	player,
		player_adaptive_variant_cb	callback,
		void *	user_data
	)

Retrieves all the streaming variant information.

Since :: 4.0

Remarks:: This API is used for adaptive streaming(hls/mpeg dash) only.

Parameters:

[in]	player	The handle to the media player
[in]	callback	The iteration callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The player state must be one of PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED

See also:: player_adaptive_variant_cb

int player_get_current_track	(	player_h	player,
		player_stream_type_e	type,
		int *	index
	)

Gets current track index.

Index starts from 0.

Since :: 2.4

Parameters:

[in]	player	The handle to the media player
[in]	type	The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[out]	index	The index of track

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The player state must be one of PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED

int player_get_max_adaptive_variant_limit	(	player_h	player,
		int *	bandwidth,
		int *	width,
		int *	height
	)

Gets the maximum limit of the streaming variant.

Since :: 4.0

Remarks:: This API is used for adaptive streaming(hls/mpeg dash) only.

Parameters:

[in]	player	The handle to the media player
[out]	bandwidth	The max bandwidth limit of the stream variant (default: -1)
[out]	width	The max width limit of the stream variant (deafult: -1)
[out]	height	The max height limit of the stream variant (deafult: -1)

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: The player state must be one of PLAYER_STATE_IDLE, PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED.

See also:: player_foreach_adaptive_variant(); player_set_max_adaptive_variant_limit()

int player_get_streaming_buffering_time	(	player_h	player,
		int *	prebuffer_ms,
		int *	rebuffer_ms
	)

Gets the streaming buffering time.

Since :: 4.0

Parameters:

[in]	player	The handle to the media player
[in]	prebuffer_ms	The buffer time to start playback
[in]	rebuffer_ms	The buffer time during playback if player enter pause state for buffering.

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_STATE	Invalid state

Precondition:: The player state must be one of PLAYER_STATE_IDLE, PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED.

See also:: player_get_streaming_buffering_time()

int player_get_track_count	(	player_h	player,
		player_stream_type_e	type,
		int *	count
	)

Gets the track count.

Since :: 2.4

Parameters:

[in]	player	The handle to the media player
[in]	type	The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[out]	count	The number of track

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The player state must be one of PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED

int player_get_track_language_code	(	player_h	player,
		player_stream_type_e	type,
		int	index,
		char **	code
	)

Gets language code of a track.

Since :: 2.4

Remarks:: code must be released with free() by caller

Parameters:

[in]	player	The handle to the media player
[in]	type	The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[in]	index	The index of track
[out]	code	A language code in ISO 639-1. "und" will be returned if the language is undefined.

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The player state must be one of PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED

int player_is_audio_only	(	player_h	player,
		bool *	audio_only
	)

Gets the audio only mode status.

Since :: 4.0

Parameters:

[in]	player	The handle to the media player
[out]	audio_only	The current audio only status: (`true` = audio only enabled, `false` = audio only disabled)

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: The player state must be one of: PLAYER_STATE_IDLE, PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED.

See also:: player_set_audio_only()

int player_select_track	(	player_h	player,
		player_stream_type_e	type,
		int	index
	)

Selects a track to play.

Since :: 2.4

Parameters:

[in]	player	The handle to the media player
[in]	type	The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[in]	index	The index of track

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The player state must be one of PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED

See also:: player_get_current_track()

int player_set_audio_only	(	player_h	player,
		bool	audio_only
	)

Sets the audio only mode.

This function is used to disable or enable video rendering during playback.

Since :: 4.0

Parameters:

[in]	player	The handle to the media player
[in]	audio_only	The new audio only status: (`true` = enable audio only, `false` = disable audio only)

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The player state must be one of: PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED.

See also:: player_is_audio_only()

int player_set_max_adaptive_variant_limit	(	player_h	player,
		int	bandwidth,
		int	width,
		int	height
	)

Sets the maximum limit of the streaming variant.

Since :: 4.0

Remarks:: This API is used for adaptive streaming(hls/mpeg dash) only.; The bandwidth setting can only be applied if there is no width, height information at streaming variant header. Application can get all the variant information by calling player_foreach_adaptive_variant() function.; If there is no affordable stream for the condition, the minimum bandwidth stream will be selected.

Parameters:

[in]	player	The handle to the media player
[in]	bandwidth	The max bandwidth limit of the stream variant (default: -1)
[in]	width	The max width limit of the stream variant (deafult: -1)
[in]	height	The max height limit of the stream variant (deafult: -1)

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: The player state must be one of PLAYER_STATE_IDLE, PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED.

See also:: player_foreach_adaptive_variant(); player_get_max_adaptive_variant_limit()

int player_set_streaming_buffering_time	(	player_h	player,
		int	prebuffer_ms,
		int	rebuffer_ms
	)

Sets the streaming buffering time.

Since :: 4.0

Parameters:

[in]	player	The handle to the media player
[in]	prebuffer_ms	The buffer time to start playback
[in]	rebuffer_ms	The buffer time during playback if player enter pause state for buffering.

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_STATE	Invalid state

Precondition:: The player state must be PLAYER_STATE_IDLE.

See also:: player_get_streaming_buffering_time()

int player_set_subtitle_path	(	player_h	player,
		const char *	path
	)

Sets a subtitle path.

Since :: 2.3

Remarks:: Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.; The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any files are used to play located in the internal storage.; The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any files are used to play located in the external storage.; The path value can be NULL for reset before calling player_prepare() or player_prepare_async().

Parameters:

[in]	player	The handle to the media player
[in]	path	The absolute path of the subtitle file, it can be `NULL` in the PLAYER_STATE_IDLE state.

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state
PLAYER_ERROR_PERMISSION_DENIED	Permission denied
PLAYER_ERROR_NO_SUCH_FILE	File not found (Since 4.0)

Precondition:: The player state must be one of PLAYER_STATE_IDLE, PLAYER_STATE_READY, PLAYER_STATE_PLAYING, or PLAYER_STATE_PAUSED.

int player_set_subtitle_position_offset	(	player_h	player,
		int	millisecond
	)

Sets the seek position for the subtitle.

Since :: 2.3.1

Remarks:: Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.

Parameters:

[in]	player	The handle to the media player
[in]	millisecond	The position in milliseconds from the start to the seek point

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation
PLAYER_ERROR_INVALID_STATE	Invalid player state

Precondition:: The subtitle must be set by calling player_set_subtitle_path().; The player state must be one of PLAYER_STATE_PLAYING or PLAYER_STATE_PAUSED.

int player_set_subtitle_updated_cb	(	player_h	player,
		player_subtitle_updated_cb	callback,
		void *	user_data
	)

Registers a callback function to be invoked when a subtitle updates.

Since :: 2.3

Remarks:: The callback is called in a separate thread (not in the main loop).

Parameters:

[in]	player	The handle to the media player
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: The subtitle must be set by calling player_set_subtitle_path().

Postcondition:: player_subtitle_updated_cb() will be invoked.

See also:: player_unset_subtitle_updated_cb(); player_subtitle_updated_cb(); player_set_subtitle_path()

int player_set_video_stream_changed_cb	(	player_h	player,
		player_video_stream_changed_cb	callback,
		void *	user_data
	)

Registers a callback function to be invoked when video stream is changed.

Since :: 2.4

Remarks:: The stream changing is detected just before rendering operation.; The callback is called in a separate thread (not in the main loop).; This API must be called before calling the player_prepare() or player_prepare_async() to reflect the requirement when the player is building.

Parameters:

[in]	player	The handle to the media player
[in]	callback	The stream changed callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_STATE	Invalid player state
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: The player state must be set to PLAYER_STATE_IDLE by calling player_create() or player_unprepare().

Postcondition:: player_video_stream_changed_cb() will be invoked.

See also:: player_unset_video_stream_changed_cb(); player_video_stream_changed_cb()

int player_unset_subtitle_updated_cb ( player_h player )

Unregisters the callback function.

Since :: 2.3

Parameters:

[in] player The handle to the media player

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_OPERATION	Invalid operation

See also:: player_set_subtitle_updated_cb()

int player_unset_video_stream_changed_cb ( player_h player )

Unregisters the video stream changed callback function.

Since :: 2.4

Parameters:

[in] player The handle to the media player

Returns:: 0 on success, otherwise a negative error value

Return values:

PLAYER_ERROR_NONE	Successful
PLAYER_ERROR_INVALID_STATE	Invalid player state
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: player_set_video_stream_changed_cb()

Required Header

Functions

Typedefs

Typedef Documentation

Function Documentation