Subtitles

Adding subtitles to the server manifest

Unified Origin supports playout to all formats of TTML subtitles (EBU-TT, SMPTE-TT, DFXP or CFF-TT) stored in an MP4 container.

New in version 1.7.31.

Unified Origin also support playout of fragmented WebVTT to HLS and MPEG DASH players that support the wvtt codec.

We recommend using fragmented DFXP for maximal interoperability as it is the most constrained format. You may use Unified Packager to convert SRT or (Web)VTT to TTML or to create (fragmented) MP4 files from WebVTT or TTML, see Packaging Subtitles.

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

#!/bin/bash

mp4split -o tears-of-steel.ism \
  tears-of-steel-avc1-400k.ismv \
  tears-of-steel-avc1-750k.ismv \
  tears-of-steel-en.ismt

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

#!/bin/bash

mp4split -o tears-of-steel.ism \
  tears-of-steel-avc1-400k.ismv \
  tears-of-steel-avc1-750k.ismv \
  tears-of-steel-en.ismt \
  tears-of-steel-zh-hans.ismt

If properties are missing or set incorrectly in the source file of the subtitles, this should preferably be corrected when creating the (fragmented) MP4 file (e.g. subtitles.ismt) from the source. This ensures that mp4split can infer and add the correct information to the server manifest when running a command like the above. However, if correcting these properties when creating the (fragmented) MP4 file from the subtitle source is not possible, they can also be specified when generating the server manifest file.

For example, you can use –track_language to set the ‘language’ attribute of the subtitle track:

#!/bin/bash

mp4split -o presentation.ism \
  tears-of-steel-avc1-400k.ismv \
  tears-of-steel-avc1-750k.ismv \
  tears-of-steel-en.ismt --track_language=eng

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

Unified Origin’s support for subtitles is similar for MPEG-DASH, HSS and HLS: the source content must be TTML or WVTT samples stored in a fragmented MP4 (.ismt) container.

The MIME type of the subtitle track listed in the .mpd is application/mp4, the @contentType attribute is text, the @codecs attribute is stpp for TTML-based samples and wvtt for VTTCue samples.

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.

Please see the Unified Streaming Demo for an example that uses subtitles in DASH.

For DASH, sidecar subtitle files are automatically added for WVTT, but for TTML, this is only supported in offline packaging with Unified Packager. Please see Adding TTML or WebVTT sidecar subtitles for MPEG-DASH for an explanation of how to add TTML and WVTT sidecar only subtitles when packaging DASH.

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, the player normally picks the one 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 that is always marked as the default.

To change the default (i.e. the track listed first) combine the fragmented MP4 files (.ismt’s) for the various languages into a single fragmented MP4 before generating the server manifest. The order in which the subtitles are added will be followed, so that the first track becomes the default, see Define default track when preparing content.

Please see the Unified Streaming Demo for an example that uses subtitles in HLS.

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 that uses subtitles in HSS.

Subtitles for HTTP Dynamic Streaming (HDS)

Not supported. However, some players can load a subtitle file (for instance .srt) as a ‘sidecar’ file and display subtitles from the loaded file. An example is Flowplayer.