Managing Text Tracks Using the CMS API

In this topic, you will learn how to use the CMS API to update WebVTT text tracks of your videos.

Introduction

Whether the text tracks are ingested or remote, you can use a PATCH request to update the metadata associated with the text tracks.

Notes

  • The methods explained in this document are for updating WebVTT files added to your videos. You can ingest WebVTT files to Video Cloud using the Dynamic Ingest API or add remote WebVTT files to your videos using the CMS API.

Authorization

Requests to the CMS API require an authorization header which contains 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

We recommend making the following request first to get the complete array:

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

Updating Text Tracks

When updating Text Tracks, some fields in Text Tracks Fields can be treated differently according to its type.

Text Track Fields
Field Type Remote Text Tracks Dynamic Ingested Text Tracks
id String READ-ONLY value. Required to identify the TT that needs to be updated.
account_id String Updates on this field will be ignored.
src String Required and limited to 255 characters. Updates on this field will be ignored.
srclang String Limited to 32 characters.
label String Limited to 255 characters.
kind Enum Valid values are:
  • subtitles
  • captions
  • descriptions
  • chapters
  • metadata
status enum Valid values (case-sensitive):
  • published - text tracks will be available to viewers
  • draft - text tracks will not be available to viewers
  • null - (default) text tracks will be available to viewers
mime_type String Limited to 32 characters. Updates on this field will be ignored.
asset_id String READ-ONLY value. Field not applicable for this type. Updates on this field will be ignored.
in_band_metadata_track_dispatch_type String Field not applicable for this type. Updates on this field will be ignored.
sources Array READ-ONLY value.
default Boolean true or false. The field default for ingested Text Tracks will have the same behavior for remote and ingested text tracks. You cannot add multiple default=true to text tracks with different srclang.  

Request

Applicable to Remote, Static and Dynamic Text Tracks.

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

Request body examples

Remote text tracks

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

        
          {
          "text_tracks" :
          [
          {
          "id" : "1234-1234-1234"
          "src" : "https://some.site.com/captions/bc_smart_ja.vtt",
          "srclang" : "ja",
          "label" : "日本人",
          "kind" : "captions",
          "mime_type" : null,
          "default" : true,
          "status": "published"
          },
          {
          "id" : "5678-5678-5678"
          "src" : "https://some.site.com/captions/bc_smart_es.vtt",
          "srclang" : "es",
          "label" : "español",
          "kind" : "descriptions",
          "mime_type" : null,
          "default" : false,
          "status": "published"
          }
          ]
          }
Static text tracks

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

        
          {
          "text_tracks" :
          [
          {
          "id" : "1234-1234-1234"
          "srclang" : "ja",
          "label" : "日本人",
          "kind" : "captions",
          "mime_type" : null,
          "default" : true,
          "status": "published"
          },
          {
          "id" : "5678-5678-5678"
          "srclang" : "es",
          "label" : "español",
          "kind" : "descriptions",
          "mime_type" : null,
          "default" : false,
          "status": "published"
          }
          ]
          }
Dynamic text tracks

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

        
          {
          "text_tracks" :
          [
          {
          "id" : "1234-1234-1234"
          "srclang" : "ja",
          "label" : "日本人",
          "kind" : "captions",
          "mime_type" : null,
          "default" : true,
          "status": "published"
          },
          {
          "id" : "5678-5678-5678"
          "srclang" : "es",
          "label" : "español",
          "kind" : "descriptions",
          "mime_type" : null,
          "default" : false,
          "status": "published"
          }
          ]
          }