Subtitle

---

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)
	Sets a callback function to be invoked when a subtitle updates.
int	player_unset_subtitle_updated_cb (player_h player)
	Unsets the subtitle updated callback function.
int	player_set_subtitle_position_offset (player_h player, int millisecond)
	Sets the seek position for the subtitle.
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

Remarks:

The text should not be released and it can be used only in the callback. To use outside, make a copy.

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_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
	)

Sets 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_unset_subtitle_updated_cb

(

player_h

player

)

Unsets the subtitle updated 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()