Adding Captions to Videos Programmatically

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Topic(s)
Captions

In this topic, you will learn how to add captions to videos using the new Brightcove player.

Overview

Closed captions can be added to your videos to provide additional or interpretive information to individuals who wish to access it. Captions are necessary so the deaf and hard of hearing can access the audio portion of video presentations. To display captions for a video in the Brightcove player, you need to complete the following tasks:

Creating caption files

To add captions to a video, you first need to create a caption file. The Brightcove Player requires that captions be in Web Video Text Tracks Format (WebVTT) format. The WebVTT file format is in plain text and contains time text data followed by the desired caption or subtitle text. A portion of a WebVTT file is shown below.

WEBVTT

00:00:00.000 --> 00:00:07.080 align:middle line:90%

00:00:07.080 --> 00:00:10.280 align:middle line:84%
Hi, I'm Bob Bailey, a Learning
Specialist with Brightcove.

00:00:10.280 --> 00:00:12.780 align:middle line:84%
In this video, you'll learn
about how Video Cloud Studio is

00:00:12.780 --> 00:00:14.940 align:middle line:84%
organized and get a
brief overview of what

00:00:14.940 --> 00:00:17.490 align:middle line:90%
you can accomplish using it.

For more information on the WebVTT format, see this link. You should have a separate WebVTT file for each caption language you need to support. While there are many third-party tools to help create captions files, Brightcove has several partners that provide transcription, captioning and translation services. For a complete list of Brightcove partners, visit the Partners section of our website.

If you are using Dynamic Delivery videos, you can also ingest SRT or DFXP captions, and Brightcove will convert them to WebVTT automatically. See the Ingesting WebVTT Files (Text Tracks/Captions) document for more information.

Add captions to videos

In Video Cloud, you can add your WebVTT captions to a video, either as a remote asset that you host, or by ingesting it into Video Cloud. Once you do that, the Brightcove player will automatically add the captions when it loads that video, and display the CC button in the player controls. For more details on adding captions to videos, see Working with Captions.

Including a <track> tag

To associate WebVTT caption file(s) to a Brightcove player, you need to modify the In-Page embed code to include <track> tag for each caption file you have. For example:

<track kind="captions" src="<location of caption file>" srclang="en" label="English">

The <track> tag is used to specify subtitles, caption files or other files containing text, that should be visible when the media is playing. The steps to do this are outlined below.

  1. Generate the Advanced (In-Page) embed code for your player. This can be done using the Media module or the Players module.
    Your code should look similar to this:
    <video-js id="myPlayerID"
      data-video-id="4230322585001"
      data-account="20318290001"
      data-player="default"
      data-embed="default"
      data-application-id
      class="video-js"
      controls
      width="640"
      height="360">
    </video-js>
    <script src="https://players.brightcove.net/20318290001/default_default/index.min.js"></script>
    <video-js id="myPlayerID"
      data-account="20318290001"
      data-player="d508c6e1-efa7-4aad-ba91-1a8db9761b8c"
      data-embed="default"
      data-application-id
      class="video-js"
      controls
      width="640"
      height="360">
    </video-js>
    <script src="https://players.brightcove.net/20318290001/default_default/index.min.js"></script>
  2. Add <track> tag(s) inside of the <video-js> tag that point to location of all caption files. Player Studio does not currently provide a way for publishers to upload WebVTT caption files. The URL for the caption file location must be less than 250 characters.

    In the example below, English, Japanese and French caption files have been specified. For a complete list of language codes, see the HTML Language Code Reference.
    <video-js id="myPlayerID"
      data-video-id="4230322585001"
      data-account="20318290001"
      data-player="default"
      data-embed="default"
      data-application-id
      class="video-js"
      controls
      width="640"
      height="360">
      <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs.vtt" srclang="en" label="English">
      <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs-jp.vtt" srclang="ja" label="Japanese">
      <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs-fr.vtt" srclang="fr" label="French">
    </video-js>
    <script src="https://players.brightcove.net/20318290001/default_default/index.min.js"></script>
    <video-js id="myPlayerID"
      data-account="20318290001"
      data-player="d508c6e1-efa7-4aad-ba91-1a8db9761b8c"
      data-embed="default"
      data-application-id
      class="video-js"
      controls
      width="640"
      height="360">
      <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs.vtt" srclang="en" label="English">
      <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs-jp.vtt" srclang="ja" label="Japanese">
      <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs-fr.vtt" srclang="fr" label="French">
    </video-js>
    <script src="https://players.brightcove.net/20318290001/default_default/index.min.js"></script>
                  
  3. (Optional) To have captions automatically display when the video starts playing you have to make a couple of changes to your page. You have to add the default attribute to the <track> tag for the language to display and set and add a small amount of code. Note that the default attribute should only appear on one <track> tag. For example, to have the English captions display when the video starts playing, the <track> tag would be modified as follows:
    <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs.vtt" srclang="en" label="English" default>
    <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs-jp.vtt" srclang="ja" label="Japanese">
    <track kind="captions" src="https://solutions.brightcove.com/bcls/assets/captions/intro-vcs-fr.vtt" srclang="fr" label="French">

    The code needed to start the designated captions automatically is:

    <script type="text/javascript">
      videojs.getPlayer('myPlayerID').ready(function() {
        var myPlayer = this;
        myPlayer.on("play", function () {
          //If you want to start English as the caption automatically
          myPlayer.textTracks()[1].mode = "showing";
        });
      });
    </script>
  4. Publish the page with the player. When a player with associated captions is published, a CC button will appear on the player chrome.
    CC button on toolbar
  5. Click the CC button to select a caption language and display the captions.
    captions menu

Styling captions

The default look and feel of the captions is subject to change so you may wish to style the captions. For information on styling captions, see Styling Captions.

Implement using code

It is possible to programmatically add text tracks for captions. The key method for this functionality is addRemoteTextTrack(), the syntax of which is:

playerObject.addRemoteTextTrack({
  kind: string,
  language: string,
  label: string,
  src: string
});

where:

  • kind - Type of text track, for this use 'captions'
  • language - Two letter language code, for example 'en'
  • label - The language label which appears in the captions UI, for example 'English'
  • src - URL to the WebVTT formatted caption file

The function call returns an object of type vjs.TextTrack.

Example usage:

var frTrack = myPlayer.addRemoteTextTrack({
  kind: 'captions',
  language: 'fr',
  label: 'French',
  src: 'https://solutions.brightcove.com/bcls/captions/adding_captions_to_videos_french.vtt'
});

You must wait for the loadedmetadata event to be dispatched before you use the addRemoteTextTrack() method. The following example shows the script block for adding English and French captions to a video.

<script type="text/javascript">
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;

    myPlayer.one("loadedmetadata",function(){

      var enTrack = myPlayer.addRemoteTextTrack({
        kind: 'captions',
        language: 'en',
        label: 'English',
        src: 'https://solutions.brightcove.com/bcls/captions/adding_captions_to_videos.vtt'
      });

      var frTrack = myPlayer.addRemoteTextTrack({
        kind: 'captions',
        language: 'fr',
        label: 'French',
        src: 'https://solutions.brightcove.com/bcls/captions/adding_captions_to_videos_french.vtt'
      });

    });
  });
</script>

The complementary method textTracks() enables you to retrieve all text tracks assigned to a player. The method returns a object of type vjs.TextTrackList.

Live streaming with captions

Up to this point in the document captions have been delivered as a separate file and associated with a video through the <track> element. This type of captions is sometimes referred to as out-of-band. The alternative method involves embedding the caption data directly into the video content, frequently live video streams, and is sometimes called in-band captions.

Brightcove Live currently supports 608 captions in-band (inside h.264 headers). If captions are inside the h.264 input signal (correctly signaled in the user_data packet) those are passed through to the h.264 outputs.

If you are using a broadcast Elemental live encoder you can get captions from SDI (EIA-608/CEA-608) or other sources (SCTE-20, SCC, Teletext, DVB-Sub, Ancillary, ARIB, TTML, SCTE-27, STL, SRT, SMI) and put them into the h.264 stream that you send to us. Other broadcast grade encoders probably can do the same, but we have not formally tested them.

WebVTT captions are not supported for Live streams.

Brightcove Player has support for in-band captions, and hence Live with captions, built into HLS, therefore no plugins are needed. Brightcove Player's implementation will work everywhere that native HLS isn't used. If native HLS is being used, support for in-band captions is OS and browser dependent. For instance, iOS's native HLS has full support for in-band captions.

Limitations

Captions are supported on the following device types and operating systems.

  • iOS 9+
  • Android 4+
  • Internet Explorer 8+
  • The latest Chrome, Safari, and Firefox browsers on desktops