Samsung Electronics logo

Samsung Web API: AVPlay


Introduction

This API provides access to playback of media content on a Smart TV or Bluelay Disk Player (BD) or Monitor device.

There will be a webapis.avplay object provides access to the functionality of the avplay API.

For more information on the AV Play features, see AV Play Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
WebAPIsAVPlayManager
AVPlayManager void getAVPlay(AvailableAVPlaySuccessCallback successCallback, ErrorCallback? errorCallback)
AvailableAVPlaySuccessCallback void onsuccess(AVPlay obj)
BufferingCallback void onbufferingstart()
void onbufferingprogress(unsigned short percent)
void onbufferingcomplete()
AVPlayCallback void oncurrentplaytime(PlayTime time)
void onresolutionchanged(unsigned long width, unsigned long height)
void onstreamcompleted()
void onerror(WebAPIError error)
SRect
AVPlay boolean init(AVPlayInitialOption? option)
boolean open(DOMString url, AVPlayOption? option)
void play(SuccessCallback successCallback, ErrorCallback? errorCallback, unsigned long? sec)
void stop()
boolean pause()
boolean resume()
boolean jumpForward(unsigned long sec)
boolean jumpBackward(unsigned long sec)
boolean setSpeed(long speed)
boolean setAudioStreamID(unsigned short index)
boolean setSubtitleStreamID(unsigned short index)
unsigned long getCurrentBitrate()
BitrateArray getAvailableBitrates()
boolean startSubtitle(SubtitleOption option)
void stopSubtitle()
boolean setSubtitleSync(long millisec)
boolean setDisplayRect(SRect rect)
void clear()
boolean show()
boolean hide()
AdaptiveStreamingOption
DrmOption
MacrovisionOption
SubtitleDataCallback void onsubtitle(unsigned long syncTime, DOMString dataString)
SubtitleOption
PlayTime
AVPlayInitialOption
AVPlayOption

1. Type Definitions

1.1. BitrateArray

Arry of Bit-rates.

    typedef sequence<unsigned long> BitrateArray;

2. Interfaces

2.1. WebAPIsAVPlayManager

Defines what is instantiated in the webapis object.

    [NoInterfaceObject] interface WebAPIsAVPlayManager {
        readonly attribute AVPlayManager avplay;
    };
    WebAPIs implements WebAPIsAVPlayManager;

A webapis.avplay object provides access to the functionality of the avplay module.

2.2. AVPlayManager

The AVplay manager interface which provides access to the AV Play API.

    [NoInterfaceObject] interface AVPlayManager {

       const short PLAY_STATE_IDLE = 0;        

       const short PLAY_STATE_INITIALIZED = 1;        

       const short PLAY_STATE_STOPPED = 2;

       const short PLAY_STATE_PREPARED = 3;

       const short PLAY_STATE_STARTED = 4;

       const short PLAY_STATE_PAUSED = 5;
       
        void getAVPlay(AvailableAVPlaySuccessCallback successCallback,
                           optional ErrorCallback? errorCallback);
    };

This manager interface exposes the API to provide functionality for playing audio/video.

CONSTANTS

short PLAY_STATE_IDLE

Represents that avplay is in idle state.

short PLAY_STATE_INITIALIZED

Represents that avplay is initialized.

short PLAY_STATE_STOPPED

Represents that avplay is stopped.

short PLAY_STATE_PREPARED

Represents that avplay is prepared to play.

short PLAY_STATE_STARTED

Represents that avplay is playing.

short PLAY_STATE_PAUSED

Represents that avplay is paused.

METHODS

getAVPlay

Gets the avplay object which plays an audio/video file

Signature
void getAVPlay(AvailableAVPlaySuccessCallback successCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (such as null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (that is the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: AvailableAVPlaySuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Function called when an error occurs.
Exceptions
  • WebAPIException:

    with error type TypeMismatchError if any of the input attributes are of the wrong type.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 function successCB(avplayObj) {
     console.log("getting avplay object successfully");
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 webapis.avplay.getAVPlay(successCB, errorCB);
 

2.3. AvailableAVPlaySuccessCallback

Success callback for retrieving a avplay.

    [Callback=FuntionOnly, NoInterfaceObject] interface AvailableAVPlaySuccessCallback {
        void onsuccess (AVPlay obj);
    };

METHODS

onsuccess

Invoked when the available AVplay object is retrieved successfully.

Signature
void onsuccess(AVPlay obj);
Parameters
  • obj
    • Optional: No.
    • Nullable: No.
    • Type: AVPlay.
    • Description: available avplay object

2.4. BufferingCallback

Specifies the options for buffering callback subscriptions

    [Callback, NoInterfaceObject] interface BufferingCallback {

        void onbufferingstart();

        void onbufferingprogress(unsigned short percent);

        void onbufferingcomplete();
    };

METHODS

onbufferingstart

Invoked upon successfully starting the buffering.

Signature
void onbufferingstart();

onbufferingprogress

Invoked when the buffering is in progress. A parameter is sent which represents the amount of buffering completed.

Signature
void onbufferingprogress(unsigned short percent);
Parameters
  • percent
    • Optional: No.
    • Nullable: No.
    • Type: unsigned short.
    • Description: of buffering completed

onbufferingcomplete

Invoked on successfully completing the buffering.

Signature
void onbufferingcomplete();

2.5. AVPlayCallback

Specifies the options for playing callback subscriptions.

    [Callback, NoInterfaceObject] interface AVPlayCallback {
        void oncurrentplaytime(PlayTime time);

        void onresolutionchanged(unsigned long width,  unsigned long height);

        void onstreamcompleted();

        void onerror(WebAPIError error);
    };

METHODS

oncurrentplaytime

Invoked when a video is being played. It is called by passing the current playing time as the parameter. The current time is in milliseconds.

Signature
void oncurrentplaytime(PlayTime time);
Parameters
  • time
    • Optional: No.
    • Nullable: No.
    • Type: PlayTime.
    • Description: current playing time (milliseconds)

onresolutionchanged

Invoked when the resolution changes. This method is invoked by passing the new width and height of the video as parameters.

Signature
void onresolutionchanged(unsigned long width, unsigned long height);
Parameters
  • width
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: a video resolution width
  • height
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: a video resolution height

onstreamcompleted

Invoked upon completion of the stream currently being played.

Signature
void onstreamcompleted();

onerror

Invoked when there is an error playing the video. It is called by passing the WebAPIError as parameter.

Signature
void onerror(WebAPIError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: an error which is occurred in avplay

2.6. SRect

Rectangular interface which contains a region of window.

    [NoInterfaceObject] interface SRect {
        attribute unsigned long top;

        attribute unsigned long left;

        attribute unsigned long width;

        attribute unsigned long height;
    };

ATTRIBUTES

unsigned long top

the Y coordinate of the point where the rectangle will begin

unsigned long left

the X coordinate of the point where the rectangle will begin

unsigned long width

the width of the rectangle

unsigned long height

the height of the rectangle

2.7. AVPlay

Provides access to avplay. This interface allows a web application to play a video file which is not supported in HTML5.

    [NoInterfaceObject] interface AVPlay {

        readonly attribute DOMString id;

        readonly attribute DOMString url;

        readonly attribute unsigned long duration;

        readonly attribute unsigned short videoWidth;

        readonly attribute unsigned short videoHeight;

        readonly attribute SRect displayRect;

        readonly attribute DOMString containerID;

        readonly attribute unsigned short zIndex;

        readonly attribute unsigned short totalNumOfVideo;

        readonly attribute unsigned short     totalNumOfAudio;

        readonly attribute unsigned short     totalNumOfSubtitle;


        readonly attribute unsigned long     totalBufferSize;

        readonly attribute unsigned long    initialBufferSize;

        readonly attribute unsigned long     pendingBufferSize;

        readonly attribute boolean        macrovision;

        readonly attribute short        status;

        boolean init(optional AVPlayInitialOption? option);
                  
        boolean open(DOMString url, optional AVPlayOption? option);
                  
        void play(SuccessCallback successCallback, 
                    ErrorCallback? errorCallback, 
                    optional unsigned long? sec);
                              
        void stop();
        
        boolean pause();
        
        boolean resume();

        boolean jumpForward(unsigned long sec);
        
        boolean jumpBackward(unsigned long sec);
        
        boolean setSpeed(long speed);

        boolean setAudioStreamID(unsigned short index);
        
        boolean setSubtitleStreamID(unsigned short index);
        
        unsigned long getCurrentBitrate();

        BitrateArray getAvailableBitrates();
        
        boolean startSubtitle(SubtitleOption option);
        
        void stopSubtitle();
        
        boolean setSubtitleSync(long millisec);

        boolean setDisplayRect(SRect rect) ;
                                        
        void clear();
        
        boolean show();
        
        boolean hide();        
    };

ATTRIBUTES

readonly DOMString id

Avplay identification

This attribute is read-only.

readonly DOMString url

Source URL

This attribute is read-only.

readonly unsigned long duration

Total play time

This attribute is read-only.

readonly unsigned short videoWidth

Width of the video

This attribute is read-only.

readonly unsigned short videoHeight

Height of the video

This attribute is read-only.

readonly SRect displayRect

The position of the displayed screen area.

This attribute is read-only.

readonly DOMString containerID

Container identifier

This attribute is read-only.

readonly unsigned short zIndex

The z-index

This attribute is read-only.

readonly unsigned short totalNumOfVideo

The total number of video streams

This attribute is read-only.

readonly unsigned short totalNumOfAudio

The total number of audio streams

This attribute is read-only.

readonly unsigned short totalNumOfSubtitle

The total number of subtitle streams

This attribute is read-only.

readonly unsigned long totalBufferSize

The total number of playing buffer bytes

This attribute is read-only.

readonly unsigned long initialBufferSize

The total number of initial buffer bytes

This attribute is read-only.

readonly unsigned long pendingBufferSize

The total number of pending buffer bytes

This attribute is read-only.

readonly boolean macrovision

Represents it was encoded with Macrovision

This attribute is read-only.

readonly short status

Represents avplay status

This attribute is read-only.

METHODS

init

Initializes avplay with the specified option parameter. This has to be called before any other avplay function.

Signature
boolean init(optional AVPlayInitialOption? option);
Parameters
  • option
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AVPlayInitialOption.
    • Description: the initial option for avplay
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other errors.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any of the input attributes are of the wrong type

Code example
 var bufferingCB = {
     onbufferingstart : function() { console.log("buffering started"); },
     onbufferingprogress: function(percent) { console.log("on buffering : " + percent); },
     onbufferingcomplete() { console.log("buffering completely"); }
 }
 var playCB = {
     oncurrentplaytime: function(time) { console.log("playing time : " + time); },
     onresolutionchanged: function(width, height) { console.log("resolution changed : " + width + ", " + height); },
     onstreamcompleted: function() { console.log("streaming completed"); },
     onerror: function (error) { console.log(error.name); }
 }

 function successCB(avplayObj) {
     avplayObj.init({
         containerID : "0",
         zIndex : 1,
         bufferingCallback : bufferingCB, 
         playCallback : playCB, 
         displayRect : {
             width : 480,
             height : 240,
             top : 0, 
             left : 0
         },
         autoratio : true
       });  
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
     

open

Opens media content with the URL specified by parameter. This has to be called before all of other player functions.

Signature
boolean open(DOMString url, optional AVPlayOption? option);
Parameters
  • url
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: URL of the media file to be opened.
  • option
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AVPlayOption.
    • Description: the option for opening a specific media content source.
Return value
true the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError in the case of any other errors.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if the input argument "url" is a valid value.

    with error type TypeMismatchError, if any of the input attributes are of the wrong type.

Code example
 function successCB(avplayObj) {
     avplayObj.init();
     avplayObj.open("media.avi", 
          {
              totalBufferSize: 1024,
              pendingBufferSize: 1024,
              initialBufferSize: 1024, 
              macrovision: {
                  type : 0, 
                  ict: 0,
                  dot : 0,
                  vbi : 0,
              },
              adaptive: {
                    type : "",
                    startTime : "00:00",
                    startBitrate: "128"
                    uptimer: "00:00",
                    bitrates: "128",
                    admode: "seek" 
              },
              drm: {
                  type: "Macrovision",
                  company: "Rovi Corporation",
                  deviceID: "1",
                  deviceType: "...",
                  drmURL: "https://drm.com",
                  ackURL: "https://drm.com/ack",
                  heartbeatPeriod: "10",
                  portal: "https://drm.com/portal",
                  userData: "...",
                  cookie: "..."
              }
          },
          subtitle: {
               path: "subtitle.txt",
               streamID : 0,
               sync : 1000,
               subtitleDataCallback: function (syncTime, data) {
                   console.log(syncTime + " : " + data);
               }
          }
      });
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

play

Starts playback from the second specified by the parameter.

Signature
void play(SuccessCallback successCallback, ErrorCallback? errorCallback, optional unsigned long? sec);

The ErrorCallback is launched with these error types:

  • AVPlayNetworkDisconnectedError: If network is disconnected
  • AVPlayUnsupportedVideoFormatError: If the video codec is not supported
  • AVPlayUnsupportedVideoResolutionError: If the video resolution is not supported
  • AVPlayUnsupportedVideoFrameRateError: If the video frame rate is not supported
  • AVPlayCorruptedStreamError: If the video container is corrupted
  • InvalidValuesError: If the input attributes do not contain a valid value.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required. (i.e. the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: To be invoked if the play operation has completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error has occurred.
  • sec
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: Second at which playback should begin.
Exceptions
  • WebAPIException:

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 function playSuccessCB() {
     console.log("playing the video is successfully.");
 }

 function successCB(avplayObj) {
     avplayObj.init();
     avplayObj.open("media.avi");
     avplayObj.play(playSuccessCB, 
         function (error) { 
             console.error(error.message);
         },
         5);
  }
         
 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

stop

Stops playback of content.

Signature
void stop();
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function onClickStop() {
     gAVplayObj.stop();
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");              
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
     );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

pause

Pauses the current playback.

Signature
boolean pause();
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function onClickPause() {
     gAVplayObj.pause();
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");              
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

resume

Resumes the playback of paused content.

Signature
boolean resume();
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function onClickResume() {
     gAVplayObj.resume();
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");              
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

jumpForward

Jumps forward from the current playback point by the number of seconds specified in the parameter.

Signature
boolean jumpForward(unsigned long sec);
Parameters
  • sec
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: relative time offset from current time in second.
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var gAVplayObj;

 function onClickJumpForward(sec) {
     avplay.jumpForward(sec);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");   
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
     );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error)  {
     console.log(error.name); 
 }
 

jumpBackward

Jumps backward from the current playback point by the number of seconds specified in the parameter.

Signature
boolean jumpBackward(unsigned long sec);
Parameters
  • sec
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: relative time offset from current time in second.
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var gAVplayObj;

 function onClickJumpBackward(sec) {
     gAVplayObj.jumpBackward(sec);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully."); 
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
     );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

setSpeed

Sets the playback speed of currently playing content.

Signature
boolean setSpeed(long speed);
Parameters
  • speed
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Specifies the playback speed in multiples of 2. This can be a negative integer for backward playback.
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var gAVplayObj;

 function onClickSetSpeed(speed) {
     gAVplayObj.setSpeed(speed);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
     );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

setAudioStreamID

Sets the desired audio track for playback.

Signature
boolean setAudioStreamID(unsigned short index);
Parameters
  • index
    • Optional: No.
    • Nullable: No.
    • Type: unsigned short.
    • Description: index of audio stream
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value.

    with error type TypeMismatchError if any of the input attributes are of the wrong type.

Code example
 var gAVplayObj;

 function onChangeAudioTrack(index) {
     gAVplayObj.setAudioStreamID(index);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 } 
 

setSubtitleStreamID

Sets a subtitle to be displayed.

Signature
boolean setSubtitleStreamID(unsigned short index);
Parameters
  • index
    • Optional: No.
    • Nullable: No.
    • Type: unsigned short.
    • Description: index of subtitle stream
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value.

    with error type TypeMismatchError if any of the input attributes are of the wrong type.

Code example
 var gAVplayObj;

 function onChangeSubtitle(index) {
     avplay.setSubtitleStreamID(index);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

getCurrentBitrate

Gets the bitrate for the content currently playing.

Signature
unsigned long getCurrentBitrate();
Return value
unsigned long the current bitrate information for currently playing content.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function playSuccessCB() {
     console.log("playing the video is successfully.");
     console.log("current bitrate : " + avplay.getCurrentBitrate());
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

getAvailableBitrates

Retrieves available bitrate information, if content currently being played supports adaptive streaming.

Signature
BitrateArray getAvailableBitrates();
Return value
BitrateArray available bitrates of the currently playing content in String format if it is successful, otherwise it returns "".
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function playSuccessCB() {
     console.log("playing the video is successfully.");
     var bitrates = gAVplayObj.getAvailableBitrates();
     for (var i = 0; i  bitrates.length; i++) {
         console.log("available bitrate : " + bitrates[i]);
      }
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

startSubtitle

Requests that media player parse specified smi file and send event which includes subtitle string at the time to be displayed.

Signature
boolean startSubtitle(SubtitleOption option);
Parameters
  • option
    • Optional: No.
    • Nullable: No.
    • Type: SubtitleOption.
    • Description: option for the subtitle
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError if any of the input attributes are of the wrong type.

Code example
 var gAVplayObj;
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
     gAVplayObj.startSubtitle({
         path: "subtitle.txt", 
         streamID: 1, 
         sync: 1000, 
         subtitleDataCallback: function (syncTime, data) {
             console.log("sync time : " + syncTime + " : " + data);
         }
     );
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

stopSubtitle

Stops showing a subtitle.

Signature
void stopSubtitle();
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function onStopSubtitle() {
     gAVplayObj.stopSubtitle();
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
     gAVplayObj.startSubtitle({
         path: "subtitle.txt", 
         streamID: 1, 
         sync: 1000, 
         subtitleDataCallback: function (syncTime, data) {
             console.log("sync time : " + syncTime + " : " + data);
         }
     );
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 } 
 

setSubtitleSync

Adjusts displayed subtitle timing when subtitle and a/v playback are out of synch.

Signature
boolean setSubtitleSync(long millisec);
Parameters
  • millisec
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: synchronous time delay (milisecond)
Return value
true if the operation is successful otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var gAVplayObj;

 function onSetSubtitleSync(millisec) {
     gAVplayObj.setSubtitleSync(millisec);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
     gAVplayObj.startSubtitle({
         path: "subtitle.txt", 
         streamID: 1, 
         sync: 1000, 
         subtitleDataCallback: function (syncTime, data) {
             console.log("sync time : " + syncTime + " : " + data);
         }
     );
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 } 
 

setDisplayRect

Sets the display area of video content on TV screen.

Signature
boolean setDisplayRect(SRect rect);
Parameters
  • rect
    • Optional: No.
    • Nullable: No.
    • Type: SRect.
    • Description: the position of the display area
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var gAVplayObj;

 function onChangeScreenSize(rect) {
     gAVplayObj.setDisplayRect(rect);
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 } 
 

clear

Clears the TV screen (sets it to black).

Signature
void clear();
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function onClearScreen() {
     gAVplayObj.clear();
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
         );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 } 
 

show

Shows the display area.

Signature
boolean show();
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVplayObj;

 function onShowScreen() {
     gAVplayObj.show();
 }
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
     gAVplayObj.hide();
 }

 function successCB(avplayObj) {
     gAVplayObj = avplayObj;
     gAVplayObj.init();
     gAVplayObj.open("media.avi");
     gAVplayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
     );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

hide

hides display area.

Signature
boolean hide();
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 var gAVPlayObj; 
 
 function playSuccessCB() {
     console.log("playing the video is successfully.");
     gAVPlayObj.hide();
 }

 function successCB(avplayObj) {
     gAVPlayObj = avplayObj;
     gAVPlayObj.init();
     gAVPlayObj.open("media.avi");
     gAVPlayObj.play(playSuccessCB, 
         function (error) { console.error(error.message); }
     );
  }

 function errorCB(error) {
     console.log("Cannot get avplay object : " + error.name);
 }

 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 } 
 

2.8. AdaptiveStreamingOption

Specifies the options for adaptive steaming

   dictionary AdaptiveStreamingOption {
        DOMString?    type;

        DOMString?    startTime;

        DOMString?    startBitrate; 

        DOMString?    uptimer;

        DOMString?    bitrates;

        DOMString?    admode;
    };

Dictionary members

DOMString? type

Specifies the type of adaptive streaming

DOMString? startTime

Specifies the Start time of Content

DOMString? startBitrate

Specifies initial playback bitrate

DOMString? uptimer

Specifies the initial UP switching time between groups.

DOMString? bitrates

Specifies available content bitrates and bitrate groups.

DOMString? admode

Specifies the AD Play mode during seek(jump) operation.

2.9. DrmOption

Specifies the options for DRM(Digital Rights Management)

    dictionary DrmOption {
        DOMString? type;

        DOMString? company;

        DOMString? deviceID;

        DOMString? deviceType;

        DOMString? streamID;

        DOMString? drmURL;

        DOMString? ackURL;

        DOMString? heartbeatPeriod;

        DOMString? portal;

        DOMString? userData;

        DOMString? cookie;
    };

Dictionary members

DOMString? type

Specifies the type of DRM

DOMString? company

Specifies the name of DRM Company.

DOMString? deviceID

Specifies the value that is to be set in order to check the available device.

DOMString? deviceType

Specifies the value that is to be set in order to check the available device.

DOMString? streamID

Specifies the ID of the stream.

DOMString? drmURL

Specifies the URL of the DRM server.

DOMString? ackURL

Specifies the URL of the DRM ack server.

DOMString? heartbeatPeriod

Specifies the period of the heartbeat.

DOMString? portal

Specifies the address of the portal.

DOMString? userData

Specifies the extra user data.

Specifies the extra cookie data.

2.10. MacrovisionOption

Specifies the options for Macrovision.

    dictionary MacrovisionOption {
        unsigned short? type;

        unsigned short? ict;

        unsigned short?    dot;

        unsigned long?    vbi;
    };

Dictionary members

unsigned short? type

This specifies the level of Macrovision protection to be used during playback. It is used to protect analog video output.

  • 0 : APS_ALL_OFF
  • 1 : APS_AGC_ON_ONLY
  • 2 : APS_AGC_ON_CS_2L
  • 3 : APS_AGC_ON_CS_4L

unsigned short? ict

This specifies the ICT output level.

  • 0 : ICT off
  • 1 : ICT On

unsigned short? dot

This is used to disable analog video output on BD.

It must only be used for BD and not for TV.

unsigned long? vbi

This specifies VBIData (cgms type) output level.

  • 0 : CGMS_COPY_FREE
  • 1 : CGMS_COPY_NO_MORE
  • 2 : CGMS_COPY_ONCE
  • 3 : CGMS_COPY_NEVER

2.11. SubtitleDataCallback

Specifies the options for subtitle callback subscriptions.

    [Callback=FunctionOnly, NoInterfaceObject] interface SubtitleDataCallback {

        void onsubtitle(unsigned long syncTime,  DOMString dataString);
    };

METHODS

onsubtitle

Invoked when the subtitle is thrown for the current frame. The dataStr contains the subtitle value for the current frame. The user must display this string on the video.

Signature
void onsubtitle(unsigned long syncTime, DOMString dataString);
Parameters
  • syncTime
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: sync time with subtitle and frame
  • dataString
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the subtitle value for the current frame.

2.12. SubtitleOption

Specifies the options for subtitle.

    dictionary SubtitleOption {
        DOMString path;

        unsigned short streamID;

        unsigned long?  sync;

        SubtitleDataCallback subtitleDataCallback;
    };

Dictionary members

DOMString path

This value gives the path to the subtitle file associated with the video file that is currently being played.

unsigned short streamID

This value gives the subtitle index.

unsigned long? sync

This value gives the value that is to be set in order to synchronize the subtitles with the video currently being played. This value is given in milliseconds.

SubtitleDataCallback subtitleDataCallback

subtitle callback to be invoked when the subtitle is thrown for the current frame.

2.13. PlayTime

Specifies the options for Play time

    dictionary PlayTime
    {
         unsigned long millisecond;

         DOMString timeString;
    };

Dictionary members

unsigned long millisecond

This value gives the current time in milliseconds.

DOMString timeString

This value gives the current time as a string.

2.14. AVPlayInitialOption

Specifies the options for initializing avplay

    dictionary AVPlayInitialOption {
        DOMString? containerID;

        unsigned short? zIndex;

        BufferingCallback? bufferingCallback;

        AVPlayCallback? playCallback;

        SRect? displayRect;

        boolean? autoratio;
    };

Dictionary members

DOMString? containerID

container ID

unsigned short? zIndex

Z-index of the window

BufferingCallback? bufferingCallback

buffering callback

AVPlayCallback? playCallback

play callback

SRect? displayRect

display area

boolean? autoratio

auto ratio

2.15. AVPlayOption

Specifies the options for playing content.

    dictionary AVPlayOption
    {
        unsigned long? totalBufferSize;
        
        unsigned long? pendingBufferSize;
        
        unsigned long? initialBufferSize;
        
        MacrovisionOption? macrovision;
        
        AdaptiveStreamingOption? adaptive; 
        
        DrmOption? drm;
        
        SubtitleOption? subtitle;        
    };

Dictionary members

unsigned long? totalBufferSize

This value gives the total number of bytes buffered.

unsigned long? pendingBufferSize

This value gives the number of bytes still pending to be buffered.

unsigned long? initialBufferSize

This value gives the number of initial bytes buffered.

MacrovisionOption? macrovision

Specifies the options for Macrovision.

AdaptiveStreamingOption? adaptive

Specifies the options for adaptive streaming.

DrmOption? drm

Specifies the options for drm.

SubtitleOption? subtitle

Specifies the options for subtitles.

3. Full WebIDL

module AVPlay {

    typedef sequence<unsigned long> BitrateArray;
    
    [NoInterfaceObject] interface WebAPIsAVPlayManager {
        readonly attribute AVPlayManager avplay;
    };

    WebAPIs implements WebAPIsAVPlayManager;
    
    [NoInterfaceObject] interface AVPlayManager {

       const short PLAY_STATE_IDLE = 0;        

       const short PLAY_STATE_INITIALIZED = 1;        

       const short PLAY_STATE_STOPPED = 2;

       const short PLAY_STATE_PREPARED = 3;

       const short PLAY_STATE_STARTED = 4;

       const short PLAY_STATE_PAUSED = 5;
       
        void getAVPlay(AvailableAVPlaySuccessCallback successCallback,
                           optional ErrorCallback? errorCallback);
    };
        
    [Callback=FuntionOnly, NoInterfaceObject] interface AvailableAVPlaySuccessCallback {
        void onsuccess (AVPlay obj);
    };
    
    [Callback, NoInterfaceObject] interface BufferingCallback {

        void onbufferingstart();

        void onbufferingprogress(unsigned short percent);

        void onbufferingcomplete();
    };

    [Callback, NoInterfaceObject] interface AVPlayCallback {
        void oncurrentplaytime(PlayTime time);

        void onresolutionchanged(unsigned long width,  unsigned long height);

        void onstreamcompleted();

        void onerror(WebAPIError error);
    };

    [NoInterfaceObject] interface SRect {
        attribute unsigned long top;

        attribute unsigned long left;

        attribute unsigned long width;

        attribute unsigned long height;
    };  
    
    [NoInterfaceObject] interface AVPlay {

        readonly attribute DOMString id;

        readonly attribute DOMString url;

        readonly attribute unsigned long duration;

        readonly attribute unsigned short videoWidth;

        readonly attribute unsigned short videoHeight;

        readonly attribute SRect displayRect;

        readonly attribute DOMString containerID;

        readonly attribute unsigned short zIndex;

        readonly attribute unsigned short totalNumOfVideo;

        readonly attribute unsigned short     totalNumOfAudio;

        readonly attribute unsigned short     totalNumOfSubtitle;


        readonly attribute unsigned long     totalBufferSize;

        readonly attribute unsigned long    initialBufferSize;

        readonly attribute unsigned long     pendingBufferSize;

        readonly attribute boolean        macrovision;

        readonly attribute short        status;

        boolean init(optional AVPlayInitialOption? option);
                  
        boolean open(DOMString url, optional AVPlayOption? option);
                  
        void play(SuccessCallback successCallback, 
                    ErrorCallback? errorCallback, 
                    optional unsigned long? sec);
                              
        void stop();
        
        boolean pause();
        
        boolean resume();

        boolean jumpForward(unsigned long sec);
        
        boolean jumpBackward(unsigned long sec);
        
        boolean setSpeed(long speed);

        boolean setAudioStreamID(unsigned short index);
        
        boolean setSubtitleStreamID(unsigned short index);
        
        unsigned long getCurrentBitrate();

        BitrateArray getAvailableBitrates();
        
        boolean startSubtitle(SubtitleOption option);
        
        void stopSubtitle();
        
        boolean setSubtitleSync(long millisec);

        boolean setDisplayRect(SRect rect) ;
                                        
        void clear();
        
        boolean show();
        
        boolean hide();        
    };
    
   dictionary AdaptiveStreamingOption {
        DOMString?    type;

        DOMString?    startTime;

        DOMString?    startBitrate; 

        DOMString?    uptimer;

        DOMString?    bitrates;

        DOMString?    admode;
    };
    
    dictionary DrmOption {
        DOMString? type;

        DOMString? company;

        DOMString? deviceID;

        DOMString? deviceType;

        DOMString? streamID;

        DOMString? drmURL;

        DOMString? ackURL;

        DOMString? heartbeatPeriod;

        DOMString? portal;

        DOMString? userData;

        DOMString? cookie;
    };
      
    dictionary MacrovisionOption {
        unsigned short? type;

        unsigned short? ict;

        unsigned short?    dot;

        unsigned long?    vbi;
    };    
 
    [Callback=FunctionOnly, NoInterfaceObject] interface SubtitleDataCallback {

        void onsubtitle(unsigned long syncTime,  DOMString dataString);
    };
    
       
    dictionary SubtitleOption {
        DOMString path;

        unsigned short streamID;

        unsigned long?  sync;

        SubtitleDataCallback subtitleDataCallback;
    };
    
    dictionary PlayTime
    {
         unsigned long millisecond;

         DOMString timeString;
    };
           
    dictionary AVPlayInitialOption {
        DOMString? containerID;

        unsigned short? zIndex;

        BufferingCallback? bufferingCallback;

        AVPlayCallback? playCallback;

        SRect? displayRect;

        boolean? autoratio;
    };
    
    dictionary AVPlayOption
    {
        unsigned long? totalBufferSize;
        
        unsigned long? pendingBufferSize;
        
        unsigned long? initialBufferSize;
        
        MacrovisionOption? macrovision;
        
        AdaptiveStreamingOption? adaptive; 
        
        DrmOption? drm;
        
        SubtitleOption? subtitle;        
    };    
};