Adding WebVTT Captions (Text Tracks)

In this topic, you will learn how to use the CMS API to add WebVTT text tracks for captions or chapters to your videos.

Introduction

WebVTT captions (text tracks) cannot be added when you initially create the video using a POST request:

  • For text tracks to be ingested in Video Cloud, the tracks can be included in the Dynamic Ingest request to ingest the video - see Ingesting WebVTT Files for details.
  • If the text tracks are going to be hosted at some remote location, they can be added to the video using a PATCH request to update the video metadata. See the CMS API Sample: Update Videos for an example of an update request.

Whether the text tracks are ingested or remote, you can you use a PATCH request to update the metadata associated with the text tracks (such as the scrlang or label, or whether the text tracks are the default for the video).

Also see Managing Text Tracks Using the CMS API for more information on differences in the way text track metadata is handled depending on whether the text tracks are remote, ingested with a static ingest profile, or ingested with a dynamic ingest profile.

Notes

  • When you update text tracks on a Dynamic Delivery video, the process is asynchronous, so the response status code will be 202 ACCEPTED, and the update will not happen immediately.
  • There is a limit of 1000 text tracks per video.
  • The text of the captions must be encoded UTF-8 to display properly for double-byte languages such as Japanese and Korean.
  • The preview player section in Studio cannot display remote text track files. Therefore, the CC button will not be visible.

Remote or ingested

Authorization

Requests to the CMS API require an authorization header which contain your access tokens. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

The operations you will need to update video metadata are video-cloud/video/update or video-cloud/video/all.

Syntax

Request

      https://cms.api.brightcove.com/v1/accounts/{{account_id}}/videos/{{video_id}}

Request body:

The request body will be a JSON object containing an array of text tracks:

      {"text_tracks" : [ {
        "src" : "https://some.site.com/captions/bc_smart_ja.vtt",
        "srclang" : "ja",
        "label" : "日本人",
        "kind" : "captions",
        "mime_type" : null,
        "default" : false
        }, {
        "src" : "https://some.site.com/captions/bc_smart_es.vtt",
        "srclang" : "es",
        "label" : "español",
        "kind" : "captions",
        "mime_type" : null,
        "default" : false
        }, {
        "src" : "https://some.site.com/captions/bc_smart_de.vtt",
        "srclang" : "de",
        "label" : "Deutsch",
        "kind" : "captions",
        "mime_type" : null,
        "default" : false
        }, {
        "src" : "https://some.site.com/captions/bc_smart_fr.vtt",
        "srclang" : "fr",
        "label" : "français",
        "kind" : "captions",
        "mime_type" : null,
        "default" : false
        }, {
        "src" : "https://some.site.com/captions/bc_smart.vtt",
        "srclang" : "en",
        "label" : "English",
        "kind" : "captions",
        "mime_type" : null,
        "default" : true
        }
        ]}

Replacing text tracks

Replacing existing text tracks (either uploaded or remote) is a two-step process:

  1. Remove the existing text tracks via a CMS API update (PATCH):

    API request (PATCH)

              https://cms.api.brightcove.com/v1/accounts/account_id/videos/video_id

    Request body

              {
            "text_tracks": []
            }
  2. If you are adding remote text tracks, add them via another CMS API update (PATCH) (optional - if you are uploading text tracks, skip to the next step):

    API request (PATCH)

              https://cms.api.brightcove.com/v1/accounts/account_id/videos/video_id

    Request body

              {
            "text_tracks": [
            {
            "src": "https://some.site.com/vtt/sample.vtt",
            "srclang": "en",
            "label": "EN",
            "kind": "captions",
            "mime_type": "text/webvtt"
            },
            {
            "src": "https://some.site.com/vtt/sample-es.vtt",
            "srclang": "es",
            "label": "ES",
            "kind": "captions",
            "mime_type": "text/webvtt"
            }
            ]
            }
  3. If you are uploading new text tracks instead, add them via a POST request to the Dynamic Ingest API:

    API request (POST)

              https://ingest.api.brightcove.com/v1/accounts/account_id/videos/video_id/ingest-requests

    Request body

              {
            "text_tracks": [
            {
            "url": "https://solutions.brightcove.com/bcls/assets/vtt/sample.vtt",
            "srclang": "en",
            "kind": "captions",
            "label": "EN",
            "default": true
            },
            {
            "url": "https://solutions.brightcove.com/bcls/assets/vtt/sample-ar.vtt",
            "srclang": "ar",
            "kind": "captions",
            "label": "AR",
            "default": false
            }
            ]
            }
  4. Make a GET request to the CMS API to verify that your new text tracks are associated with the video: 
              https://cms.api.brightcove.com/v1/accounts/account_id/videos/video_id