INTRODUCTION

SSSP

Introduction

Spec & Products

H.Browser

Tizen Hotel TV

Orsay Hotel TV
GUIDE

SSSP

Specifications

Getting Started

Guides

API References

Tools

Extention Libraries

H.Browser

Tizen Hotel TV

Orsay Hotel TV

KIOSK

Specifications

Getting Started

Guides

API References

Tools
DOWNLOAD

SDK Download

SDK Download
COMMUNITY

News & Updates

News & Updates

FAQ

FAQ

Q&A

Q&A

GUIDE

GUIDE

AVPlay API

To use Samsung Product API,
<script type="text/javascript" src="$WEBAPIS/webapis/webapis.js"></script>
Should be loaded in index.html

For RTP/UDP steaming case use B2BAVPlay library,
<script type="text/javascript" src="$B2BAPIS/b2bapis/b2bavplay.js"></script>
Should be loaded in index.html, This library file required from Smart Signage 3.0

This module defines the multimedia player functionalities provided by the Tizen Samsung Smart Signage Product API.

Since : 2.4

Product : Smart Signage

Summary of Interfaces and Methods

Interface	Method
AVPlayManagerObject
AVPlayManager	void open(); void close(); void prepare(); void prepareAsync(opitional SuccessCallback? successCallback, optional ErrorCallback? errorCallback); void setDisplayRect(unsigned long x, unsigned long y, unsigned long width, unsigned long height); void play(); void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback); void stop(); AVPlayPlayerState getState(); void pause(); void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback); void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback ); unsigned long getDuration(); unsigned long getCurrentTime(); void setTimeoutForBuffering(unsigned long seconds); void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount); void setSpeed(long playbackSpeed); void setListener(AVPlayPlaybackCallback playbackCallback); DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam); void setDisplayMethod(AVPlayDisplayMode displayMode); void setDisplayRotation(AVPlayDisplayRotation DisplayRotation); void setVideoStillMode(boolean bStillMode); void setStreamingProperty(AVPlayStreamingPropertyType propertyType, DOMString propertyParam); DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType); DOMString getVersion(); void suspend(); void restore(DOMString URL, optional unsigned optional long? resumeTime, optional boolean? bPrepare) ; void restoreAsync(DOMString URL, optional unsigned optional long? resumeTime, optioanl optional boolean? bPrepare, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) ;
AVPlayPlaybackCallback	void onbufferingstart(); void onbufferingprogress(unsigned long percent); void onbufferingcomplete(); void oncurrentplaytime(unsigned long currentTime ); void onstreamcompleted(); void onevent(AVPlayEvent eventid, DOMString data ); void onerror(AVPlayError eventid); void ondrmevent(AVPlayDrmType type, drmData data);

1. Type Definitions

1.1. AVPlayPlayerState

Specifies the player state.


enum AVPlayPlayerState {
  "NONE",
  "IDLE",
  "READY",
  "PLAYING",
  "PAUSED"
};

Since : 2.4

The following values are supported

NONE : Player is not created
IDLE : Player is created but not prepared
READY : Player is ready to play media
PLAYING : Player is playing media
PAUSED : Player is paused

1.2. AVPlayDisplayMode

Specifies display modes.


enum AVPlayDisplayMode { 
  "PLAYER_DISPLAY_MODE_LETTER_BOX", 
  "PLAYER_DISPLAY_MODE_FULL_SCREEN",
  "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO" 
};

Since : 2.4

The following values are supported

PLAYER_DISPLAY_MODE_LETTER_BOX : Letterbox mode
PLAYER_DISPLAY_MODE_FULL_SCREEN : Full-screen mode
PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO : Screen mode based on video dar/par info

1.3. AVPlayBufferOption

Specifies buffering scenarios.


enum AVPlayBufferOption { 
  "PLAYER_BUFFER_FOR_PLAY", 
  "PLAYER_BUFFER_FOR_RESUME" 
};

Since : 2.4

The following values are supported

PLAYER_BUFFER_FOR_PLAY : Initial buffering scenario
PLAYER_BUFFER_FOR_RESUME : Re-buffering which might be occured after initial buffering during the playback. The onbufferingcomplete event would be triggered when the PLAYER_BUFFER_FOR_PLAY amount of data is buffered. The actual buffering completion time may vary depending on the contents format, bitrate, network speed and so on.

1.4. AVPlayBufferSizeUnit

This enumeration defines the Buffering param's Unit defined by the player.


enum AVPlayBufferSizeUnit {
  "PLAYER_BUFFER_SIZE_IN_BYTE", 
  "PLAYER_BUFFER_SIZE_IN_SECOND" 
};

Since : 2.4

The following values are supported

PLAYER_BUFFER_SIZE_IN_BYTE
PLAYER_BUFFER_SIZE_IN_SECOND : Buffer size in seconds

Remark :

"PLAYER_BUFFER_SIZE_IN_BYTE" property has been deprecated from Tizen version 5.0

1.5. AVPlayStreamingPropertyType

Specifies parameters for various streaming protocols, such as HTTP, MMS, and adaptive streaming (Smooth Streaming, HLS, and MPEG-DASH).


enum AVPlayStreamingPropertyType { 
  "COOKIE", 
  "USER_AGENT", 
  "PREBUFFER_MODE", 
  "ADAPTIVE_INFO",  
  "SET_MODE_4K",
  "PROPERTY_HD_AUDIO", 
  "LISTEN_SPARSE_TRACK", 
  "IS_LIVE", 
  "AVAILABLE_BITRATE", 
  "GET_LIVE_DURATION", 
  "CURRENT_BANDWIDTH", 
  "WIDEVINE",                                                                                                                                                                       
  "USE_VIDEOMIXER",                                                                                                                                                                 
   "SET_MIXEDFRAME"
};

Since : 2.4

The following values are supported

COOKIE : HTTP request cookie used to establish the session with the HTTP server. (for setStreamingProperty)
USER_AGENT : HTTP user agent, used in the HTTP request header. (for setStreamingProperty)
PREBUFFER_MODE : Property to initiate prebuffering mode. The second parameter indicates start-time for prebuffered content, in milliseconds. (for setStreamingProperty)
ADAPTIVE_INFO : Sets a custom streaming URL with various streaming parameters, such as "BITRATES", "STARTBITRATE", or "SKIPBITRATE" (for setStreamingProperty)
String containing custom attributes for adaptive streaming playback.
- "STARTBITRATE=" Valid values are "LOWEST", "HIGHEST", and "AVERAGE". You can also define a specific bandwidth for the start of playback.
- "FIXED_MAX_RESOLUTION=max_widthXmax_height". Only if the given media URI such as mpd in MPEG-DASH or m3u8 in HLS through open() method doesn't describe entire required video resolutions in case of 4K / 8K adaptive streaming, application should use this attribute to complete the resolution information for the player. If the metadata file (mpd in MPEG-DASH or m3u8 in HLS) doesn’t describe the video resolutions of its contents and the max resolution of the adaptive streaming content is 3000x2000, it can be set as below.
  webapis.avplay.setStreamingProperty("ADAPTIVE_INFO", "FIXED_MAX_RESOLUTION=3000x2000");
  
  It might not be able to stream contents which don't have any issue when the resolution value is wrongly set and the API is unnecessarily used. So, applications should wisely use this option only when they know the exact max resolution value in case that the metadata doesn't contain the whole resolution information. It’s recommended to set the value only when 4K / 8K contents are played.
- "BITRATES=" Use '~' to define a bandwidth range (5000 ~ 20000). You can also define a specific bandwidth for playback.
- "SKIPBITRATE=" Defines the bandwidth to use after a skip operation.
- "STARTFRAGMENT=" For live content playback, defines the start fragment number.
LISTEN_SPARSE_TRACK : For the Smooth Streaming case, configures the player to listen for a "Sparse name" configured through "propertyParam". The sparse track name is a string. (for setStreamingProperty)
IS_LIVE : Whether the stream is LIVE or VOD. Applicable to all streaming types. (for getStreamingProperty)
AVAILABLE_BITRATE : String listing the available bit-rates for the currently-playing stream. (for getStreamingProperty)
GET_LIVE_DURATION : String describing the duration of live content. (for getStreamingProperty)
CURRENT_BANDWIDTH : String describing the current streaming bandwidth. (for getStreamingProperty)
SET_VR360_MODE : Forces the player to use the VR360 mode. Its parameter can be the string "TRUE" or "FALSE". (for setStreamingProperty)
USE_VIDEOMIXER : Property used for enabling/initializing video mixer feature on SSSP only (for setStreamingProperty). It should be set before calling prepare and before setting SET_MIXEDFRAME property on the player
SET_MIXEDFRAME : Property to set the position of mixed frame (for setStreamingProperty). This should be called after prepare() call. setDisplayRect with required position on corresponding player instance should be called before setting this property.

Remark :

"GET_LIVE_DURATION" is available since Tizen version 2.4.
"WIDEVINE" property has been deprecated from Tizen version 4.0.
"PROPERTY_HD_AUDIO" property has been deprecated from Tizen version 2.4.
"SET_VR360_MODE" property has been deprecated from Tizen version 5.0.
"SET_MODE_4K" property has been deprecated from Tizen version 5.0.

1.6. AVPlayDrmType

Specifies DRM systems supported by the player.


enum AVPlayDrmType {
  "LYNK"
};

Since : 2.4

The following values are supported

LYNK : LYNK

1.7. AVPlayDrmOperation

Specifies various DRM operations.


enum AVPlayDrmOperation { 
  "Initialize"
};

Since : 2.4

The following values are supported

Initialize : Initialize the DRM instance

1.8. AVPlayError

Specifies the player error messages.


enum AVPlayError{
  "PLAYER_ERROR_NONE",
  "PLAYER_ERROR_INVALID_PARAMETER",
  "PLAYER_ERROR_NO_SUCH_FILE",
  "PLAYER_ERROR_INVALID_OPERATION",
  "PLAYER_ERROR_SEEK_FAILED",
  "PLAYER_ERROR_INVALID_STATE",
  "PLAYER_ERROR_NOT_SUPPORTED_FILE",
  "PLAYER_ERROR_INVALID_URI",
  "PLAYER_ERROR_CONNECTION_FAILED",
  "PLAYER_ERROR_GENEREIC"
};

Since : 2.4

The following values are supported

PLAYER_ERROR_NONE : Operation has successfully completed; no error.
PLAYER_ERROR_INVALID_PARAMETER : Unable to find the parameter
PLAYER_ERROR_NO_SUCH_FILE : Unable to find the specified media content
PLAYER_ERROR_INVALID_OPERATION : Invalid API Call at the moment
PLAYER_ERROR_SEEK_FAILED : Failed to perform seek operation, or seek operation called during an invalid state
PLAYER_ERROR_INVALID_STATE : AVPlay API method was called during an invalid state
PLAYER_ERROR_NOT_SUPPORTED_FILE : Multimedia file format not supported
PLAYER_ERROR_INVALID_URI : Input URI is in an invalid format
PLAYER_ERROR_CONNECTION_FAILED : Failed multiple attempts to connect to the specified content server
PLAYER_ERROR_GENEREIC : Failed to create the display window

1.9. AVPlayEvent

Specifies player events.


enum AVPlayEvent {
  "PLAYER_MSG_NONE",
  "PLAYER_MSG_RESOLUTION_CHANGED",
  "PLAYER_MSG_BITRATE_CHANGE",
  "PLAYER_MSG_FRAGMENT_INFO",
  "PLAYER_SPARSE_TRACK_DETECT",
  "PLAYER_STREAMING_EVENT",
  "PLAYER_MSG_HTTP_ERROR_CODE",
  "PLAYER_MSG_DRM_CHALLENGE_DATA",       
  "PLAYER_MSG_RENDER_DONE",                                                                                         
  "PLAYER_MSG_STREAM_INFO_READY"
};

Since : 2.4

The following values are supported

PLAYER_MSG_NONE : Notifies that a multimedia component message was not recognized by the player
PLAYER_MSG_RESOLUTION_CHANGED : During adaptive streaming playback, notifies that the video resolution has changed
PLAYER_MSG_BITRATE_CHANGE : During adaptive streaming playback, notifies of a change, based on network heuristics, in the bandwidth-specific URL. The current bandwidth value is also sent.
PLAYER_MSG_FRAGMENT_INFO : Posts the downloaded fragment details. The following information is posted:
fragment number, stream-type, current bitrate, and download time for this fragment
PLAYER_SPARSE_TRACK_DETECT : During adaptive streaming playback, notifies that a sparse track was encountered
PLAYER_STREAMING_EVENT : Posts required streaming data
PLAYER_MSG_HTTP_ERROR_CODE : Describes the detailed HTTP network situation information
PLAYER_MSG_DRM_CHALLENGE_DATA : For encrypted content playback, posts the DRM challenge data
PLAYER_MSG_RENDER_DONE : This event triggered only IPTV stream
PLAYER_MSG_STREAM_INFO_READY : This event triggered only IPTV stream

1.10. AVPlayDisplayRotation

Specifies display Rotation.


enum AVPlayDisplayMode { 
  "PLAYER_DISPLAY_ROTATION_90", 
  "PLAYER_DISPLAY_ROTATION_180",
  "PLAYER_DISPLAY_ROTATION_270",                                                                                               
  "PLAYER_DISPLAY_ROTATION_0"
};

Since : 2.4

The following values are supported

PLAYER_DISPLAY_ROTATION_90 : rotate 90 anticlockwise (PORTRAIT Mode)
PLAYER_DISPLAY_ROTATION_180 : rotate 180 anticlockwise
PLAYER_DISPLAY_ROTATION_270 : rotate 270 anticlockwise (PORTRAIT Mode)
PLAYER_DISPLAY_ROTATION_0 : rotate 0 anticlockwise (LANDSCAPE Mode)

2. Interfaces

2.1. AVPlayManagerObject

Defines a WebApi object instance of the Tizen Samsung Smart Signage Product API.
The webapis.AVPlay object enables access to AVPlay API functionality.


[NoInterfaceObject] interface AVPlayManagerObject {
  readonly attribute AVPlayManager avplay;
};


WebApi implements AVPlayManagerObject;

Attributes

readonly AVPlayManager avplay
AVPlay API namespace

2.2. AVPlayManager

Provides methods for the AVPlay functionalities.


[NoInterfaceObject] interface AVPlayManager {
  void open(DOMString url) ;
  void close() ;
  void prepare() ;
  void prepareAsync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) ;
  void setDisplayRect( unsigned long x, unsigned long y, unsigned long width, unsigned long height ) ;
  void play() ;
  void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
  void stop() ;
  AVPlayPlayerState getState() ;
  void pause() ;
  void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) ;
  void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback ) ;
  unsigned long getDuration() ;
  unsigned long getCurrentTime() ;
  void setTimeoutForBuffering(unsigned long seconds);
  void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);
  void setSpeed(long playbackSpeed)  ;
  void setListener(AVPlayPlaybackCallback playbackCallback)  ;
  DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam)  ;  
  void setDisplayMethod(AVPlayDisplayMode displayMode)  ;                                                                                                           
  void setDisplayRotation(AVPlayDisplayRotation DisplayRotation);                                                                                                
  void setVideoStillMode(boolean bStillMode);
  void setStreamingProperty(AVPlayStreamingPropertyType propertyType, DOMString propertyParam)  ;  
  DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType)  ;
  DOMString getVersion()  ;
  void suspend() ;
 void restore(DOMString URL, optional unsigned long? resumeTime, optional boolean? bPrepare);
  void restoreAsync(DOMString URL, optional unsigned long? resumeTime, optioanl boolean? bPrepare, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
};

Methods

open

Instantiates the player object with a content URL as the input parameter.


void open(DOMString url);

Product : Smart Signage

Parameters:

url: Content URL for playback. It can be an absolute local path or a remote URL from a network-based stream server.

Constraint

Can be called in the following states: "NONE", "IDLE"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.open(url);
	}
	catch (e) 
	{
	console.log(e);
	}

close

Destroys the player object.


        void close();

Product : Smart Signage

Constraint

Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.close();
	} 
	catch (e) 
	{
	console.log(e);
	}

prepare

Prepares the media player for playback synchronously. The player must already be created with a valid URI.


void prepare();

Product : Smart Signage

Constraint

Can be called in the following states: "IDLE", "READY"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.prepare();
	} 
	catch (e) 
	{
	console.log(e);
	}

prepareAsync

Prepares the media player for playback asynchronously. This method is preferred over prepare because it returns immediately and does not block the application thread during preparation.
When preparation is successful, the success callback is returned and the player is in READY state. If preparation fails, the error callback returns the error value.
When prepareAsync is used with "PREBUFFER_MODE", successCallback is invoked when prebuffering is complete, instead of when preparation is complete.


void prepareAsync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product : Smart Signage

Parameters:

successCallback: Callback method to invoke when the call is successful
errorCallback: Callback method to invoke when an error occurs

Constraint

Can be called in the following states: "IDLE", "READY"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.prepareAsync(successCallback, errorCallback);

setDisplayRect

Sets the display area for video content playback. The 4 parameters specify the left side, top, window width, and window height based on a 1920 x 1080 resolution screen, regardless of the actual application resolution.


void setDisplayRect( unsigned long x, unsigned long y, unsigned long width, unsigned long height );

Product : Smart Signage

Parameters:

x: Display area top-left X-coordinate. Must be less than the Signage device screen width.
y: Display area top-left Y-coordinate. Must be less than the Signage device screen height.
width: Display area width. Must be less than the Signage device screen width.
height: Display area height from source image. Must be less than the source image height.

Constraint

Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED" (when APP is using normal calling sequence , OPEN+setDisplay+PREPARE etc).

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.setDisplayRect(0, 0, 1920, 1080);
	}
	catch (e)
	{
	  console.log(e);
	}

play

Starts stream playback, or resumes stream playback after pause.


void play();

Product : Smart Signage

Constraint

Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.play();
	} 
	catch (e) 
	{
	console.log(e);
	}

Remark :

Adaptive streaming using TS container (for e.g. HLS) with audio sample rate changing across variants may cause audio loss.

seekTo

Skips playback to a specific timestamp.
For HTTP streaming, this method is successful even when the specified timestamp is invalid. The internal player automatically resets an out-of-range value to an in-range one.


void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product : Smart Signage

Parameters:

milliseconds: Timestamp to skip to
successCallback: Callback method to invoke when the call is successful
errorCallback: Callback method to invoke when an error occurs

Constraint

Can be called in the following states: "IDLE","READY", "PLAYING" (buffered data is flushed and buffering starts over), "PAUSED".
During this async operation, the other API would not be allowed. So, the application needs to wait for one of both callbacks( SuccessCallback, errorCallback) before any other API call.
For LIVE stream case, seek position must be within DVR range. DVR range could be retrieved using GET_LIVE_DURATION property in getStreamingProperty API.

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.seekTo(10000,successCallback, errorCallback);
	}
	catch (e)
	{
		console.log(e);
	}
// for live cases, get the live duration as :
var StartTime = webapis.avplay.getStreamingProperty("GET_LIVE_DURATION").split('|')[0];
var EndTime = webapis.avplay.getStreamingProperty("GET_LIVE_DURATION").split('|')[1];
// seekpoint must be between StartTime and Endtime.

stop

Stops the player. Call this function after the video finishes playing.


void stop();

Product : Smart Signage

Constraint

Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.stop();
	} 
	catch (e) 
	{
	console.log(e);
	}

getState

Retrieves the current player state.


  AVPlayPlayerState getState();

Product : Smart Signage

Return value:

AVPlayPlayerState "NONE", "IDLE", "READY", "PLAYING", "PAUSED".

Constraint

Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


var BRet = webapis.avplay.getState();

pause

Pauses playback. If this method is called successfully, current time updates are stopped.


 void pause();

Product : Smart Signage

Constraint

Can be called in the following states: "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type InvalidAccessError, if this API couldn't operate at the moment. (E.g. During the async operation such as seekTo, etc.)
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.pause();
	} 
	catch (e) 
	{
	console.log(e);
	}

jumpForward

Skips playback forward by a specific amount of time. The player state is unchanged.
Passing the optional callbacks is recommended. For best performance, ensure that the previous call to this API was successful.
For HTTP streaming, this method is successful even when the resulting timestamp is invalid. The internal player automatically resets an out-of-range value to an in-range one.


 void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product :Smart Signage

Parameters:

milliseconds: Time to skip forward, in milliseconds
successCallback: Callback method to invoke when the call is successful
errorCallback: Callback method to invoke when an error occurs

Constraint

Can be called in the following states: "READY" (when using the synchronous prepare method), "PLAYING", "PAUSED"
During this async operation, the other API would not be allowed. So, the application needs to wait for one of both callbacks( SuccessCallback, errorCallback) before any other API call.

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.jumpForward(5000,  successCallback, errorCallback);

jumpBackward

Skips playback backward by a specific amount of time. The player state is unchanged.
For HTTP streaming, this method is successful even when the resulting timestamp is invalid. The internal player automatically resets an out-of-range value to an in-range one.


void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback );

Product : Smart Signage

Parameters:

milliseconds: Time to skip backward, in milliseconds
successCallback: Callback method to invoke when the call is successful
errorCallback: Callback method to invoke when an error occurs

Constraint

Can be called in the following states: "READY" (when using the synchronous prepare method), "PLAYING", "PAUSED"
During this async operation, the other API would not be allowed. So, the application needs to wait for one of both callbacks( SuccessCallback, errorCallback) before any other API call.

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.jumpBackward(5000,  successCallback, errorCallback);

getDuration

Retrieves the total media duration.


unsigned long getDuration();

Product : Smart Signage

Return value:

unsigned long number Duration, in milliseconds

Constraint

Can be called in the following states:"NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


duration = calcPlaytime(webapis.avplay.getDuration());

function calcPlaytime(totalMilisec) {
  var Hours = Math.floor(totalMilisec/3600000);
  var Minutes = Math.floor((totalMilisec - (Hours * 3600000)) / 60000);
  var Seconds = Math.floor((totalMilisec - (Hours * 3600000) - (Minutes * 60000)) / 1000);
  var Milisec = totalMilisec - (Hours * 3600000) - (Minutes * 60000) - (Seconds * 1000);
  return {
    Hours: Hours,
    Minutes: Minutes,
    Seconds: Seconds,
    milisec: Milisec,
    totalMilisec: totalMilisec
  }
}

getCurrentTime

Retrieves the current playback time.


unsigned long getCurrentTime();

Product : Smart Signage

Return value:

unsigned long number Current playback time, in milliseconds.

Constraint

Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


var CurrentPlayTime = webapis.avplay.getCurrentTime();

setTimeoutForBuffering

Sets the stream buffering timeout. When the specified amount of time has passed, the onbufferingcomplete callback is invoked, irrespective of buffering progress.
If not set using this method, the default buffer size is 32MB or 10 seconds of playable data, and 20 seconds time-out.


void setTimeoutForBuffering(unsigned long seconds);

Product : Smart Signage

Parameters

seconds: Buffering timeout duration, in seconds. Depending on network conditions, 3 to 10 seconds is recommended.

Constraint

Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.setTimeoutForBuffering(10);

setBufferingParam

Sets the buffer size for the play and resume scenarios. The time buffer size must be at least 4 seconds.
For example, If a 10 second buffer size is set, playback can only start or resume after 10 seconds of media has accumulated in the buffer.
Play scenarios include user-initiated streaming playback and whenever media playback is starting for the first time.
Resume scenarios include resuming playback after pause or seek operations, or when lack of data causes playback rebuffering.


void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);

Product : Smart Signage

Parameters

option: "PLAYER_BUFFER_FOR_PLAY" or "PLAYER_BUFFER_FOR_RESUME"
unit: "PLAYER_BUFFER_SIZE_IN_SECOND"
amount: Data amount to be buffered, in bytes or seconds as specified by the unit parameter

Constraint

Can be called in the following states: "IDLE"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


// For the initial buffering
webapis.avplay.setBufferingParam("PLAYER_BUFFER_FOR_PLAY","PLAYER_BUFFER_SIZE_IN_SECOND", 5); // 5 is in seconds
// For the rebuffering
webapis.avplay. setBufferingParam("PLAYER_BUFFER_FOR_RESUME","PLAYER_BUFFER_SIZE_IN_SECOND", 15); // 15 is in seconds

Remark:

unit "PLAYER_BUFFER_SIZE_IN_BYTE" has been deprecated from Tizen version 5.0

setSpeed

Sets the current playback rate. Positive parameter values play the media forwards, while negative values cause the media to play in reverse.
The range of valid playback rates depends on the streaming protocol. If the input parameter is out of range, the player returns the PLAYER_ERROR_INVALID_PARAMETER flag.


 void setSpeed(long playbackSpeed);

Product :Smart Signage

Parameters:

playbackSpeed: -16x, -8x, -4x, -2x, 1x, 2x, 4x, 8x, 16x

Constraint

Can be called in the following states: "READY, "PLAYING", "PAUSED"
For the general HTTP and HTTPS, the supported playback rate is -8x ~ 8x. (Repeated seek) Please refer to the specification for the supported range of other streaming types.

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


try {
	webapis.avplay.setSpeed(2);
	} 
	catch (e) 
	{
	console.log(e);
	}

setListener

Sets asynchronous callback methods for player information notifications, such as buffering progress, player information, playback mode, and DRM mode information.


void setListener(AVPlayPlaybackCallback playbackCallback);

Product : Smart Signage

Parameters:

playbackCallback: AVPlayPlaybackCallback

Constraint

Can be called in the following states: "NONE", "IDLE" (recommended), "READY", "PLAYING", "PAUSED"
To avoid missing necessary information, the onbufferingstart, onbufferingprogress, onbufferingcomplete, onerror, onevent, and ondrmevent listeners must be set during the "IDLE" state.

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type UnknownError, for any other error.

Code example:


var Listener = {
	onbufferingstart: function() {
		console.log("Buffering start.");
		},
		onbufferingprogress: function(percent) {
			console.log("Buffering progress data : " + data1);
		},
		onbufferingcomplete: function() {
			console.log("Buffering complete.");
		},
		oncurrentplaytime: function(currentTime) {
			console.log("Current Playtime : " + data1);
		},
		onbufferingcomplete: function() {
			console.log("Buffering complete.");
		},
		onevent: function(eventType, eventData) {
			console.log("event type error : " + eventType + ", data: " + eventData);
		},
		onerror: function(eventType) {
			console.log("event type error : " + eventType);
		},
		ondrmevent: function(drmEvent, drmData) {
			console.log("DRM callback: " + drmEvent + ", data: " + drmData);
		},
		onstreamcompleted: function() {
			console.log("Stream Completed");
		}
	}
webapis.avplay.setListener(Listener);

setDrm

Updates the DRM information, such as SetProperties . You can change the DRM mode and run the control feature. The AVPlayDrmOperation and jsonParam parameters depend on the DRM type. Please refer to the specification for the supported DRM.


DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam);

Product : Smart Signage

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/drmplay

Parameters

drmType: AVPlayDrmType {"LYNK"}
jsonParam: DOMString DRM parameter represented by JSON string. You can use the JSON.stringify method to generate the JSON string.

Return value:

DRMString

Constraint

Can be called in the following states: "IDLE"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type SecurityError, if the application does not have the privilege to call this method.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.
  Examples of exception scenarios include an invalid DRM session, or failure to create the underlying DRM module or configuration. In these scenarios, an exception is thrown and the method call returns FALSE.

Code example:


			
//  LYNK DRM example: 

var Player = webapis.avplay;
var url =”udp://Multicast_IP_Address:Port”; // 'rtp://Multicast_IP_Address:Port'
var listener =function() {
    onevent: function(eventType, eventData) {
          console.log("event type error : " + eventType + ", data: " + eventData);
    },
    ondrmevent: function(drmEvent, drmData) {
          console.log("DRM callback: " + drmEvent + ", data: " + drmData);
  },
    onerror: function(eventType) {
          console.log("event type error : " + eventType);
  }
} 
var drmParam = {
	LYNKServer:"NONE", // No LYNK server required
	type: "1"
};
try {
	Player.open(url);
	Player.setDisplayRect(0, 0, 1920, 1080);
	Player.setListener(listener);
	Player.setDrm("LYNK", "Initialize", JSON.stringify(drmParam));
	Player.prepareAsync(function() {
		Player.play();
	});		
} catch (error) {
	    console.log("Error name = "+ error.name + ", Error message = " + error.message);
}

Remark :

'LYNK TYPE-1 DRM supported. ONLY UDP/RTP streaming protocol supported. B2BAVPlay.js library file should be included in web application to play multicast streaming. This API start supported from Smart Signage 3.0.

setDisplayMethod

Sets the video screen mode in the specified display area.


void setDisplayMethod(AVPlayDisplayMode displayMode);

Product : Smart Signage

Parameters:

displayMode: "PLAYER_DISPLAY_MODE_LETTER_BOX", "PLAYER_DISPLAY_MODE_FULL_SCREEN", or "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO"

Constraint

Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.setDisplayMethod("PLAYER_DISPLAY_MODE_FULL_SCREEN");

setDisplayRotation

Sets the rotation settings of the video surface display in anti-clockwise direction. If no display is set, no operation would be performed. Use this method to change the video orientation to portrait mode.


void setDisplayRotation(AVPlayDisplayRotation displayRotation);

Product : Smart Signage

Parameters:

displayMode: "PLAYER_DISPLAY_ROTATION_90", "PLAYER_DISPLAY_ROTATION_180", "PLAYER_DISPLAY_ROTATION_270","PLAYER_DISPLAY_ROTATION_0"

Constraint

Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.setDisplayRotation("PLAYER_DISPLAY_ROTATION_90");

setVideoStillMode

This API can be used to set video still mode. This is useful API, in scenario where playback switch from one content to other in seamless manner. In case of still mode true, last frame would continue to display on screen even after stopping the video.


void setVideoStillMode(boolean bStillMode);

Product : Smart Signage

Parameters:

bStillMode:: " "true" means still mode is required, "false" means still mode is not required"

Constraint

Can be called in the following states: "NONE"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


webapis.avplay.setVideoStillMode("true");                                                                                                                                                   
    // For seamless Example-                                                                                                                                                                     
  var player1 = webapis.avplaystore.getPlayer();
  var player2 = webapis.avplaystore.getPlayer(); 

listener2 = {
    onstreamcompleted: function() {
    player2.setVideoStillMode("true");
    player2.stop();
    player1.open(“http://test.com/test1.mp4”);
    player1.setListener(listener1);
    player1.setDisplayRect(0, 0, 1920, 1080);
    player1.prepare();
    player1.setVideoStillMode("false");
    player1.play();
};
listener1 = {
    onstreamcompleted: function() {
    player1.setVideoStillMode("true");
    player1.stop();
    player2.open(“http://test.com/test2.mp4”);
    player2.setListener(Listener2);
    player2.setDisplayRect(0, 0, 1920, 1080);
    player2.prepare();
    player2.setVideoStillMode("false");
    player2.play();
};
try
{
       player1.open(“http://test.com/test1.mp4”);
       player1.setListener(listener1);
       Player1.setDisplayRect(0, 0, 1920, 1080);
       player1.avplay.prepare();
       player1.avplay.play();
  }
 catch (e)
 {
       console.log(e);
 }

Remark :

This API is supported only for http streaming (.mp4). Hence webapis.js must be included for this method. b2bavplay.js doesn’t support this.

setStreamingProperty

Sets specific feature values for HTTP, MMS, or specific streaming engine (Smooth Streaming, HLS, DASH, DivX Plus Streaming, or Widevine). The available streaming properties depend on the streaming protocol or engine.
Use the CUSTOM_MESSAGE property for streaming engine or CP-specific settings.


void setStreamingProperty(AVPlayStreamingPropertyType propertyType, DOMString propertyParam);

Product : Smart Signage

Parameters:

propertyType: { "COOKIE", "USER_AGENT", "PREBUFFER_MODE" , "ADAPTIVE_INFO", "SET_MODE_4K", "PROPERTY_HD_AUDIO", "LISTEN_SPARSE_TRACK","WIDEVINE,"USE_VIDEOMIXER","SET_MIXEDFRAME" };
propertyParam: Value according to the propertyType. e.g. "ADAPTIVE_INFO" PropetyTypes are "BITRATES", "STARTBITRATE", "SKIPBITRATE", "FIXED_MAX_RESOLUTION".

Constraint

Can be called in the following states: "IDLE"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


//Smooth Streaming example:
var BitRateString = "BITRATES=5000~10000|STARTBITRATE=HIGHEST|SKIPBITRATE=LOWEST"; webapis.avplay.setStreamingProperty("ADAPTIVE_INFO", BitRateString);

//Prebuffer mode example:
webapis.avplay.setStreamingProperty("PREBUFFER_MODE", time_in_miliseconds);

Player1 => Playback of Main Content
Player2 => Playback of advertisement (Buffered the ad content before playback).
Player1 = webapis.avplaystore.getPlayer();
Player2 = webapis.avplaystore.getPlayer();
Player1.open('http://www.example.com/example_1.mp4');
Player1.setDisplayRect(x, y, width, height);
Player1.prepare();
Player1.play();
Player2.open('http://www.example.com/example_2.mp4');
Player2.setStreamingProperty("PREBUFFER_MODE", "5000");
Player2.setDisplayRect(x, y, width, height);
Player2.prepare();
Player1.stop();
Player2.play();

//User-agent example:
webapis.avplay.setStreamingProperty("USERAGENT", "samsungsmooth-agent/1.1");

//Setting resolution information for HLS/DASH
webapis.avplay.setStreamingProperty("ADAPTIVE_INFO", "FIXED_MAX_RESOLUTION=7680X4320");

Remark :

"WIDEVINE" unit has been deprecated from Tizen version 4.0
"PROPERTY_HD_AUDIO" unit has been deprecated from Tizen version 2.4

getStreamingProperty

Retrieves a specific property value obtained by the streaming engine (Smooth Streaming, HLS, DASH, or Widevine).


DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType);

Product : Smart Signage

Parameters:

propertyType: AVPlayStreamingPropertyType { "IS_LIVE", "AVAILABLE_BITRATE", "GET_LIVE_DURATION","CURRENT_BANDWIDTH"};

Return value:

DOMString Property value

Constraint

Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


var Text = 'AVAILABLE_BITRATE: ' + webapis.avplay.getStreamingProperty ("AVAILABLE_BITRATE") ;
 Text += 'CURRENT_BANDWIDTH: ' + webapis.avplay.getStreamingProperty ("CURRENT_BANDWIDTH") + '';
 Text += 'IS_LIVE: ' + webapis.avplay.getStreamingProperty ("IS_LIVE") +'';

@endparblock @code
 var StartTime = webapis.avplay.getStreamingProperty("GET_LIVE_DURATION").split('|')[0];
 var EndTime = webapis.avplay.getStreamingProperty("GET_LIVE_DURATION").split('|')[1];

 if (StartTime > targetSeekTime)
 { 
     if (EndTime < targetSeekTime)
    {
        webapis.avplay.seekTo(targetSeekTime); //ms
    }
  }

Remark :

GET_SERVER_TIME_SCALE and GET_ABSOLUTE_SERVER_TIME: Supported for Smooth Streaming only.

getVersion

Retrieves the AVPlay version.


DOMString getVersion();

Product :Smart Signage

Return value:

DOMString string current version

Constraint

Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


var Version = webapis.avplay.getVersion();

suspend

Pauses the player state when the application is sent to the background. Saves the current statistics for the ongoing playback session.


void suspend();

Product : Smart Signage

Constraint

Can be called in the following states: "READY, "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


document.addEventListener("visibilitychange", function() 
{
  if(document.hidden)
  {
    // Something you want to do when application is paused.
    console.log("lifecycle [pause]");
    webapis.avplay.suspend();
  } 
  else 
  {
    // Something you want to do when application is resumed.
    console.log("lifecycle [resume]");
    webapis.avplay.restore();
  }
});

restore

During multitasking, restores the player state when the application is resumed. For live streaming or DRM-encrypted content playback, you must check whether the streaming URL has changed or the DRM session or license has expired, and specify the new URL and DRM information as needed.


void restore(DOMString URL, optional unsigned long? resumeTime, optional boolean? bPrepare);

Product : Smart Signage

Parameters

URL: updated URL after suspend. If null, the stored URL is used.
For live streaming or DRM-encrypted content playback, in case the URL has changed or the DRM license or session has expired, checking for and passing the newest URL is recommended.
resumeTime: (milliseconds) Optional. Position from which to resume playback. If 0, the stored position is used.
For live streaming, this parameter is not meaningful. Do not pass 0 for this parameter.
For DRM-encrypted content playback, if the DRM session has expired, to recreate the playback pipeline, pass 0 for this parameter.
bPrepare: Optional boolean. false (default): Player sets the resume behavior automatically. true: Player does not resume automatically. The application must invoke the prepare and play methods.
For live streaming, this parameter is not meaningful. Do not pass true for this parameter.
For DRM-encrypted content playback: if the DRM session has expired, pass true for this parameter.

Constraint

Can be called in the following states: "NONE", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


document.addEventListener("visibilitychange", function() 
{
  if(document.hidden)
  {
    // Something you want to do when application is paused
    console.log("lifecycle [pause]");
    webapis.avplay.suspend();
  }
  else
  {
    // Something you want to do when application is resumed
    console.log("lifecycle [resume]");
    webapis.avplay.restore(url, 0, false);
  }
});

restoreAsync

During multitasking, restores the player state when the application is resumed.restoreAsync is an asynchronous interface.
Other API, restore is a synchronous interface which blocks the application thread. This method is preferred over restore because it returns immediately and does not block the application thread during its restoration.
When player is restored successful, the success callback is returned and player resumed the playback from the restored playback position, state, properties etc. If restoration fails, the error callback returns the error value.
Application is required to make further calls to avplay on its success or failure callback happens.
For live streaming or DRM-encrypted content playback, you must check whether the streaming URL has changed or the DRM session or license has expired, and specify the new URL and DRM information as needed.


void restoreAsync(DOMString URL, optional unsigned long? resumeTime, optioanl boolean? bPrepare, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product : Smart Signage

Parameters

URL: updated URL after suspend. If null, the stored URL is used.
For live streaming or DRM-encrypted content playback, in case the URL has changed or the DRM license or session has expired, checking for and passing the newest URL is recommended.
resumeTime: (milliseconds) Optional. Position from which to resume playback. If 0, the stored position is used. For live streaming, this parameter is not meaningful. Do not pass 0 for this parameter. For DRM-encrypted content playback, if the DRM session has expired, to recreate the playback pipeline, pass 0 for this parameter.
bPrepare: Optional boolean. false (default): Player sets the resume behavior automatically. true: Player does not resume automatically. The application must invoke the prepare and play methods.
For live streaming, this parameter is not meaningful. Do not pass true for this parameter.
For DRM-encrypted content playback: if the DRM session has expired, pass true for this parameter.
successCallback: Callback method to invoke when the call is successful
errorCallback: Callback method to invoke when an error occurs

Constraint

Can be called in the following states: "NONE", "PLAYING", "PAUSED"

Exceptions:

WebAPIException
- with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
- with error type NotSupportedError, if this feature is not supported.
- with error type InvalidValuesError, if any input parameter contains an invalid value.
- with error type InvalidStateError, if it is called in an invalid state.
- with error type UnknownError, for any other error.

Code example:


document.addEventListener("visibilitychange", function() 
{
	if(document.hidden)
	{
		// Something you want to do when application is paused
		console.log("lifecycle [pause]");
		webapis.avplay.suspend();
	}
	else 
	{
		// Something you want to do when application is resumed
		console.log("lifecycle [resume]");
		try 
		{
			var successCallback = function()
			{
			console.log("success");
			}
			var errorCallback = function(err)
			{
			throw new Error('Error:' + err.name);
			}
			webapis.avplay.restoreAsync(url, 0, false, successCallback, errorCallback);
		} 
		catch (e) 
		{
			console.log(e);
		}
	}
});

2.4. AVPlayPlaybackCallback

Defines callbacks for buffering and playback notifications.


[Callback=FunctionOnly, NoInterfaceObject] interface AVPlayPlaybackCallback{
  void onbufferingstart();
  void onbufferingprogress(unsigned long percent);
  void onbufferingcomplete();
  void oncurrentplaytime(unsigned long currentTime );
  void onstreamcompleted();
  void onevent(AVPlayEvent eventid, DOMString data );
  void onerror(AVPlayError eventid);
  void ondrmevent(AVPlayDrmType type, drmData data);
  void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, AVPlaySubtitleAttribute attributes);
};

Methods

onbufferingstart

Callback method for asynchronous buffering started notifications.


void onbufferingstart();

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onbufferingstart: function() 
{
  console.log("Buffering start.");
}

onbufferingprogress

Callback method for asynchronous buffering progress notifications.


void onbufferingprogress(unsigned long percent);

Parameters:

percent: unsigned long

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onbufferingprogress: function(percent) 
{
  console.log("Buffering progress data : " + percent);
}

onbufferingcomplete

Callback method for asynchronous buffering complete notifications.


void onbufferingcomplete();

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onbufferingcomplete: function()
{
  console.log("Buffering complete.");
}

oncurrentplaytime

Callback method for the current playback time.


void oncurrentplaytime(unsigned long currentTime );

Parameters:

currentTime: unsigned long

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


oncurrentplaytime: function(currentTime)
{
  console.log("Current playtime: " + currentTime);
}

onstreamcompleted

Callback method for asynchronous playback finished notifications.


void onstreamcompleted();

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onstreamcompleted: function(currentTime)
{
  console.log("Stream Completed");
}

onevent

Callback method for asynchronous event notifications.


void onevent(AVPlayEvent eventid, DOMString data );

Parameters:

eventid: AVPlayEvent object
data: DOMString

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onevent: function(eventType, eventData)
{
  console.log("OnEvent Callback with eventType: " + eventType);
}

onerror

Callback method for AVPlay error notifications.


void onerror(AVPlayError eventid);

Parameters:

eventid: AVPlayError object

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onerror: function(eventType)
{
  console.log("OnError Event Callback with eventType: " + eventType);
}

ondrmevent

Callback method for DRM information notifications.


void ondrmevent(AVPlayDrmType type, drmData data);

Parameters:

type: AVPlayDrmType object
data: drmData

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


ondrmevent: function(drmType, drmData) 
{
 console.log("DRM callback, type: " + drmType + ", data: " + drmData);
 if(drmData.name === 'Challenge')
 {
	var ChallengeData = 
	{
	"NAME": drmData.name,
	"SESSION_ID": drmData.session_id,
	"CHALLENGE": drmData.challenge,
	"CHALLENGE_LEN": drmData.challenge_len,
	"SERV_URL": drmData.serverurl,
	"SERV_URL_LEN": drmData.serverurl_len
	} 
	// Use challenge data to get drm license.
 } 
 else if (drmData.name === 'DrmError') 
 {
	 var ErrorInfo = 
	 {
		 "NAME": drmData.name,
		 "ERROR_CODE": drmData.code,
		 "ERROR_MESSAGE": drmData.message // Generally, it's human readable message.
	}
 }
}

onsubtitlechange

Callback method for asynchronous subtitle change notifications.


void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, AVPlaySubtitleAttribute attributes);

Parameters:

duration: unsigned long
subtitles: DOMString
type: unsigned long
attriCount: unsigned long
attributes: AVPlaySubtitleAttribute "attr_type": "AttributeType:value"; "start_pos": start position as long; "stop_pos": stop position as long

Exceptions:

WebAPIException
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, for any other error.

Code example:


onsubtitlechange: function(duration, text, data3, data4)
{
  console.log("Subtitle Changed.");
}

3. Full WebIDL


module AVPlay {
  enum AVPlayPlayerState {
    "NONE",
    "IDLE",
    "READY",
    "PLAYING",
    "PAUSED"
  };

  enum AVPlayDisplayMode { 
    "PLAYER_DISPLAY_MODE_LETTER_BOX", 
    "PLAYER_DISPLAY_MODE_FULL_SCREEN",
    "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO" 
  };

  enum AVPlayBufferOption { 
    "PLAYER_BUFFER_FOR_PLAY", 
    "PLAYER_BUFFER_FOR_RESUME" 
  };

  enum AVPlayBufferSizeUnit {
    "PLAYER_BUFFER_SIZE_IN_BYTE", 
    "PLAYER_BUFFER_SIZE_IN_SECOND" 
  };

  enum AVPlayStreamingPropertyType { 
    "COOKIE", 
    "USER_AGENT", 
    "PREBUFFER_MODE", 
    "ADAPTIVE_INFO",  
    "SET_MODE_4K", 
    "PROPERTY_HD_AUDIO", 
    "LISTEN_SPARSE_TRACK", 
    "IS_LIVE", 
    "AVAILABLE_BITRATE", 
    "GET_LIVE_DURATION", 
    "CURRENT_BANDWIDTH", 
    "WIDEVINE"
  };

  enum AVPlayDrmType {
    "PLAYREADY", 
    "VERIMATRIX", 
    "WIDEVINE_CDM"
  };

  enum AVPlayDrmOperation { 
    "SetProperties", 
    "InstallLicense", 
    "ProcessInitiator", 
    "GetUID", 
    "Initialize", 
    "Finalize", 
    "widevine_license_data", 
    "widevine_app_session", 
    "widevine_data_type" 
  };

  enum AVPlayStreamType { 
    "VIDEO", 
    "AUDIO", 
    "TEXT" 
  };

  enum AVPlayError{
    "PLAYER_ERROR_NONE",
    "PLAYER_ERROR_INVALID_PARAMETER",
    "PLAYER_ERROR_NO_SUCH_FILE",
    "PLAYER_ERROR_INVALID_OPERATION",
    "PLAYER_ERROR_SEEK_FAILED",
    "PLAYER_ERROR_INVALID_STATE",
    "PLAYER_ERROR_NOT_SUPPORTED_FILE",
    "PLAYER_ERROR_INVALID_URI",
    "PLAYER_ERROR_CONNECTION_FAILED",
    "PLAYER_ERROR_GENEREIC"
  };

  enum AVPlayEvent {
    "PLAYER_MSG_NONE",
    "PLAYER_MSG_RESOLUTION_CHANGED",
    "PLAYER_MSG_BITRATE_CHANGE",
    "PLAYER_MSG_FRAGMENT_INFO",
    "PLAYER_SPARSE_TRACK_DETECT",
    "PLAYER_STREAMING_EVENT",
    "PLAYER_MSG_HTTP_ERROR_CODE",
    "PLAYER_MSG_DRM_CHALLENGE_DATA"
  };

  dictionary AVPlayStreamInfo {
    unsigned long index;
    unsigned long adaption_index;
    unsigned long alternate_index;
    AVPlayStreamType type;
    DOMString extra_info;
  };

  dictionary AVPlaySubtitleAttribute {
    DOMString attr_type;
	long start_pos;
	long stop_pos;
  };

  [NoInterfaceObject] interface AVPlayManagerObject {
    readonly attribute AVPlayManager avplay;
  };

  WebApi implements AVPlayManagerObject;

  [NoInterfaceObject] interface AVPlayManager {
    void open(DOMString url);
    void close();
    void prepare();
    void prepareAsync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    void setDisplayRect( unsigned long x, unsigned long y, unsigned long width, unsigned long height );
    void play();
    void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    void stop();
    AVPlayPlayerState getState();
    void pause();
    void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback );
    unsigned long getDuration() ;
    unsigned long getCurrentTime() ;
    void setTimeoutForBuffering(unsigned long seconds);
    void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);
    void setSpeed(long playbackSpeed);
    void setListener(AVPlayPlaybackCallback playbackCallback);
    DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam);
    DOMString getUID ( AVPlayDrmType drmType )
    void setSoundAnalysisListener (AVPlaySoundAnalysisCallback soundAnalysisCallback);
    void unsetSoundAnalysisListener();
    void setSilentSubtitle(boolean onoff);
    void setExternalSubtitlePath(DOMString filePath);
    void setSubtitlePosition(long position);
    void setDisplayMethod(AVPlayDisplayMode displayMode);
    void setSelectTrack(AVPlayStreamType trackType, long trackIndex);
    AVPlayStreamInfo getCurrentStreamInfo();
    AVPlayStreamInfo[] getTotalTrackInfo();
    void setStreamingProperty(AVPlayStreamingPropertyType propertyType, DOMString propertyParam);
    DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType);
    DOMString getVersion();
    void suspend() ;
    void restore(DOMString URL, unsigned long resumeTime, boolean bPrepare);
    void restoreAsync(DOMString URL, optional unsigned optional long? resumeTime, optioanl optional boolean? bPrepare, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) ;
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface AVPlayPlaybackCallback{
    void onbufferingstart();
    void onbufferingprogress(unsigned long percent);
    void onbufferingcomplete();
    void oncurrentplaytime(unsigned long currentTime );
    void onstreamcompleted();
    void onevent(AVPlayEvent eventid, DOMString data );
    void onerror(AVPlayError eventid);
    void ondrmevent(AVPlayDrmType type, drmData data);
    void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, AVPlaySubtitleAttribute attributes);
  };
};

GUIDE

AVPlay API

Table of Contents

Summary of Interfaces and Methods

Attributes

Methods

Methods