Samsung Electronics logo

AV Player Control

Table of Contents


If your application must play media content on a TV, you can use the AVPlay API. The AVPlay API allows you to play media content on a TV, control playback, set the display area, and so on.

Prerequisites

The AVPlay API lets you play media content on a TV. When the application is launched, an avplay object is automatically instantiated in the webapis object. The webapis.avplay object is an instance of the AVPlayManager interface that gives you the method to get the reference to the TV player.

Adding the webapis JavaScript file in your application is required to invoke this API properly. Please refer to the script code below to add the webapis file:

 
<html><head>
    <!-- including the JavaScript file which supports Samsung Web API -->
    <script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/webapi/1.0/webapis.js"></script> 
</head></html>

Get the avplay Object that Plays Audio/Video Content

In order to play media content on a TV, an application needs the reference to the webapis.avplay object.

The AVPlay API provides the AVPlayManager interface, which allows you to get the reference to the TV player. The method getAVPlay() gives you the avplay object that plays audio/video content.

 
function successCB(avplayObj) {
 	alert("getting avplay object successfully");
  }

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

 webapis.avplay.getAVPlay(successCB, errorCB);

Initialize the Player and Open and Play Media Content

An application must first initialize the TV player using the init method, then use the open method to open media content and call the play method to play media content.

Initializing the player

An application must pass the callback functions for buffering and playback, player z-index, display area coordinates and size, and so on to initialize the player.

var bufferingCB = {
				
     onbufferingstart : function() { alert("buffering started"); },
     
     onbufferingprogress: function(percent) { alert ("on buffering : " + percent); },
     
     onbufferingcomplete:function() { alert ("buffering completely"); }
 };
 var playCB = {
     oncurrentplaytime: function(time) { alert ("playing time : " + time); },
     
     onresolutionchanged: function(width, height) { alert ("resolution changed : " + width + ", " + height); },
     
     onstreamcompleted: function() { alert ("streaming completed"); },
     
     onerror: function (error) { alert (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
       });  
  };

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

Opening media content

An application must open media content with the URL specified by the parameter. An application must open media content before playing.

The open() method is used to open media content.

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) {
                   alert(syncTime + " : " + data);
               }
          }
      });
  }

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

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

Playing media content

After initializing the player and opening media content, an application plays the media content using the play() method.
The play() method starts playback of the video file stored in the URL and passed as a parameter to the open function. Upon successfully playing the video file, successCallback is called, and, upon failure, errorCallback is called. An option parameter can also be sent specifying the position in seconds from which play starts.

function playSuccessCB() {
     alert("playing the video is successfully.");
 }

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

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

Control Playback with Stop, Pause, Resume, and Jump Methods

To control media content playback on a TV, an application must use methods provided by the webapis.avplay object reference. These methods allow the application to stop, pause, resume, and jump forward and backward in media playback.

Stopping media playback

If an application must stop playback of current media content on a TV, it must call the stop() method. This method stops current media content playback.

var gAVplayObj;

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

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

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

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

Pausing media playback

The AVPlay API provides methods that allow you to pause media content.

To request pausing media content, call the pause() method of the avplayerObject that is received on success callback of initialization of AVplayer, such as AVplayObj.pause(); it changes the state of the AV player from play state to pause/stop and therefore pauses playback of the current media content on the TV.

var gAVplayObj;

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

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

 function errorCB(error) {
     alert("Cannot get avplay object : " + error.name);
 }
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     alert(error.name);
 }

Resuming media playback

The AVPlay API provides methods that allow you to resume media content.

To request resuming the paused media content, call the resume() method of avplayerObject, which is returned on success callback of initialization of AVplayer, such as AVplayObj.resume(); it changes the state of the AV player from pause state to resume and therefore resumes the playback of current media content on the TV.

var gAVplayObj;

 function onClickResume() {
     // resume the playback by user event after the media being played
     gAVplayObj.resume();
 }
 
 function playSuccessCB() {
     alert("playing the video is successfully.");       
 }
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert(error.message); }
         );
  }
 function errorCB(error) {
     alert("Cannot get avplay object : " + error.name);
 }
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     alert(error.name);
 }

Jumping forward or backward during media playback

The AVPlay API provides methods that allow you to seek forward/backward in the media content.

To request seeking forward/backward in media content using a given number of seconds, call the jumpForward() or jumbBackward() method of avplayerObject, which is returned on success callback of AVPlayer initialization, such as AVplayObj.jumpForward() or AVplayObj.jumpBackward(); it is required to pass the numeric value in number of seconds to seek forward/backward in the media playback.
On successful execution, it seeks forward or backward and starts playback of current media content on the TV from the new seek time.

If an application must move playback forward by a specified number of seconds in the currently playing media, it must call the jumpForward method.
This method moves playback forward in the current media by the given number of seconds.

var gAVplayObj;

 function onClickJumpForward(sec) {
     // jump forward by user event after the media being played
     gAVplayObj.jumpForward(sec);
 }

 function onClickJumpBackward(sec) {
     // jump backward by user event after the media being played
     gAVplayObj.jumpBackward(sec);
 }

 
 function playSuccessCB() {
     alert("playing the video is successfully.");             
 }

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

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

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

Set Different Attributes, Such as Playback Speed, Stream ID, Subtitles, and Bitrate

The TVPlay object allows you to set playback speed, audio stream ID, subtitle stream ID, handling subtitle, get current bitrates, available bitrates, and so on.

Setting playback speed

The AVPlay API provides methods that allow you to set the playback speed of media content.

To request setting the playback speed of media content by a given number, call the setSpeed() method of avplayerObject, which is returned on success callback of initialization of AVplayer, such as AVplayObj.setSpeed(). It is required to pass the numeric value as a number by which you want to set the speed of media playback; on successful execution, it sets the playback speed of the media content on the TV.

var gAVplayObj;

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

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

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

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

Setting the audio stream ID

The AVplayer API provides methods that allow you to set the audio stream of the media content.

To request setting the audio stream of media content, call the setAudioStreamID method of avplayerObject, which is returned on success callback of AVPlayer initialization, such as AVplayObj. setAudioStreamID(). It is required to pass the numeric value as the index of the audio stream of the media content; on successful execution, it returns true on success; otherwise, it returns false
setAudioStreamID() sets the audio track to the audio track ID specified in the parameter.

 var gAVplayObj;
 function onChangeAudioTrack(index) {
     gAVplayObj.setAudioStreamID(index);
 }
 
 function playSuccessCB() {
     alert("playing the video is successfully.");         
 }
 
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert (error.message); }
         );
  }
  
 function errorCB(error) {
     alert ("Cannot get avplay object : " + error.name);
 }
 
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
     
 } catch (error) {
     alert (error.name);
 }

Setting the subtitle stream ID

The AVPlay API provides methods that allow you to set the subtitles of the media content.

To request setting the subtitle stream of media content, call the setSubtitleStreamID() method of avplayerObject, which is returned on success callback of AVPlayer initialization, like AVplayObj.setSubtitleStreamID() and it is required to pass the numeric value as index of subtitle stream for the media content and on successful execution it will return true, otherwise  false will be returned.

The setSubtitleStreamID() sets the current subtitle track to the subtitle track ID specified in the parameter.

var gAVplayObj;
			
 function onChangeSubtitle(index) {
 
     avplay.setSubtitleStreamID(index);
 }
 function playSuccessCB() {
 
     alert("playing the video is successfully.");        
 }
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert (error.message); }
         );
  }
  
 function errorCB(error) {
     alert ("Cannot get avplay object : " + error.name);
 }
 
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     alert (error.name);
 }

Getting current bitrates

The AVPlay API provides methods that allow you to get the bitrates of media content.

To request getting media content bitrates, call the getCurrentBitrate() method of avplayerObject, which is returned on success callback of AVPlayer initialization, such as AVplayObj.getCurrentBitrate(); on successful execution, it returns, unsigned long, the current bitrate information for the currently playing content.

getCurrentBitrate() retrieves the current bitrates of the media being played.

var gAVplayObj;
			
 function playSuccessCB() {
     alert ("playing the video is successfully.");
     alert ("current bitrate : " + gAVplayObj.getCurrentBitrate());
 }
 
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert (error.message); }
         );
 }
  
 function errorCB(error) {
     alert ("Cannot get avplay object : " + error.name);
 }
 
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     alert (error.name);
 }

Getting available bitrates

The AVPlay API provides methods that allow you to get the list of bitrates for the media content.

To request getting the list of bitrates for the media content, call the getAvailableBitrates method of avplayerObject, which is returned on success callback of AVPlayer initialization, such as AVplayObj. getAvailableBitrates(). On successful execution, it returns an array of available bitrates for the currently playing content in String format if successful; otherwise, it returns "".

getAvailableBitrates() retrieves an array consisting of all the available bitrates.

var gAVplayObj;
			
 function playSuccessCB() {
 
     alert ("playing the video is successfully.");
     
     var bitrates = gAVplayObj.getAvailableBitrates();
     
     for (var i = 0; i < bitrates.length; i++) {
         alert ("available bitrate : " + bitrates[i]);
      }
 }
 
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert (error.message); }
         );
  }
  
 function errorCB(error) {
     alert ("Cannot get avplay object : " + error.name);
 }
 
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
     
 } catch (error) {
     alert (error.name);
 }

Starting or stopping subtitles

The AVPlay API provides methods that allow you to start or stop showing subtitles in the media content.

To request starting the subtitles in media content, call the startSubtitle method of avplayerObject, which is returned on success callback of AVPlayer initialization, such as AVplayObj. startSubtitle(); it is required to pass the object as SubtitleOption, which contains detailed information about the path and streamID sync and callback function. On success, it returns the sync time.

Also, to stop showing subtitles, call the stopSubtitle() instead when showing subtitles.

The startSubtitle() starts the subtitles by sending a subtitle option as a parameter. The stopSubtitle() ends subtitles without any parameter.

var gAVplayObj;
			
 function onClickStopSubtitle() {
     aAVplayObj.stopSubtitle();
     alert("showing subtitle is stopped");
 }
			
 function playSuccessCB() {
 
     alert ("playing the video is successfully.");
     
     if (gAVplayObj.startSubtitle({
           path: "subtitle.txt", 
           streamID: 1, 
           sync: 1000, 
           subtitleDataCallback: function (syncTime, data) {
               alert ("sync time : " + syncTime + " : " + data);
         }) {
          alert("showing a subtile properly");
      }
     );
 }
 
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert (error.message); }
         );
  }
  
 function errorCB(error) {
     alert ("Cannot get avplay object : " + error.name);
 }
 
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
     
 } catch (error) {
     alert (error.name);
 }

Synchronizing subtitle timing

The AVPlay API provides methods that allow synchronizing the subtitle track with the video track by the number of milliseconds specified in the parameter. \

To request synchronizing the subtitle track with the video track by the number of milliseconds specified in the parameter, call the setSubtitleSync() method of avplayerObject, which is returned on success callback of AVplayer initialization, such as AVplayObj.setSubtitleSync(); it is required to pass the number in milliseconds to synchronize.
On successful execution, it returns true; otherwise, false is returned.

setSubtitleSync() synchronizes the subtitle track with the video track by the number of milliseconds specified in the parameter.

var gAVplayObj;

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

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

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

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

Set the Display Area that Plays Media Content

An application can set the display area of video content on the TV screen.

To set the display area, the setDisplayRect() method must be used. This function sets the display area to the values in the sRect. It has four values. The first two values represent the x and y coordinates in the upper-left corner of the area, and the next two values represent the width and height of the video.

var gAVplayObj;
			
 function onChangeScreenSize(rect) {
     gAVplayObj.setDisplayRect(rect);
 }
 function playSuccessCB() {
     alert("playing the video is successfully.");
 }
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert (error.message); }
         );
  }
 function errorCB(error) {
     alert ("Cannot get avplay object : " + error.name);
 }
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
     
 } catch (error) {
     alert (error.name);
 }

Clear, Show, and Hide the Player Screen

An application must use the methods provided by the player object to control player visibility (hide and show) and clear the display area of TV screen.

Clearing the TV screen

An application must erase the video remnant after playback to clear the TV screen with black.

The clear() function erases the TV screen with black.

var gAVplayObj;
			
 function onClearScreen() {
     // Clear the screen with black
     gAVplayObj.clear();
 }
 function playSuccessCB() {
     alert("playing the video is successfully.");
 }
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert(error.message); }
         );
  }
 function errorCB(error) {
     alert("Cannot get avplay object : " + error.name);
 }
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
     
 } catch (error) {
     alert(error.name);
 }

Showing and hiding the display area

The AVPlay API provides methods that allow you to set the display area of AVplayer to visible or invisible for media content.

 To set the display area of AVplayer to visible or invisible for media content, call the show() or hide() method of avplayerObject, which is returned on success callback of AVPlayer initialization, such as AVplayObj.show() or AVplayObj.hide().
On successful execution, it returns true; otherwise, false is returned.

show() or hide() sets the display area of AVplayer to visible or invisible.

var gAVplayObj;
			
 function onShowScreen() {
     gAVplayObj.show();
 }

 function onHideScreen() {
     gAVplayObj.hide();
 }
 
 function playSuccessCB() {
     alert("playing the video is successfully.");
     gAVplayObj.hide();
 }
 
 function successCB(avplayObj) {
 
     gAVplayObj = avplayObj;
     
     gAVplayObj.init();
     
     gAVplayObj.open("media.avi");
     
     gAVplayObj.play(playSuccessCB, 
         function (error) { alert(error.message); }
     );
  }
  
 function errorCB(error) {
     alert("Cannot get avplay object : " + error.name);
 }
 
 try {
     webapis.avplay.getAVPlay(successCB, errorCB);
 } catch (error) {
     alert(error.name);
 }