Subtitles

This topic describes how to configure a subtitle track to be displayed for video playback.

Related Info

Samples

PlayerAVPlaySubtitle

Samsung Smart TVs support subtitles for video playback. Subtitle tracks can be embedded in the media file, or stored in an external subtitle file.

The AVPlay API supports internal and external subtitles in the following common formats:

SAMI (".smi") (in UTF-8 encoding)
SMPTE-TT
DFXP (for Smooth Streaming only)

Configuring the Subtitle File Path

To configure the subtitle file path:

Internal subtitles

If the video file contains internal subtitles, no additional configuration is needed to set the subtitle file path.
External subtitles

The AVPlay API supports only external subtitles accessed through absolute local paths.

To set the external subtitle file path:

If the subtitle file is located remotely, download it to local storage on the TV using the Download API.

NoteDownloading the subtitle file to the "wgt-private-tmp" virtual root (the application's private volatile storage) is recommended.

While the AVPlay instance is in the IDLE state, set the external subtitle file path using the setExternalSubtitlePath() method.

...
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);
    // call setExternalSubtitlePath() before prepare()
    webapis.avplay.setExternalSubtitlePath(fullPath);
    ...
    webapis.avplay.prepare();
  },
  onfailed: function(error) {
    console.log('Failed to download Subtitle');
  }
});

Whenever the subtitle text changes during media playback, the onsubtitlechange() callback is called, returning the subtitle data value.

Switching Subtitle Tracks

If there are multiple subtitle tracks (such as for different languages), you can switch tracks during media playback.

To select a subtitle track:

Retrieve the subtitle track list.

The getTotalTrackInfo() method of the AVPlay API can only be called when the AVPlay instance is in the READY, PLAYING, or PAUSED states. It returns an array of objects for all tracks in the media.

Each object has 3 properties:
- type: The TEXT value identifies the track as a subtitle track.
- index: The index number for the track.
- extra_info: Additional information about the track, such as language information.
```
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);
  }
}
```
Select the subtitle track.

Call the setSelectTrack() method with the track type and index number as parameters:
```
// Select subtitle track with index 2
webapis.avplay.setSelectTrack('TEXT',2);
```

Synchronizing Subtitles

If the subtitles are not synchronized with the video during playback, you can adjust the synchronization using a time delay.

To adjust the subtitle delay, call setSubtitlePosition() with the delay duration in milliseconds as the parameter. The duration can be a positive or negative number; a positive delay displays the subtitles later, while a negative delay displays the subtitles sooner.

// Display the subtitles with a 5000 ms delay
webapis.avplay.setSubtitlePosition(5000);