Smart TVs configuration and best practices

Compatibility

This article is related to Bitmovin Web SDK and SmartTVs that leverage it. Android TV, Google TV, FireTV and tvOS are out of scope of this article.

Smart TVs are typically resource-constrained devices with limited Memory and CPU capacity. Also the APIs for streaming and DRM handling (MSE/EME) on these platforms are generally incompatible with latest standards of Desktop browsers.

Know your device

Know your environment by researching the documentation on each Smart TV platform and OS release:

• Tizen documentation on web environments by version
• LG WebOS documentation on web environments

Start with Bitmovin sample repositories

The Bitmovin samples are the best resources to get start it with your Smart TV app.

1. bitmovin-player-tizen-demo
2. bitmovin-player-webos-demo

Use and retain the best practices demonstrated in the sample apps as a baseline:

1. Use of the modular player. This keeps the player footprint as small as possible, useful for constrained environments.

2. Use of the respective platform modules. There are specific modules created for both Tizen and WebOS. While these modules are not 100% necessary for all use cases on all devices, they are recommended to be included as a baseline.

3. Proactive management of the player buffer. Reducing the front and back buffer reduces player's overhead in managing the buffer, important for lower-resourced devices. The samples use the PlayerConfigBuilder which applies a forward buffer level of 30 and backward level of 10 which is a good starting point, but should be tweaked based on segment length used in your streams. For example, with 4s segments, you might adjust this to be 16s or 12s for the front buffer and 12s for the back buffer.
   And, whenever possible, steer away from formats and features that will require additional processing - and therefore resources - as these will play a factor in playback performance. For example, prefer MP4 over TS containers, as the player will have to transmux TS (overhead of converting MPEG-2 TS container into MP4 "on the fly” ).

Special player configurations

As seen in the provided web samples the PlayerConfigBuilder.optimizeForPlatform applies the below mentioned special configurations required on TVs. So you don't have to add them to your configuration if the builder is used.

Here is an example on how it can be used:

var 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);

For completeness those special settings which do get applied are explained below.

tweaksconfig settings

1. file_protocol:true (only required if the app’s HTML page is put within the TV app. For apps hosted on a remote server it isn’t necessary).
2. app_id: Has to be used together with file_protocol. It is required when the app is loaded from within the TV app
3. minimal_backward_buffer_clearing_interval On low-end TV models this setting helps to reduce the load on the TV by clearing the backward buffer not as often.

The generated config should have those properties:

conf.tweaks = {
  app_id : "my-app-id",
  file_protocol : true,
  minimal_backward_buffer_clearing_interval: 5
} 

Analytics Configuration:

origin is required to have Analytics data flow appropriately when the HTML page is put within the TV App. This should match the value you have set for your app_id and added to the allow-list in your player account.

conf.analytics =  {
  config : {
    origin: "my-app-id"
  }
}

Buffer configuration

As mentioned above, in order to reduce the memory footprint on TVs you might want to reduce the buffer kept in memory.

// you can't use the direct assigments with {[bufferType]: 40]} since older device versions only support ES5
var bufferConfig = {};
var bufferLevels = {};
bufferLevels[bitmovin.player.core.BufferType.ForwardDuration] = 30;
bufferLevels[bitmovin.player.core.BufferType.BackwardDuration] = 10,
bufferConfig[bitmovin.player.core.MediaType.Video] = bufferLevels;
bufferConfig[bitmovin.player.core.MediaType.Audio] = bufferLevels;

conf.buffer = bufferConfig;

Streaming Format and DRM Considerations

General Recommendations by Platform:

• Tizen 2.4+ (2016+) - PlayReady (DASH + PR/CENC)
• WebOS 3.0 - 3.4 (2016) - Widevine (DASH + WV/CENC)
• WebOS 3.5 - 4.x (2017-2019) - PlayReady (DASH + PR/CENC)
• WebOS 5.0+ (2020+) - Widevine (DASH + WV/CENC)

Specific configuration recommendations

PlayReady DRM:
These settings may not be universally needed for PlayReady DRM, but are good starting points when attempting PR playback on SmartTV devices.

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

DASH:
Some older Tizen model streaming API might attempt to default to native playback. Ensuring that preferredTech is appropriately set in the playbackConfiguration helps avoid this situation:

playback : {
  autoplay : true,
  muted : false,
  preferredTech : [{
    player: 'html5',
    streaming: 'dash',
  }]
}

Streams with high playback times

It has been observed, that the Tizen2016 TV has failed to playback streams which have high resulting playback times (~1_600_000_000). It is known, that the device cannot decode BaseMediaDecodeTimes greater than 2^32 bit, but it might already fail with lesser values. If a stream fails to start playback (or if you observe multiple seek operations in rapid succession), it can help to force the BaseMediaDecodeTime rewriting by setting the tweak FORCE_BASE_MEDIA_DECODE_TIME_REWRITE: true

Warning: Using this tweak might also cause some playback issues, like stalls and freezes, when playing streams with multiple short discontinuities (e.g. SSAI streams). Enabling the tweak is only recommended when the playback experience is improved on testing.

Device Information

It is useful to get information logged out directly from the device, especially when submitting logs for further investigation, so readers know exactly where they came from. Device information from the OS can also be informative in terms of profiling and resource utilisation.

WebOS deviceInfo Example:
Using WebOs API Services it is possible to obtain valuable information from the LG smartTV. Please refer to WebOS API documentation to understand how to use it.

Please be sure to include the webOSTV.js into your application in order to use the API.

function deviceInfo () {
	var request = webOS.service.request("luna://com.webos.service.tv.systemproperty", {
	    method: "getSystemInfo",
	    parameters: {
	        "keys": ["modelName", "firmwareVersion", "UHD", "sdkVersion"]
	    },
	    onComplete: function (inResponse) {
	        var isSucceeded = inResponse.returnValue;

	        if (isSucceeded){
	            console.log("deviceInfo Result: " + JSON.stringify(inResponse));
	            // To-Do something
	        } else {
	            console.log("Failed to get TV device information");
	            // To-Do something
	            return;
	        }
	    }
	});
}

Tizen segmentPlayback Memory Usage Example:

Tizen TVs provide an API that allows obtaining different types of information from the device.

Please review the Tizen SystemInfo documentation to understand its usage and capabilities.

As opposed with WebOS, there is no need to include any Js file or reference to this API, as it will become available globally when the application runs on a Tizen device.

player.on(bitmovin.player.core.PlayerEvent.SegmentPlayback, function(data) {
    console.log("segment played back: " + JSON.stringify(data));
    console.log("total memory: " + tizen.systeminfo.getTotalMemory() / (1000*1000) + "MB   avail memory: " + tizen.systeminfo.getAvailableMemory() / (1000*1000) + "MB");
  });

What's Next

Getting Started Guides

• Using the Web player on Samsung Tizen TVs
• Using the Web player on LG webOS TVs