07

AV Player

Initializing the AVPlayer Library

Play, Pause, Stop, and Skip

Handling Remote Control Key Events

Summary

The core purpose of a TV is to consume video content. The Samsung SmartTV supports both broadcasting programs and VOD content to be played in an application using its AVPlayer application library. This chapter will explain major APIs of the AV Player, and show how event functions are declared and called to control the player.

Initializing the AVPlayer Library

VOD-type applications are gaining popularity because they can maximize large screen features of the common SmartTV. The Samsung SmartTV supports two different approaches to play VOD content. The first method is using a standard web HTML tag, and the second method is using the AVPlayer included in the Samsung SmartTV Web Device API. See below for an example of playing contents with the HTML tag method.

<object src=“http://www.w3schools.com/tags/movie.mp4” type=“video/mp4”></
object>
<video src=“http://www.w3schools.com/tags/movie.mp4” type=“video/mp4”></video>
<audio src=“http://www.w3schools.com/tags/audio.mp3” type=“audio/mp3”></audio>

While it is easy to implement the HTML tag approach, it has a drawback of severely limited player control other than the basic attributes supported by the HTML. Mainly, it cannot take advantage of using the focus policy to control player functions, or using callback functions to receive player events.

The following Web Device API's AV Player offers customized player control. This approach provides multiple playback methods and detailed contents controlling, by sending instructions to and receiving event messages from the AVPlayer library. See the next section for the initialization and the AVPlayer library, as well as the usage of the content-controlling functions and events.

Initializing the API

The following library needs to be declared before using the player API.

<script type=“text/javascript” language=“javascript” src=“$MANAGER_WIDGET/
Common/webapi/1.0/webapis.js”></script>

The AV Player is part of the Web Device API that was declared above. This is much simpler than the previous player plug-in method, which required declaring the Plugin API and an object to hold the module.

Next, initialize the AV Player as, shown below.

var playerInstance = webapis.avplay;

playerInstance.getAVPlay(onAVPlayObtained, onGetAVPlayError);

The playerInstance object is used only to reference the AVPlayer library instance and call getAVPlay(). Then getAVPlayer() calls the onAVPlayerObtained() callback function, which loads the actual AVPlayer module. Another callback function, onGetAVPlayerError(), was also supplied for error handling.

var Main = {};


// Callback function to initialize the AVPlayer module
function onAVPlayObtained (avplay){
    Main.AVPlayer = avplay;
    Main.AVPlayer.init();
}


// Callback function for error handling while initializing the AVPlayer
module
function onGetAVPlayError(){
    alert(‘######onGetAVPlayError: ’ + error.message);
}

The preceding code demonstrates an implementation of the callback functions to supply getAVPlay() as parameters. Note that the actual module loader, onAVPlayer(), receives the AVPlayer instance as its parameter. This instance is then bound to a local variable so that it can be accessed by all scenes (screen layers). Finally, init() is called to finalize the player initialization process.

Play, Pause, Stop, and Skip

The AVPlayer instance supports many API functions and basic player control events (play, pause, stop, skip) to control the player.

The preceding table only covers the most basic player controller APIs. See the following SDF link for the complete list of APIs.

Play

To play saved content, the player needs a path for the content. While the player can use both local and network media, streaming URL for network stored media is recommended. Absolute file path is required to play a locally stored media file. See the next example.

var playerInstance = deviceapis.avplay;
playerInstance.getAVPlay(onAVPlayObtained,onGetAVPlayError);


function onAVPlayObtained(avplay){
    Main.AVPlayer = avplay;
    Main.AVPlayer.init();
}


function onGetAVPlayError(){
    alert(‘######onGetAVPlayError: ’ + error.message);
}


// load a media file
Main.AVPlayer.open(“http://www.w3schools.com/tags/movie.mp4”);


// play the content
Main.AVPlayer.play();

Once the AV Player is successfully initialized, use open() to set the URL for the playable content, then use play() to play the content.

The Samsung SmartTV supports the following media formats.

The Samsung SmartTV also supports adaptive streaming technology that reduces buffering by automatically adopting to a client network environment with variable quality playbacks.

Player Pause and Stop

In addition to the play event, the pause and stop events are the most basic player control events. If a user presses the remote control stop or pause key, the player needs to correctly handle the user input. See the example for using stop() to stop a playback. The AVPlayer instance is already initialized.

// stop playback
Main.AVPlayer.stop();

The stop() function also needs to be called after completion of a playback. The AV Player provides onStreamCompleted() to handle the playback completion event.

The onStreamCompleted() function is included in the AVPlayerCallback API. See the SDF link for details.

The pause() function works the same way.

// pause playback
Main.AVPlayer.pause();

The paused player needs to be resumed.

// resume paused playback
Main.AVPlayer.resume();

The preceding event functions can be called within the user key event handling code to create a working player with play, stop, and pause capabilities.

Skip

The AV Player supports skipping backward or forward in set seconds. It can be used to move playing content forward or backward for a specified amount of time. These functions are commonly bound to remote control ◂◂ and ▸▸ buttons as their event-handling functions.

// jump 5 seconds backward from the current position
Main.AVPlayer.jumpBackward(5);

// jump 5 seconds forward from the current position
Main.AVPlayer.jumpForward(5);

Handling Remote Control Key Events

The next example demonstrates how an AVPlayer instance handles user remote control key events.

var Main = {};


function AVPlayerRun(){


    var playerInstance = deviceapis.avplay;
    playerInstance.getAVPlay(onAVPlayObtained, onGetAVPlayError);


    // initialize the AV Player using avplay instance
    function onAVPlayObtained(avplay){
        Main.AVPlayer = avplay;
        Main.AVPlayer.init();
    }


    function onGetAVPlayError(){
        alert(‘######onGetAVPlayError: ’ + error.message);
    }


    // load and play a content file
    Main.AVPlayer.open(“http://www.w3schools.com/tags/movie.mp4”);
    Main.AVPlayer.play();

    jQuery(“anchor_player”).focus();
}



Main.player.keyDown = function()
{
    var keyCode = event.keyCode;
    switch(keyCode)
    {
        case tvKey.KEY_RETURN:
            Player.stop();
            Main.content.anchor.focus();
            break;
        case tvKey.KEY_PLAY:
            // resume the player
            Main.AVPlayer.resume();
            break;
        case tvKey.KEY_STOP:
            // stop the player
            Main.AVPlayer.stop();
            break;
        case tvKey.KEY_PAUSE:
            // pause the player
            Main.AVPlayer.pause();
            break;
        case tvKey.KEY_RW:
            // jump 5 seconds backward from the current position
            Main.AVPlayer.jumpBackward(5);
            break;
        case tvKey.KEY_FF:
            // jump 5 seconds forward from the current position
            Main.AVPlayer.jumpForward(5);
            break;
        default:
            break;
    }
};

AVPlayerRun() initializes the player and plays the content. Then it sets focus on the player anchor, so that remote control user inputs can be handled while playing. Note that the anchor's handler, Main.player.keyDown(), is calling an appropriate AVPlayer event function for each input key.

The SDF also supports many callback functions to handle specific player status, notably AVPlayCallback() that was mentioned with the player stop function, and BufferingCallback() and SubtitleDataCallback().

Utilizing the callback functions enables specialized interface, such as player-specific subtitles and the timeline.