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 current)
	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_set_progressive_download_path (player_h player, const char *path) TIZEN_DEPRECATED_API
	Sets a path to download, progressively.
int	player_get_progressive_download_status (player_h player, unsigned long current, unsigned long total_size) TIZEN_DEPRECATED_API
	Gets the status of progressive download.
int	player_set_progressive_download_message_cb (player_h player, player_pd_message_cb callback, void *user_data) TIZEN_DEPRECATED_API
	Sets a callback function to be invoked when progressive download is started or completed.
int	player_unset_progressive_download_message_cb (player_h player) TIZEN_DEPRECATED_API
	Unsets the progressive download message 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_pd_message_cb )(player_pd_message_type_e type, void *user_data)
	Called when progressive download is started or completed.
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()

typedef void(* player_pd_message_cb)(player_pd_message_type_e type, void *user_data)

Called when progressive download is started or completed.

Since :: 2.3

Parameters:

[in]	type	The message type for progressive download
[in]	user_data	The user data passed from the callback registration function

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_progressive_download_status	(	player_h	player,
		unsigned long *	current,
		unsigned long *	total_size
	)

Gets the status of progressive download.

Deprecated:: Deprecated since 4.0.

Since :: 2.3

Parameters:

[in]	player	The handle to the media player
[out]	current	The current download position (bytes)
[out]	total_size	The total size of the file (bytes)

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 progressive download path must be set by calling player_set_progressive_download_path().; The player state must be set to PLAYER_STATE_PLAYING by calling player_start() or set to PLAYER_STATE_PAUSED by calling player_pause().

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.
[out]	rebuffer_ms	The time duration of buffering data that must be prerolled to resume playback if player enters pause state for buffering.

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 *	current
	)

Gets the download progress for streaming playback.

Since :: 2.3

Parameters:

[in]	player	The handle to the media player
[out]	start	The starting position in percentage [0, 100]
[out]	current	The current position 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 set to PLAYER_STATE_PLAYING by calling player_start() or set to PLAYER_STATE_PAUSED by calling player_pause().

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_progressive_download_message_cb	(	player_h	player,
		player_pd_message_cb	callback,
		void *	user_data
	)

Sets a callback function to be invoked when progressive download is started or completed.

Deprecated:: Deprecated since 4.0.

Since :: 2.3

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 path to download must be set by calling player_set_progressive_download_path().

Postcondition:: player_pd_message_cb() will be invoked.

int player_set_progressive_download_path	(	player_h	player,
		const char *	path
	)

Sets a path to download, progressively.

Deprecated:: Deprecated since 4.0.

Since :: 2.3

Remarks:: Progressive download will be started when you invoke player_start().; This function must be called before calling the player_prepare() or player_prepare_async() to reflect the download path when the player is building.; The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any files are used to download and play located in the internal storage.; The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any files are used to download and play located in the external storage.

Parameters:

[in]	player	The handle to the media player
[in]	path	The absolute path to download

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

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.
[in]	rebuffer_ms	The time duration of buffering data that must be prerolled to resume playback if player is paused for buffering internally.

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

Precondition:: The player state must be PLAYER_STATE_IDLE.

See also:: player_get_streaming_buffering_time()

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

int player_unset_progressive_download_message_cb ( player_h player )

Unsets the progressive download message callback function.

Deprecated:: Deprecated since 4.0.

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

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation