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:

connection information, such as cookie, user_agent.
buffering information, such as time, percent, progress.
variant information of adaptive streaming content, such as bandwidth, resolution.

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]	bandwidth	The bandwidth of the stream can be supportable, this is mandatory parameter
[in]	width	The width of the stream, this is optional parameter
[in]	height	The height of the stream, this is optional parameter
[in]	user_data	The 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]	percent	The percentage of buffering completed (0~100)
[in]	user_data	The 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]	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_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]	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 (default: -1)
[out]	height	The max height limit of the stream variant (default: -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

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
[out]	prebuffer_ms	The 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_ms	The 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_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid 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]	player	The handle to the media player
[out]	start	The starting position of received data in percentage [0, 100]
[out]	end	The end position of received data in percentage [0, 100]

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

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]	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 (default: -1)
[in]	height	The max height limit of the stream variant (default: -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

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 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_ms	The 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_NONE	Successful
PLAYER_ERROR_INVALID_PARAMETER	Invalid parameter
PLAYER_ERROR_INVALID_STATE	Invalid state
PLAYER_ERROR_INVALID_OPERATION	Invalid 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]	player	The handle to the media player
[in]	cookie	The cookie to set
[in]	size	The size of the cookie

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 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]	player	The handle to the media player
[in]	user_agent	The user agent to set
[in]	size	The size of the user agent

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 set to PLAYER_STATE_IDLE by calling player_create() or player_unprepare().

See also:: player_set_uri(); player_set_streaming_cookie()

int player_unset_buffering_cb ( player_h player )

Unsets the buffering 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_buffering_cb()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation