Captioning

This tutorial shows how to properly add close captions when using AMP.

The topics covered in this page are:

Adding captions.
Adding captions for multiple laguages.
Using embedded captions.
Custom rendering.
Using cue point transformation.

1. Adding Captions

AMP supports the following captioning formats by default:

VTT
TTML
608
708
embedded

To include caption tracks in media playback, provide a track array to the media object. Each item in the array should have the following properties:

src: The path to the caption file
type: The mime type of the file
kind: The kind of text track. For captions, use the string "captions"
srclang: Language code of the given track

Below there's an example.

var config = {
  media: {
    src: "http://video.xyz.com/master.m3u8",
    type: "application/x-mpegURL",
    track: [{
      kind : "captions",
      type: "application/ttml+xml",
      src: "captioning.xml",
      srclang: "en"
    }]
  }
};

For further information please check:

2. Adding Captions for Multiple Languages

Tracks for individual languages can be set using the srclang property of the track items with an ISO 639-1 language code. The player will choose the track based on the player's language setting (see Localization for more details):

var config = {
  media : {
    src : "http://video.xyz.com/master.m3u8",
    type : "application/x-mpegURL",
    track : [{
      kind : "captions",
      type : "text/vtt",
      src : "captioning-en.vtt",
      srclang : "en"
    }, {
      kind : "captions",
      type : "application/ttml+xml",
      src : "captioning-es.xml",
      srclang : "es"
    }]
  }
};

3. Using Embedded Captions

For 608, 708, or embedded captions, the src property is not needed, since the captions are provided as part of the stream data. However, it is needed to provide the proper kind, mime type and language tag.

The mime types for each format are:

608: "text/cea-608"
708: "text/cea-708"
Embedded: "text/embedded"

var config = {
  media : {
    src : "http://video.xyz.com/master.m3u8",
    type : "application/x-mpegURL",
    track : [{
      kind : "captions",
      type : "text/cea-608",
      srclang: "en"
    }]
  }
};

4. Custom Rendering

Certain scenarios require specific handling of the caption rendering. AMP provides two rendering engines for captions:

html: Captions are rendered in a HTML overlay
native: Captions are rendered natively by the video tag

By default the player will automatically choose which renderer is best for the platform. To override this behavior, provide the renderer config option.

var config = {
  captioning: {
    renderer: "native"
  }
};

5. Using Cue Point Transformation

Sometimes there is a need to alter a cue point before rendering it on-screen. This can be accomplished by using the transform API. Similar to media transforms, each cue can be run through a function to alter it's contents:

amp.addTransform(akamai.amp.TransformType.CUE_CHANGE, function (cues) {
  cues.forEach(function (cue) {
    cue.html += "<p>Transformed!</p>"
  });
  return cues;
});

For more information on media transforms please check Using media transforms.

Redirect Notice

1. Adding Captions

2. Adding Captions for Multiple Languages

3. Using Embedded Captions

4. Custom Rendering

5. Using Cue Point Transformation