Getting started with the Web Player on Samsung Tizen

Introduction

After completing this tutorial you will be able to successfully deploy an application on a Tizen TV, which is capable of playing back your stream with the Bitmovin Player WebSDK.

Modern TVs are capable of handling web applications and offer the same APIs that browsers do. A given TV however often uses a fixed version of an older browser engine. The Bitmovin Web SDK has been engineered to support a wide variety of such platforms.

A more detailed overview can be found in our device and cross browser support article.

One of these platforms is Tizen. In this tutorial a web application featuring the Bitmovin Player Web SDK will be created to play back a video on a Tizen TV.

Prerequisites

In order to deploy and test applications on Tizen TVs the Tizen TV SDK needs to be installed on your working machine. A detailed step by step guide can be found in the official Samsung Tizen documentation.

Once you have completed the Tizen Studio installation we are ready to create our first demo application.

Project setup

While you can simply follow the Tizen documentation and create a new web application directly in the Tizen studio, for simplicity's sake, we'll use as a starting point the Tizen sample application from our public demo repository.

Go ahead and clone the repository to your local machine and then open it in Tizen studio.

git clone https://github.com/bitmovin/bitmovin-player-tizen-demo.git

Here is a short overview of the structure of the project:

Application configuration

Finally, we are going to dig into some code. Let's go through the different files one by one.

index.html

In order to keep the memory footprint small, as a smart TV is quite a constrained environment, we should use the modular player in our demo application, to load as little code as possible. The player modules are simply imported through script tags in the index.html.

Please note that this is not a full list and needs to be customized depending on your stream requirements. More details can be found in our modules overview.

...
<script type="text/javascript" src="https://cdn.bitmovin.com/player/web/8/modules/bitmovinplayer-core.js"></script>
<script type="text/javascript" src="https://cdn.bitmovin.com/player/web/8/modules/bitmovinplayer-polyfill.js"></script>
<script type="text/javascript" src="https://cdn.bitmovin.com/player/web/8/modules/bitmovinplayer-engine-bitmovin.js"></script>
...
<script type="text/javascript" src="https://cdn.bitmovin.com/player/web/8/modules/bitmovinplayer-tizen.js"></script>

One important part here is the adding of the tizen module. This is a module specifically for Tizen TVs which works around certain device limitations.

Apart from that the index.html looks similar to the example from the Getting started.

config.xml

The config.xml is Tizen specific. It defines all capabilities your application requires. Here we are requesting access to capabilities that are necessary for video playback like the TV audio and TV display and DRM playback.

<tizen:privilege name="http://developer.samsung.com/privilege/drmplay"/>
<tizen:privilege name="http://tizen.org/privilege/drmplay"/>
<tizen:privilege name="http://tizen.org/privilege/content.write"/>
<tizen:privilege name="http://tizen.org/privilege/content.read"/>
<tizen:privilege name="http://tizen.org/privilege/tv.audio"/>
<tizen:privilege name="http://tizen.org/privilege/tv.channel"/>
<tizen:privilege name="http://tizen.org/privilege/tv.display"/>
<tizen:privilege name="http://tizen.org/privilege/tv.inputdevice"/>
<tizen:privilege name="http://tizen.org/privilege/tv.window"/>

In addition to the privileges we need to define which URLs our application is allowed to access. This means, that the CDN/URL of your source/video files will have to be added together with other resources you might be using. Such as:

<tizen:allow-navigation>demo.bitmovin.com bitmovin-a.akamaihd.net fonts.googleapis.com cdn.bitmovin.com</tizen:allow-navigation>

js/main.js

In this file, our player is setup and configured. Our focus here are Tizen TV specific settings.

An important side note is that some older Tizen platfroms only support ES5 syntax, so the recommendation is to stay on that syntax for your application.

In order to kickstart the application we are using the window.onload callback, as it ensures that all static resources are available at execution time:

window.onload = function() {
	setupPlayer();
	setupControllerEvents();
}

Let's have a look at the setupPlayer and setupControllerEvents functions and highlight some areas of interest.

Module configuration

First of all we need to register the modules which our application requires and were loaded within the index.html. This can be done by our addModule API.

bitmovin.player.core.Player.addModule(window.bitmovin.player.polyfill.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player['engine-bitmovin'].default);
bitmovin.player.core.Player.addModule(window.bitmovin.player['container-mp4'].default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.mserenderer.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.abr.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.drm.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.xml.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.dash.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.crypto.default;
bitmovin.player.core.Player.addModule(window.bitmovin.player.style.default);
bitmovin.player.core.Player.addModule(window.bitmovin.player.tizen.default);

Player configuration

After all required modules are in place you can utilize the PlayerConfigBuilder.optimizeForPlatform to apply platform specific settings like shown below:

const conf = new bitmovin.player.core.util.PlayerConfigBuilder(PLAYER_KEY)
  // the appId is only required if your html page is bundled within the app 
 .optimizeForPlatform({ appId: APP_ID }) 
 .build();

// disable the default UI
conf.ui = false;

// analytics defaults get applied by the config builder on TV models
conf.analytics.customUserId = 'my-custom-user-id';

var container = document.getElementById('player');
player = new bitmovin.player.core.Player(container, conf);

In this case you have to provide your PLAYER_KEY which can be obtained from the dashboard and optionally the APP_ID.

The APP_ID follows a reverse dns pattern such as com.bitmovin.demo.tizenwebapp and is a replacement for the hostname in standard applications. It needs to be allow-listed in the admin portal for your license requests to work on your TV application.

More details and best practices can be found at our article around Smart TV best practices

Playback of DRM protected content

For the playback of DRM protected conted we'd recommend to use Playready as Widevine is not supported on older TV models.

For playback of a DRM protected stream you would have to set additional parameters utf8message, plaintextChallenge and also set the Content-Type header in your DRM configuration for compatibility reasons as seen below.

drm: {
  playready: {
    utf8message: true
    plaintextChallenge: true,
    headers: { 'Content-Type': 'text/xml' }
  },
}

Those are required for compatibility reasons with older APIs on the TVs.

Key mappings

Last but not least, TVs require a certain key mapping to interact with your application. Our basic example enables you to play and pause your configured source and exit your application:

function setupControllerEvents() {
  tizen.tvinputdevice.registerKey('MediaPlayPause');

  // add eventListener for keydown
  document.addEventListener('keydown', function(e) {
    switch (e.keyCode) {
      case tizen.tvinputdevice.getKey('MediaPlayPause').code:
        if (player.isPlaying()) {
          player.pause();
        } else {
          player.play();
        }
        break;
      case 10009: // RETURN button
        tizen.application.getCurrentApplication().exit();
        break;
      default:
        console.log('Key code : ' + e.keyCode);
        break;
    }
  });
}

Application deployment

Now that our application is ready we can deploy it. First, Tizen Studio needs to be connected to a TV in the same network, and then the application can be deployed straight from the IDE. A good reference guide on how to do this can be found here.

Please note that the Tizen simulator is not supported by our player, so the application needs to be tested on a physical Tizen TV.