Adding Captions to Videos Programmatically

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:

Create a captions file for your video
Modify the player publishing code to include a <track> tag
Style the captions
Use code to add captions

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). (If you ingest captions to a Dynamic Delivery account, you can add DFXP or SRT captions, and these will be automatically converted to WebVTT captions.) 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 caption file for each 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 Overview: Adding Captions to a Video.

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.

Note that 2- or 4-letter language codes can be used for the srclang attribute (e.g. en or en-us).

Generate the Advanced (In-Page) embed code for your player. This can be done using the Media 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 
    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 
    controls="" 
    width="640" height="360">
</video-js>
<script src="https://players.brightcove.net/20318290001/default_default/index.min.js"></script>

To the <video-js> element, we added an id attribute with a value of myPlayerID. This is needed to get a reference to the player in step 3.

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 
    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 
    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>

(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.one("play", function () {
      //If you want to start English as the caption automatically
      myPlayer.textTracks()[1].mode = "showing";
    });
  });
</script>

Publish the page with the player. When a player with associated captions is published, a CC button will appear on the player chrome.
Click the CC button to select a caption language and display the captions.

Styling captions

In this section you will see how to programmatically style captions. For information on styling captions by altering the WebVTT file, and also the UI in the player, see the Styling Captions document.

Two methods are key to programmatically style captions, those being:

player.textTrackSettings.setValues(): Dynamically sets styles on the captions in a player
player.textTrackSettings.saveSettings(): Saves settings to the browser's localStorage

setValues(objectOfStyles)

There is a limited set of styles you can change for captions, which are detailed below. An example of using these styles is shown in the following code, and will display captions as shown in the screenshot:

videojs.getPlayer('myPlayerID').ready(function () {
    var myPlayer = this;
    myPlayer.  textTrackSettings.setValues({
      backgroundColor: "#FF0",
      color: "#00F",
      fontFamily: "monospaceSansSerif",
      fontPercent: 1.5,
      windowColor: "#0FF",
      windowOpacity: "0.5"
    }) ;
});

The window is the cyan colored rectangle that is nearly the full width of the player. It is common NOT to use a window, hence the default opacity is 0.

Listed in the table below are the caption styles you can alter, and the valid values for those styles:

Keys	Valid Values
`backgroundColor`	Valid colors as defined below
`backgroundOpacity`	`1` (opaque) `.5` (semi-transparent)
`color`	Valid colors as defined below
`edgeStyle`	`none raised depressed uniform dropshadow`
`fontFamily`	`proportionalSansSerif monospaceSansSerif proportionalSerif monospaceSerif casual script small-caps`
`fontPercent` (NOT in quotes in the object)	`0.50 0.75 1.00 1.25 1.50 1.75 2.00 3.00 4.00`
`textOpacity`	`1` (opaque) `.5` (semi-transparent)
`windowColor`	Valid colors as defined below
`windowOpacity`	`1` (opaque) `.5` (semi-transparent) `0` (transparent)

For the values above that use colors, the valid color values are shown here:

Valid Colors
`#000` (Black)
`#00F` (Blue)
`#0FF` (Cyan)
`#0F0` (Green)
`#F0F` (Magenta)
`#F00` (Red)
`#FFF` (White)
`#FF0` (Yellow)

saveSettings()

Another method that could be helpful when styling captions is player.textTrackSettings.saveSettings(). This method saves to the browser's localStorage the current settings of caption styling. The following screenshot from Chrome's Application tab shows the local storage for the page serving the player and the name of the key, vjs-text-track-settings, and its associated values.

This method gives you the possibility to configure the caption styles using the player's UI, then save the settings and copy the values to use with player.textTrackSettings.setValues(), as shown above.

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>

If you run into timing issues on Safari, please try this approach instead:

  
    myPlayer.one('canplay', function () => {
      setPlayerSubtitles(media, player, isLiveVideo) 
    })

The complementary method textTracks() enables you to retrieve all text tracks assigned to a player. The method returns an 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
Because Safari uses the native capabilities for styling captions, the Captions Settings menu option is not available in the the CC menu on Safari browsers (both iOS and macOS).
As noted earlier in the document, and repeated here, for viewers on iOS devices, when viewing videos with captions and ads, we suggest that you explicitly select a track and not set captions to Auto (Recommended) when the video is playing. Using the Auto (Recommended) setting may display incorrect subtitles for ads. Note that using the Auto (Recommended) setting does not affect the captions display for the actual video. Viewers will see video captions for ads but once the video starts playing (pre-rolls) or resumes (mid-rolls), captions will appear as expected. Also note that this "Auto" option cannot be removed due to an OS limitation from Apple. Apple devices use their own native player, therefore, customizing caption options is not possible.