AVPlayExtension API

This method instantiates the player object and takes the content URL as the input parameter.

void open(DOMString url);

Product : B2B (HTV)

Constraint :

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

Privilege Level : Partner

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

Parameters :

• url : The URL of content to play. It supports UDP and RTP multicast URLs

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters contains an invalid value
  • with error type InvalidStateError, if it is called in an invalid state
  • with error type UnknownError in any other error case

Code Example :

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

This method destroys the AVPlay object.

void close();

Product : B2B (HTV)

Constraint :

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

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

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

This method prepares the media player for playback. The Player must have been created beforehand with a valid URI. This prepare method is synchronous. Hence, the calling context would be blocked until the player is prepared.

void prepare();

Product : B2B (HTV)

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 InvalidValuesError, if the given URL through open() is invalid. //For example, webapis.avplay.open("InvalidURL")
  • with error type InvalidAccessError, if the given URL through open() is valid but have outside multicast range. //For example, webapis.avplay.open("udp://219.10.10.10")
  • with error type InvalidStateError, if it is called in an invalid state
  • with error type UnknownError in any other error case

Code Example :

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

This method prepares the media player for playback, asynchronously. This API prepares the MM core module, asynchronously. It means that the internal media elements will change the state, asynchronously.
We recommend this asynchronous prepareAsync call instead of the prepare call which is synchronous API which blocks the entire application during its execution.
prepareAsync() returns immediately, rather than blocking until enough data has been buffered.
Since this works in asynchronous model, this does not block the executing thread and the application is responsive during its execution.
When prepareAsync() gets successfully completed, it returns with successCallback and player reached in READY state. For some reason, e.g. network error, it returns with errorCallback with error value.

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

Product : B2B (HTV)

Constraint :

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

Parameters :

• successCallback [optional][nullable] : Callback method to be invoked when this api is successful
• errorCallback [optional][nullable] : Callback method to invoke when an error occurs. This function has one parameter which shows the following errorTypes
  NotSupportedError, if this feature is not supported
  InvalidValuesError, if the given URL through open() is invalid. e.g., webapis.avplay.open("InvalidURL")
  InvalidAccessError, if the given URL through open() is valid, but does not exist or Network Issue. e.g., webapis.avplay.open("http://abc")
  InvalidStateError, if it is called in an invalid state
  UnknownError, for any other error

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if an input parameter is not compatible with the expected type

Code Example :

webapis.avplay.prepareAsync = function (successCallback, errorCallback) {
  if (typeof successCallback === 'undefined') { successCallback = null; }
  if (typeof errorCallback === 'undefined') { errorCallback = null; }
  try {
    webapis.epavplay.prepareAsync(successCallback, errorCallback);
  } catch (e) {
    logError(e);
    throw (e);
  }
};

This method sets the display area for playing the video content on the TV screen. It should be called for showing the video after calling an open method.
App's default resolution is 1920x1080. It needs 4 parameters (left,top,width,height) that always use 1920 x 1080 coordinate system regardless of your application resolution.

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

Product : B2B (HTV)

Constraint :

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

Parameters :

• x : coordinate of the display area in the TV screen coordinates. This x value is smaller than the TV screen width
• y : coordinate of the display area in the TV screen coordinates. This y value is smaller than the TV screen height
• width : The width of the display area. This value is smaller than the width of the TV screen
• height : The height of the display area from the source image. This value is smaller than the height of the source image

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters contains an invalid value
  • with error type InvalidStateError, if it is called in an invalid state
  • with error type UnknownError in any other error case

Code Example :

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

This method starts the playback of the stream.

void play();

Product : B2B (HTV)

Constraint :

• Can be called in the following states: "READY", "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 in any other error case

Code Example :

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

This method stops the player and hence any video that is currently being played.

void stop();

Product : B2B (HTV)

Constraint :

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

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

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

This method returns the current state of the underlying player which is associated with the AVPlay object.

AVPlayPlayerState getState();

Product : B2B (HTV)

Constraint :

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

Return Value :

• AVPlayPlayerState : returns the state of the player "NONE", "IDLE", "READY", "PLAYING", "PAUSED".

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

var bRet = webapis.avplay.getState();

This method returns the current play time in milliseconds.

unsigned long getCurrentTime();

Product : B2B (HTV)

Constraint :

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

Return Value :

• unsigned long : Current Playback time in milliseconds.

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

var currentPlayTime = webapis.avplay.getCurrentTime();

This method is used in order to obtain the Player information, the DRM mode information etc., and the Callback function is registered. When the relevant Event occurs, the relevant Callback function gets called asynchronously.

void setListener(AVPlayPlaybackCallback playbackCallback);

Product : B2B (HTV)

Constraint :

• Can be called in the following states: "NONE", "IDLE" (recommended), "READY", "PAUSED", "PLAYING"
  But it is highly recommended to call this API just after PLAYER_STATUS_IDLE. For onerror, onevent, ondrmevent, it must be in PLAYER_STATUS_IDLE (i.e. just after player is created), otherwise the necessary information will be missed.

Parameters :

• playbackCallback : AVPlayPlaybackCallback

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters contains an invalid value
  • with error type UnknownError in any other error case

Code Example :

var listener = {
  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);
  }
}

webapis.avplay.setListener(listener);

This method updates the DRM information, such as SetProperties, etc. It changes the DRM mode, and runs the Control feature. Every DRM has difference between AVPlayDrmOperation and jsonParam.

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

Product : B2B (HTV)

Constraint :

• Can be called in the following states: "IDLE"

Privilege Level : Public

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

Parameters :

• drmType : is the type of the DRM
• drmOperation : AVPlayDrmOperation : This is a string parameter which specifies the DRM operation to be performed for the current playback session.
  It can have these values{"Initialize", "Finalize" }
  "SetProperties" : This operation is used when the DRM related information is stringified in "json_string" format and passed along with this operation.
  This is mainly used for setting the DRM information like license server, etc.
  //Example : setting license server. Some of the code examples are given below.
• jsonParam : DOMString DRM parameter represented by JSON string not object. The application can call JSON.stringify() to generate JSON string in java script. The above given DRM operation examples could be stringified in this json_string param

Return Value :

• DOMString : "true" in case of success and "false" if fails.

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters 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, "NONE"
  • with error type UnknownError in any other error case
    During failure scenarios this API would post an exception. The following could be the possible exception scenarios:
    DRM Create failed : if creation of the underlying DRM module failed, an exception would be sent back with "FALSE" return status of this API call.
    Invalid DRM session : if an invalid DRM session is detected, an exception would be sent back with "FALSE" return status of this API call.
    DRM configuration failure : if a DRM configuration failure is detected, an exception would be sent back with "FALSE" return status of this API call.

NOTE : if you use this API, a special privilege level is required.
Insert the http://developer.samsung.com/privilege/drmplay in the config.xml file of the web application. Check below example
<tizen:privilege name="http://developer.samsung.com/privilege/drmplay"/>

Code Example :

//(Example) ProIdiom (setting forensic data)
var drmParam = new Object();
drmParam.ForensicData    = "XXXXXXX";
playerObj.setDrm("PROIDIOM", "Initialize", JSON.stringify(drmParam));
//(Example) LYNKDRM (setting type and lynk server)
var drmParam = new Object();
drmParam.type ="2";
drmParam.LYNKServer="xxx.xxx.xxx.xxx:xxxxx";
playerObj.setDrm( "LYNK", "Initialize", JSON.stringify(drmParam));

This method sets the Video Screen Mode within the given DISPLAY area.

void setDisplayMethod(AVPlayDisplayMode displayMode);

Product : B2B (HTV)

Constraint :

• Can be called in the following states: "IDLE", "PAUSED", "READY", "PLAYING"
  LIMITATION : This API works when set as setDisplayRect(0,0,1920,1080)

Parameters :

• displayMode : could be one of "PLAYER_DISPLAY_MODE_LETTER_BOX", "PLAYER_DISPLAY_MODE_FULL_SCREEN", "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO"

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters contains an invalid value
  • with error type InvalidStateError, if it is called in an invalid state
  • with error type UnknownError in any other error case

Code Example :

webapis.avplay.setDisplayMethod("PLAYER_DISPLAY_MODE_FULL_SCREEN");

This method is used with Multi Audio/Subtitle, when you want to change the Audio and Subtitle while playing.

void setSelectTrack(AVPlayStreamType trackType, long trackIndex);

Product : B2B (HTV)

Constraint :

• Can be called in the following state: "PLAYING"

Parameters :

• trackType : It may be AUDIO or TEXT value
• trackIndex : It sets the index value of the AVPlayStreamInfo obtained through the webapis.avplay.getTotalTrackInfo Function

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters contains an invalid value
  • with error type InvalidStateError, if it is called in an invalid state
  • with error type UnknownError in any other error case

Code Example :

var totalTrackInfo = webapis.avplay.getTotalTrackInfo();
for (var i=0; i<totalTrackInfo.length; i++) {
  if(totalTrackInfo.type == 'TEXT') {
    console.log('Find subtitle track.');
    console.log('subtitle track index is ' + totalTrackInfo.index);
    console.log('subtitle track language is ' + totalTrackInfo.extra_info.track_lang);
  }
}
//For example, choose the subtitle track index number 2.
webapis.avplay.setSelectTrack('TEXT',2);

This method gets the currently playing Streams Video, Audio, and Subtitle information. It informs that a Stream is playing.

AVPlayStreamInfo getCurrentStreamInfo();

Product : B2B (HTV)

Constraint :

• Can be called in the following states: "PLAYING"

Return Value :

• AVPlayStreamInfo : AVPlayStreamInfo structure containing tracktype, extraInfo and Index of current stream

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 in any other error case

Code Example :

var streamInfo = webapis.avplay.getCurrentStreamInfo();
var text = '';
for (var i = 0; i < streamInfo.length; i++) {
  text += 'index: ' + streamInfo[i].index + '';
  text += 'type: ' + streamInfo[i].type + '';
  text += 'extra_info: ' + streamInfo[i].extra_info + '';
}
All of stream type has extra_info which is JsonString.
//video extra_info example : "{fourCC:"H264","Width":"1920","Height":"1080","Bit_rate":" 477000"}"
//audio extra_info example : "{"language":"fr","channels":"2","sample_rate":"48000","bit_rate":"256000","fourCC":"mpeg","track_lang":"fra","audio_type":"0"}"
//text(subtitle) extra_info example : "{"track_lang":"eng","subtitle_type":"0","pid":"258","subtitle_mode":"0"}"
In the case of invalid Stream, the DOMString becomes null and the index value becomes -1.

This method gets the currently playing Streams information.

AVPlayStreamInfo[] getTotalTrackInfo();

Product : B2B (HTV)

Constraint :

• Can be called in the following state: "PLAYING"

Return Value :

• AVPlayStreamInfo : AVPlayStreamInfo[] structure containing the tracktype, extraInfo, and the Index of current stream
  It returns information for all the available tracks for the entire stream that is available in the current playback. The following structure is used to send the information back to the caller:
  For video tracks:
  "{"fourCC":"%s","Width":"%u","Height":"%u","Bit_rate":"%u"}"
  For audio track:
  "{"language":"%s","channels":"%d","sample_rate":"%d","bit_rate":"%d","fourCC":"%s","track_lang":"%s","audio_type":"%d"}"
  For subtitle tracks:
  "{"track_lang":"%s","subtitle_type":"%d","pid":"%d","subtitle_mode":"%s"}"

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 in any other error case

Code Example :

var trackInfo = webapis.avplay.getTotalTrackInfo();
var text = 'type of track info: ' + typeof trackInfo + '';
text += 'length: ' + trackInfo.length + '';
for (var i = 0; i<trackInfo.length; i++) {
  text += 'index: ' + trackInfo[i].index + '';
  text += 'type: ' + trackInfo[i].type + '';
  text += 'extra_info: ' + trackInfo[i].extra_info + '';
}

This method sets the value for a specific feature in the UDP/RTP playback.

void setStreamingProperty(AVPlayStreamingPropertyType propertyType, Any propparam);

Product : B2B (HTV)

Constraint :

• Can be called in the following player state: "IDLE"

Parameters :

• propertyType : property type to be set to the player
• propparam : Value according to the propertyType. e.g. "ENABLE_TTX" PropetyTypes are true, false, and for the "SET_INTERACTIVE_MODE" mode is 1 with latency in milliseconds

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if the input parameter is not compatible with the expected type
  • with error type NotSupportedError, if this feature is not supported
  • with error type InvalidValuesError, if any of the input parameters contains an invalid value
  • with error type InvalidStateError, if it is called in an invalid state
  • with error type UnknownError in any other error case

Code Example :

//set interactive mode example :
var propparam = new Object();
propparam.mode ="1";
propparam.latency="100"; //latency in ms
webapis.avplay.setStreamingProperty("SET_INTERACTIVE_MODE", propparam);
//Enable ttx mode example :
webapis.avplay.setStreamingProperty("ENABLE_TTX", true);

This method gets the version of avplay.

DOMString getVersion();

Product : B2B (HTV)

Constraint :

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

Return Value :

• DOMString : DOMString string
  current version

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

var version = webapis.avplay.getVersion();

This method sets the rotation settings of the video surface display. If no display is set, no operation is performed. Use this method to change the video orientation to portrait mode. This API call will change the origin of the coordinates. Hence, the application should call setDisplayRect() again after calling this API.

void setDisplayRotation(DOMString displayRotation);

Product : B2B (HTV)

Constraint :

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

Parameters :

• displayRotation : The rotation of the display. The valid values for the display rotation are "PLAYER_DISPLAY_ROTATION_NONE", "PLAYER_DISPLAY_ROTATION_90", "PLAYER_DISPLAY_ROTATION_180", "PLAYER_DISPLAY_ROTATION_270"

Exceptions :

• WebAPIException
  • with error type TypeMismatchError, if an input parameter is not compatible with the 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");

This method gets called async when some kind of event (other event) is received from the player.

void onevent(AVPlayEvent eventid, DOMString data);

Parameters :

• eventid : ID of the event triggered by the player
• data : description of the event received from the player

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

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

This method gets called when an error event is received from the player.

void onerror(AVPlayError eventid);

Parameters :

• eventid : ID of the error event trigerred by the player

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

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

This method gets called when the DRM information is received from the player.

void ondrmevent(AVPlayDrmType type, DRMData data);

Parameters :

• type : DRM type
• data : Detailed information about the DRM event received from the player
  {
  readonly attribute name : name for the message, means an error occurred during the DRM processing.
  readonly attribute code : signifies the DRM error code
  readonly attribute message : DRM error message
  readonly attribute reserved : not currently applicable
  }

Exceptions :

• WebAPIException
  • with error type NotSupportedError, if this feature is not supported
  • with error type UnknownError in any other error case

Code Example :

ondrmevent: function(type, data) {
  console.log("DRM callback: " + type + ", data: " + data);
  
  var ErrorInfo = {
    "NAME": data.name,
    "ERROR_CODE": data.code,
    "ERROR_MESSAGE": data.message // Generally, the error message is human readable.
  }
}