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

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_get_current_track	(	player_h	player,
		player_stream_type_e	type,
		int *	index
	)

Gets current track index.

Since :: 3.0

Index starts from 0.

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_track_count	(	player_h	player,
		player_stream_type_e	type,
		int *	count
	)

Gets the track count.

Since :: 3.0

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 :: 3.0

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_select_track	(	player_h	player,
		player_stream_type_e	type,
		int	index
	)

Selects a track to play.

Since :: 3.0

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_subtitle_path	(	player_h	player,
		const char *	path
	)

Sets a subtitle path.

Since :: 2.3.1

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

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

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 :: 3.0

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

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 :: 3.0

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