Subtitles

Adding subtitles to a VOD stream

Unified Origin supports input of fragmented TTML subtitles.

New in version 1.7.31.

From version 1.7.31, input of fragmented WebVTT subtitles is also supported.

In other words, the ingested subtitles must consist of either TTML or WVTT samples stored in a fragmented MP4 (.ismt or .cmft) container.

You can prepare your subtitles for ingest with Unified Packager, which supports packaging of SRT, WebVTT and TTML. For TTML the profiles it supports are DFXP, SMPTE-TT, EBU-TT-D, SDP-US, CFF-TT and the IMSC1 Text Profile.

Please read Packaging Subtitles for more information on how to package and prepare subtitles.

Overall, the workflow for adding subtitles to a VOD stream is as follows:

  • Package supported subtitles (SRT, WebVTT, TTML) in a fragmented MP4, as described in Packaging Subtitles
  • Add the fragmented MP4 that contains the subtitles to the VOD server manifest like any other track, as described below

Play-out formats

Depending on whether input for Origin is fragmented TTML or fragmented WebVTT, it will output subtitles in a different formats for MPEG-DASH, Apple HLS and Microsoft Smooth Streaming. The overview in the table below applies to both Origin VOD and Origin Live:

Protocol TTML input WebVTT input
DASH Fragmented TTML + (VOD only) Plain-text WebVTT sidecar Fragmented WebVTT + (VOD only) Plain-text WebVTT sidecar
HLS Plain-text WebvTT fragments Plain-text WebvTT fragments
Smooth Fragmented TTML N/A
HDS N/A N/A

Adding subtitles to a VOD server manifest

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

Correcting properties

If properties are missing or set incorrectly in the source file of the subtitles, this should preferably be corrected when packaging the subtitles in a fMP4 container. This ensures that mp4split can infer and add the correct information to the server manifest when running a command like the above.

However, if is not possible to correct the properties when packaging the subtitles in a fMP4 is not possible, they can also be specified when generating the server manifest. 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

Support for playback of subtitles varies greatly from player to player. Please make sure you are using the latest version of your player and make yourself aware of its limitations regarding subtitle support.

Subtitles for MPEG-DASH

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.

Plain-text WebVTT sidecar

New in version 1.7.31.

For DASH, WebVTT sidecar subtitles are automatically generated. This is true regardless of whether the subtitles input format is fragmented WebVTT or fragmented TTML input. The WebVTT sidecar subtitles are signaled as a separate adaptation set with MIME type text/vtt and no codec.

An example:

<!-- fMP4 containing TTML samples -->
<AdaptationSet
  contentType="text"
  lang="ru"
  mimeType="application/mp4"
  codecs="stpp">

<!-- fMP4 containing VTTCue samples -->
<AdaptationSet
  contentType="text"
  lang="ru"
  mimeType="application/mp4"
  codecs="wvtt">

<!-- Plain-text WebVTT -->
<AdaptationSet
  contentType="text"
  lang="ru"
  mimeType="text/vtt">

TTML sidecar

Plain-text TTML sidecars are 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 WebVTT sidecar only subtitles when packaging DASH.

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.

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 found, the default track is taken. Like with video and audio tracks, Origin VOD marks the first track in a group that as the default.

To control which track is the first in a group (thus controling which track is the default), you need to combine the tracks for various languages into a single fMP4 before generating the server manifest. This fMP4 needs to be a .ismt, as .cmft only supports one track per file as specified in CMAF. The order in which the tracks are added will be respected, so that the first track becomes the default, see Define default track when preparing content (track order).

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.