top

Subtitle

This document shows you how to write video playing which has subtitle in your application. You can play video from locally path or from remote URL, all using AVPlay APIs. But the subtitle path supported only locally path.
We recommend read "common > Using AVPlay" document prior to the beginning of this document.

Overview

Samsung smart tv supported internal and external subtitle when playing video. When internal or external subtitle text change during media playback ,onsubtitlechange event function, configured through parameter of setListener() is called. You get subtitle data value with onsubtitlechange event.
This guide explains how to set subtitle path before playing video which is based on common media playback guide.

Supported Subtitle Format

AVPlay support internal and external subtitle which is well-known type. Following list is the supported subtitle formats in Samsung Smart TV.

  • SAMI(SMI) (UTF-8)
  • SMPTE-TT
  • DFXP (Smooth Streaming Only)

Setting Subtitle

Internal Subtitle

If your video includes subtitle track in its file, you don’t have to call any method to set the subtitle. You only have to call AVPlay API for playback video, then AVPlay handle internal subtitle through onsubtitlechange event function during video playback.

External Subtitle

AVPlay supports only absolute locally path subtitle. It doesn’t support relative locally path or remote URL base on network. So if you have subtitle file on remote URL, first you should download subtitle file to storage in smart tv. Samsung Smart TV provides Download API which is asynchronously download the contents of a URL to a storage.

Note

We recommend using "*wgt-private-tmp*" virtual root. Because It is located a widget’s private volatile storage.

After the download subtitle file is successfully completed, subtitle file is located in storage of smart tv.
In case of subtitle file is already located in smart tv, you can skip download process. From now on you can set subtitle file for video using setExternalSubtitlePath() method, then AVPlay handle subtitle through onsubtitlechange event function during video playback.

You should call setExternalSubtitlePath method before calling prepare() method because setExternalSubtitlePath() has valid states which is IDLE.

...
var downloadRequest = new tizen.DownloadRequest(yourSubtitleURL, "wgt-private-tmp");
...
tizen.download.start(downloadRequest, {
    oncompleted: function(downloadId, fullPath) {
        console.log('absolute path of downloaded file : '+fullPath);
        // setExternalSubtitlePath should be called before prepare
        webapis.avplay.setExternalSubtitlePath(fullPath);
        ...
        // prepare should be called after setExternalSubtitlePath
        webapis.avplay.prepare();
    },
    onfailed: function (error) {
        console.log('Failed to download Subtitle');
    }
});

Changing Language of Multiple Language Subtitle

If your subtitle supports multiple language, you can change language track during media playback. First, You need find subtitle track list in media. AVPlay has webapis.avplay.getTotalTrackInfo() which is get whole track informaiton(contain subtitle track) of media. It has a state limitation after READY state.
getTotalTrackInfo() return Array type value, each Array item is object type which has three property.

  • type : It has three possible values that is “VIDEO”, “AUDIO”, "TEXT"
    You can find subtitle track using “TEXT”
  • index : It is used to select subtitle track with setSelectTrack()
  • extra_info : It has more detailed information(language/type etc) about each track which is object type.
var totalTrackInfo = webapis.avplay.getTotalTrackInfo();

for(var i=0; i<totalTrackInfo.length;i++) 
{
    if(totalTrackInfo.type =='TEXT')
    {
        console.log('Find subtitle track.');
        console.log('subtitle track index is' + totalTrackInfo.index);
        console.log('subtitle track language is' + totalTrackInfo.extra_info.track_lang);
    }
}

You can choose subtitle track using subtitle track index number in media. Call webapis.avplay.setSelectTrack() with subtitle track index number.

//For example, you choose subtitle track index number 2.
webapis.avplay.setSelectTrack('TEXT',2);

Controlling Sync of Subtitle

When subtitle and video synchronization do not match during playback video, you can move subtitle position for synchronization. Call webapis.avplay.setSubtitlePosition() set the subtitle position. You can use positive or negative numbers as parameter. The parameter unit is millisecond. If the parameter is set to negative, the subtitle position will be moved in the reverse direction. For positive case, subtitle position will be moved in forward direction.

//For example, you move subtitle position to 5000ms in forword direction.
webapis.avplay.setSubtitlePosition(5000);

Sample Application