Ingesting WebVTT Files

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, DFXP, or SCC captions. This topic explains the details of adding text tracks files to your videos using the Dynamic Ingest API.

Adding closed captions to MP4 renditions

In addition to adding text tracks to your HLS and/or DASH renditions, you can add 608 closed captions to progressive MP4 renditions by including the "embed_closed_caption": true flag in your WebVTT ingest request.

To embed closed captions for a video you are ingesting, be sure to use an ingest profile that includes one or more MP4 renditions. If you are adding text tracks/closed captions to an existing video, be sure it has at least one MP4 rendition, or re-transcode with an ingest profile that will include MP4.

If you are using Cloud Playout, note that you can now import these closed captions into your channel to provide them to your viewers.

Notes

The languages currently supported for 608 embedded captions are: English, Spanish, French, Portuguese, Italian, German, and Dutch.
For embedded 608 captions only, only European (Latin) characters are supported. Double-byte languages such as Chinese and Japanese are not supported.
If the source file already contains 608 closed captions, those will not be retained in any MP4 renditions.instead new closed captions will be embedded using the contents of the ingested captions.
Closed captions currently cannot be added while you are retranscoding video - you must be ingesting or replacing the video. Retranscode jobs will support this feature in a future release.
This feature cannot be used when you are requesting auto captions.
If your account is enabled for Cloud Playout, you can verify that the closed captions were added by including the video in a channel (Cloud Playout channels always use MP4 renditions).

Note that 2- or 4-letter language codes can be used for the srclang attribute (e.g. en or en-us). Brightcove strongly recommends to lookup for the correct language codes.

Setup

The setup for Dynamic Ingest requests is the same, whether you are ingesting a video, images, a WebVTT file, or all of these. For full details of the request body fields, see the API Reference.

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": "https://support.brightcove.com/test-assets/videos/Great_Blue_Heron.mp4"
  },
  "text_tracks": [
      {
          "url": "https://support.brightcove.com/test-assets/captions/herons.vtt",
          "srclang": "en",
          "kind": "captions",
          "label": "EN",
          "default": true,
          "status" : "published",
          "embed_closed_caption": 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": "https://media.brightcove.com/captions/Water.dfxp",
      "srclang": "fr",
      "kind": "captions",
      "label": "français",
      "default": true,
      "status" : "published",
      "embed_closed_caption": true
    }
  ]
}

Note: set embed_closed_captions to true to add 608 captions to MP4 renditions.

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 or the profile in the request body. unless you are requesting closed captions to be added to MP4 renditions - in that case, you will need to replace the video

Request URL

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

Method

POST

Sample request body - no closed captions requested

{
  "text_tracks": [
    {
      "url": "https://support.brightcove.com/test-assets/captions/herons.vtt",
      "srclang": "es",
      "kind": "captions",
      "label": "Español",
      "default": true,
      "status" : "published",
      "embed_closed_caption": false
    }
  ]
}

Sample request body - closed captions requested

{
  "master": {
      "url": "https://support.brightcove.com/test-assets/videos/Great_Blue_Heron.mp4"
  },
  "text_tracks": [
      {
          "url": "https://support.brightcove.com/test-assets/captions/herons.vtt",
          "srclang": "en",
          "kind": "captions",
          "label": "EN",
          "default": true,
          "status" : "published",
          "embed_closed_caption": true
      }
  ]
}

Notes:

Caption file names should only include letters (upper or lower case), numbers, dashes (-) and underscores (_).
The label for the captions is used by the Brightcove player for the captions language menu. Best practice is to use the appropriate language for the label. For example: français for French and so forth.
The text of the captions must be encoded UTF-8 to display properly for double-byte languages such as Japanese and Korean.
The default value is not per track, but set to true for all tracks of the same language (srclang).
For images and text tracks, only public HTTP or HTTPS URLs or signed URLs for AWS S3 or Google Cloud Storage are supported.
for text tracks, Dynamic Ingest adds/appends them to the video’s vtt list even if it is a re-encode request. You should use the CMS API to manage them (update/delete).
Dynamic Ingest accepts up to 100 text tracks at a time.
Although "mime_type": "text/vtt" is generally supported for WebVTT, Dynamic Ingest does not currently allow that field for ingestion of text tracks.

Adding text tracks to a remote asset video

See Adding Text Tracks to Remote Asset Videos.