Using the CMS API: Add WebVTT Captions (Text Tracks)

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Manage Videos
Topic(s)
Accessibility
Captions
Text Tracks
API(s)
CMS API

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

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.

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:


 

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://learning-services-media.brightcove.com/vtt/sample.vtt",
              "srclang": "en",
              "label": "EN",
              "kind": "captions",
              "mime_type": "text/webvtt"
            },
            {
              "src": "https://learning-services-media.brightcove.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": "http://solutions.brightcove.com/bcls/assets/vtt/sample.vtt",
                "srclang": "en",
                "kind": "captions",
                "label": "EN",
                "default": true
            },
            {
                "url": "http://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