Tizen Native API  3.0

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]durationThe duration of the updated subtitle
[in]textThe text of the updated subtitle
[in]user_dataThe 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]playerThe handle to the media player
[in]typeThe type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[out]indexThe index of track
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
PLAYER_ERROR_INVALID_STATEInvalid 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]playerThe handle to the media player
[in]typeThe type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[out]countThe number of track
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
PLAYER_ERROR_INVALID_STATEInvalid 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]playerThe handle to the media player
[in]typeThe type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[in]indexThe index of track
[out]codeA 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_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
PLAYER_ERROR_INVALID_STATEInvalid 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]playerThe handle to the media player
[in]typeThe type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
[in]indexThe index of track
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
PLAYER_ERROR_INVALID_STATEInvalid 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]playerThe handle to the media player
[in]pathThe 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_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
PLAYER_ERROR_INVALID_STATEInvalid player state
PLAYER_ERROR_PERMISSION_DENIEDPermission 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]playerThe handle to the media player
[in]millisecondThe position in milliseconds from the start to the seek point
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
PLAYER_ERROR_INVALID_STATEInvalid 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]playerThe handle to the media player
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid 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]playerThe handle to the media player
[in]callbackThe stream changed callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_STATEInvalid player state
PLAYER_ERROR_INVALID_PARAMETERInvalid 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()

Unregisters the callback function.

Since :
2.3.1
Parameters:
[in]playerThe handle to the media player
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_OPERATIONInvalid operation
See also:
player_set_subtitle_updated_cb()

Unregisters the video stream changed callback function.

Since :
3.0
Parameters:
[in]playerThe handle to the media player
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_STATEInvalid player state
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
See also:
player_set_video_stream_changed_cb()