Tizen Native API  5.5
Streaming

The Streaming API provides functions for streaming playback and buffering controlling.

Required Header

#include <player.h>

Overview

The streaming API allows you to set and get various properties to setup network connection and control buffering scheme:

Functions

int player_set_streaming_cookie (player_h player, const char *cookie, int size)
 Sets the cookie for streaming playback.
int player_set_streaming_user_agent (player_h player, const char *user_agent, int size)
 Sets the streaming user agent for playback.
int player_get_streaming_download_progress (player_h player, int *start, int *end)
 Gets the download progress for streaming playback.
int player_set_buffering_cb (player_h player, player_buffering_cb callback, void *user_data)
 Sets a callback function to be invoked when there is a change in the buffering status of a media stream.
int player_unset_buffering_cb (player_h player)
 Unsets the buffering callback function.
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_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_buffering_cb )(int percent, void *user_data)
 Called when the buffering percentage of the media playback is updated.
typedef void(* player_adaptive_variant_cb )(int bandwidth, int width, int height, void *user_data)
 Called to notify the streaming variant information.

Typedef Documentation

typedef void(* player_adaptive_variant_cb)(int bandwidth, int width, int height, void *user_data)

Called to notify the streaming variant information.

The adaptive streaming protocol(hls, mpeg dash) can support variant stream condition. All the streaming variant information can be shared by calling player_foreach_adaptive_variant().

Since :
4.0
Parameters:
[in]bandwidthThe bandwidth of the stream can be supportable, this is mandatory parameter
[in]widthThe width of the stream, this is optional parameter
[in]heightThe height of the stream, this is optional parameter
[in]user_dataThe user data passed from the callback registration function
See also:
player_foreach_adaptive_variant()
typedef void(* player_buffering_cb)(int percent, void *user_data)

Called when the buffering percentage of the media playback is updated.

If the buffer is full, it will return 100%.

Since :
2.3
Parameters:
[in]percentThe percentage of buffering completed (0~100)
[in]user_dataThe user data passed from the callback registration function
See also:
player_set_buffering_cb()
player_unset_buffering_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 function is used for adaptive streaming(hls/mpeg dash) only.
Parameters:
[in]playerThe handle to the media player
[in]callbackThe iteration callback function
[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
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_adaptive_variant_cb()
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 function is used for adaptive streaming(hls/mpeg dash) only.
Parameters:
[in]playerThe handle to the media player
[out]bandwidthThe max bandwidth limit of the stream variant (default: -1)
[out]widthThe max width limit of the stream variant (default: -1)
[out]heightThe max height limit of the stream variant (default: -1)
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_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]playerThe handle to the media player
[out]prebuffer_msThe time duration of buffering data that must be prerolled to start playback If the user did not set any value by calling player_set_streaming_buffering_time() function (or if the value was set to 0), the value is 0 which means platform default value depending on the streaming type and network status.
The value is set to time duration instead of 0 if the player state is one of: PLAYER_STATE_READY, PLAYER_STATE_PLAYING or PLAYER_STATE_PAUSED. (since 5.5)
[out]rebuffer_msThe time duration of buffering data that must be prerolled to resume playback if player is paused for buffering internally.
If the user did not set any value by calling player_set_streaming_buffering_time() function (or if the value was set to 0), the value is 0 which means platform default value depending on the streaming type and network status.
The value is set to time duration instead of 0 if the player state is one of: PLAYER_STATE_READY, PLAYER_STATE_PLAYING or PLAYER_STATE_PAUSED. (since 5.5)
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
See also:
player_set_streaming_buffering_time()
int player_get_streaming_download_progress ( player_h  player,
int *  start,
int *  end 
)

Gets the download progress for streaming playback.

Since :
2.3
Parameters:
[in]playerThe handle to the media player
[out]startThe starting position of received data in percentage [0, 100]
[out]endThe end position of received data in percentage [0, 100]
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_set_buffering_cb ( player_h  player,
player_buffering_cb  callback,
void *  user_data 
)

Sets a callback function to be invoked when there is a change in the buffering status of a media stream.

Since :
2.3
Remarks:
The media resource should be streamed over the network.
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
Postcondition:
player_buffering_cb() will be invoked.
See also:
player_unset_buffering_cb()
player_set_uri()
player_buffering_cb()
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 function 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]playerThe handle to the media player
[in]bandwidthThe max bandwidth limit of the stream variant (default: -1)
[in]widthThe max width limit of the stream variant (default: -1)
[in]heightThe max height limit of the stream variant (default: -1)
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_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]playerThe handle to the media player
[in]prebuffer_msThe time duration of buffering data that must be prerolled to start playback.
The value should be more than 1000 milliseconds to ensure the normal buffering.
There are, however, two exceptions:
0: Indicate to use platform default value depending on the streaming type and network status (default)
-1: Indicate to use current value (since 5.5)
[in]rebuffer_msThe time duration of buffering data that must be prerolled to resume playback if player is paused for buffering internally.
The value should be more than 1000 milliseconds to ensure the normal buffering.
There are, however, two exceptions:
0: Indicate to use platform default value depending on the streaming type and network status (default)
-1: Indicate to use current value (since 5.5)
Returns:
0 on success, otherwise a negative error value
Return values:
PLAYER_ERROR_NONESuccessful
PLAYER_ERROR_INVALID_PARAMETERInvalid parameter
PLAYER_ERROR_INVALID_STATEInvalid state
PLAYER_ERROR_INVALID_OPERATIONInvalid operation (since 5.5)
Precondition:
The player state must be PLAYER_STATE_IDLE.
See also:
player_get_streaming_buffering_time()
Example
   #include <player.h>
   bool set_buffering_time(player_h p)
   {
       int err = PLAYER_ERROR_NONE;

       // sets the prebuffer_ms to 5000 milliseconds but does not change the rebuffer_ms
       err =  player_set_streaming_buffering_time(p, 5000, -1);
       if (err != PLAYER_ERROR_NONE) {
          printf("Fail to set buffering time = 0x%x\n", err);
          return false;
       }
       return true;
   }
int player_set_streaming_cookie ( player_h  player,
const char *  cookie,
int  size 
)

Sets the cookie for streaming playback.

Since :
2.3
Remarks:
This function must be called before calling the player_prepare() or player_prepare_async() to reflect the cookie information when the streaming connection is set up.
Parameters:
[in]playerThe handle to the media player
[in]cookieThe cookie to set
[in]sizeThe size of the cookie
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 set to PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
See also:
player_set_uri()
player_set_streaming_user_agent()
int player_set_streaming_user_agent ( player_h  player,
const char *  user_agent,
int  size 
)

Sets the streaming user agent for playback.

Since :
2.3
Remarks:
This function must be called before calling the player_prepare() or player_prepare_async() to reflect the user agent information when the streaming connection is set up.
Parameters:
[in]playerThe handle to the media player
[in]user_agentThe user agent to set
[in]sizeThe size of the user agent
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 set to PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
See also:
player_set_uri()
player_set_streaming_cookie()

Unsets the buffering callback function.

Since :
2.3
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_buffering_cb()