Ingesting WebVTT Files (Text Tracks/Captions)

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Add Videos/Assets
Topic(s)
Captions
Text Tracks
API(s)
Dynamic Ingest API

Dynamic Ingest can be used to ingest WebVTT files (for captions, subtitles, chapters, etc.) with your video, or separately, after the video has been ingested. For Dynamic Delivery videos, you can also ingest SRT or DFXP captions, and Brightcove will convert them to WebVTT automatically. This topic explains the details of adding text tracks files to your videos using the Dynamic Ingest API.

Setup

The setup for Dynamic Ingest requests is the same, whether you are ingesting a video, images, a WebVTT file, or all of these:

Request URL
https://ingest.api.brightcove.com/v1/accounts/account_id/videos/video_id/ingest-requests
Authentication
Authentication requires an access token passed as a Bearer token in an Authorization header:
Authorization: Bearer {access_token}

Note on S3

If your WebVTT will be pulled from a protected S3 bucket, you will need to set a bucket policy to allow Video Cloud to access the files. See Using Dynamic Ingest with S3 for details.

Ingest WebVTT files

You can also add WebVTT captions to your video or upload them for an existing video using Dynamic Ingest:

Add text tracks during video ingestion

Request URL

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

Method

POST

Sample request body

{
    "master": {
        "url":"http://learning-services-media.brightcove.com/videos/mp4/Water-Droplet.mp4"
    },
    "profile": "multi-platform-standard-static",
    "capture-images": false,
    "text_tracks": [
        {
"url": "http://learning-services-media.brightcove.com/captions/for_video/Water-in-Motion.vtt",
"srclang": "en",
"kind": "captions",
"label": "English",
"default": true
        }
    ]
}

Adding/converting SRT or DFXP

For Dynamic Delivery videos only, you can ingest SRT or DFXP files in the same way. The Video Cloud ingest system will automatically convert them to WebVTT format and add them to the video.

{
    "text_tracks": [
      {
        "url": "http://media.brightcove.com/captions/Water.dfxp",
        "srclang": "fr",
        "kind": "captions",
        "label": "français",
        "default": true
      }
    ]
  }

Add text tracks existing videos

Adding text tracks to existing videos is exactly the same, except that you do not need any of the video information in the request body.

Request URL

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

Method

POST

Sample request body

{
  "text_tracks": [
    {
      "url": "http://learning-services-media.brightcove.com/captions/for_video/Water-in-Motion.vtt",
      "srclang": "es",
      "kind": "captions",
      "label": "Español",
      "default": true
    }
  ]
}

Adding text tracks to a remote asset video

See Adding Text Tracks to Remote Asset Videos.