Subtitles

Adding subtitles to the server manifest

Unified Origin supports TTML subtitles (EBU-TT, SMPTE-TT, TTML-TT or CFF-TT) stored in an MP4 container. You may use Unified Packager to prepare the subtitles if they are in another format, see Packaging Subtitles.

DFXP (TTML) is preferred as it is the most constrained format.

Subtitles stored in the MP4 format are treated similar to audio and video tracks. They have similar properties like 'language', 'bitrate'. They can simply be added to the list of inputs on the command line when creating the server manifest file.

TTML subtitles must contain a single language. If you have a single TTML file containing multiple languages then you have to create a separate TTML files first (one for each language).

#!/bin/bash

mp4split -o presentation.ism \
  video-400.ismv \
  video-800.ismv \
  subtitles.ismt

If properties are missing or set incorrectly then preferably they should be fixed when packaging the 'subtitles.ismt' file. If that's not possible then the properties can be given at the time when generating the server manifest file.

For example you can set the 'language' attribute of the subtitle track:

#!/bin/bash

mp4split -o presentation.ism \
  video-400.ismv \
  video-800.ismv \
  subtitles.ismt --track_language=eng

Note

The track_language is the country code as specified in ISO 639-2/T.

If you have multiple subtitles, then you simply add the various subtitle files:

#!/bin/bash

mp4split -o presentation.ism \
  video-400.ismv \
  video-800.ismv \
  subs_eng.ismt \
  subs_spa.ismt \
  subs_fra.ismt

Download

For an example please download the subtitles.sh script. The sample content is Tears of Steel.

Subtitle playback

After creating the manifest you can enable the subtitles in your player.

Some of the out-of-the-box players have support for showing subtitles or providing a language selection box.

Subtitles for MPEG-DASH

The origin supports use of subtitles/captions in MPEG-DASH in a similar manner as with HSS or HLS: the source content must be TTML-TT or CFF-TT stored in a fragmented MP4 (.ismt) container. This is conformant with the MPEG specification (ISO 14496-30) and allows storing any of the TTML formats (EBU-TT, SMPTE-TT, TTML-TT or CFF-TT). The samples are stored in a subtitle track and use the XMLSubtitleSampleEntry("stpp") as format.

You may use Unified Packager to prepare the subtitles if they are in another format, see Packaging Subtitles.

The MIME type of the subtitle track listed in the .mpd is application/mp4, the @contentType attribute is text, the @codecs attribute is stpp.

An example:

<AdaptationSet
  group="3"
  contentType="text"
  lang="ru"
  minBandwidth="1000"
  maxBandwidth="1000"
  mimeType="application/mp4"
  codecs="stpp">

For DVB-DASH the input format must be EBU-TT-D, see page 27 of DVB Document A168 July 2014.

Support for sidecar subtitle files is only available when offline packaging (so using the packager, not the just-in-time origin). Please see Adding TTML or WebVTT sidecar subtitles for MPEG-DASH for an example of adding WebVTT to a DASH packaging command line.

Please see the Unified Streaming Demo for an example.

Subtitles for HTTP Live Streaming (HLS)

Important

Subtitles for HLS require at least version 4 of the HLS protocol.

Make sure to set this using the --hls.client_manifest_version option:

--hls.client_manifest_version=4

When you have multiple subtitles, then normally the player picks the one that it finds most suitable (e.g. when the language of the subtitle track matches the language of the phone). If no match is made then the default track is taken. In our case the first track in a group is always marked as the default.

If you want to change the default (i.e. the track listed first) then you change the order by packaging all TTML subtitle tracks into a single ISMT file. The order in which they are added is then used and the first track becomes the default, see Packaging with track order and defaults.

Please see the Unified Streaming Demo for an example.

Subtitles for HTTP Smooth Streaming (HSS)

Enabling subtitles in the Silverlight player (MMP Player Framework 2.7) is done by adding the following value to the InitParams parameter:

param name="InitParams" value="enablecaptions=true, selectedcaptionstream=textstream_eng, mediaurl=...

Note that parameter for the 'selectedcaptionstream' is the name of the text track as given by the @Name attribute in the Smooth Streaming client manifest.

Please see the Unified Streaming Demo for an example.