Overview: Playback API

Product(s)
Video Cloud
Role(s)
API Developer
Device SDK Developer
Task(s)
Get Video Metadata
Topic(s)
API Overviews
Playback
API(s)
Playback API

The Playback API is used to fetch video and playlist data from Video Cloud. It is typically used to get video data to a player on a web page or in a mobile app.

Introduction

The Playback API is low-latency API intended for client-side use in fetching video or playlist data from web pages or mobile apps. It is not a general media management API to use in integrating Video Cloud with your CMS or other systems - for that, you should use the CMS API.

The Playback API results are filtered to only return playable videos (state=ACTIVE, ingestion complete flag = true, and in correct data/time if scheduled). This means that the player will be able to play the video as soon as one rendition exists, even if others are still processing. If you need to fetch videos that are not currently playable, you should again use the CMS API instead.

Be aware also that to maximize performance, the video data accessed by the Playback API is cached for a short period of time, similar to data returned by the older Media READ API. How long a particular data set id cached will vary, but may be up to 20 minutes.

Also see the API Reference.

Use cases

The Brightcove Player and the Brightcove SDK players include catalog methods identical to methods of the Playback API, and for the most part you can simply use those if you are just retrieving videos or playlists at runtime to play.

However, you may wish to provide a view of video or playlists in a mobile app screen where no player is present.

In addition, there may be occasions when you want to retrieve videos or playlists to display information about them, without having a player on the screen, as the landing page for a video portal, for example.

The Playback API is useful in these instances.

General Information

Base URL

The base URL for the Playback API is:

  https://edge.api.brightcove.com/playback/v1

Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}

Authentication

Requests are authenticated by a policy key, which can be passed in one of three ways:

  1. In an argument to an Accept header:
      Accept: application/json;pk={policy_key}

    This is the recommended method for a browser-based client, because it allows the request to go ahead without an extra request first as part of the browser CORS "pre-flight" checking. This saves latency on the first time a browser request is made.

  2. In an Authorization header using the realm keyword BCOV-Policy:
      Authorization: BCOV-Policy {policy_key}
  3. In a BCOV-Policy header:
      BCOV-Policy: {policy_key}

Obtaining a policy key

There are three ways you can obtain a policy key:

  1. Every Brightcove player is automatically assigned one. You can find instructions for getting a player's policy key in this document. Since policy keys are good account-wide, you can use it regardless of whether that player is embedded on the page.
  2. You can generate a basic policy key using the Policy Keys Quick Start
  3. You can make a request to the Policy API

Token authentication

Token authentication for HLS and DASH content is supported. If you need token authentication, contact your account manager about getting it enabled for your account.

Avoid hard-coded URLs

URLs for thumbnails, posters, video files, and other media should never be hard-coded in your pages or applications. The Playback API will return the latest cached version of URLs for media files, but the URLs themselves are subject to change. You should use the CMS API ( or Playback API ) requests to retrieve these URLs each time the page loads, or cache them for no more than six hours.

Caching video and image URLs

You can cache URLs for videos and images to improve page performance, but the cache must be refreshed regularly. If you cache the URLs you retrieve to improve the performance of your pages, be sure to refresh the cache by repeating the API calls at least once every six hours.

Methods

The API supports the following GET requests only, of the following types:

Video requests

A single video object can be retrieved using either the video id or reference id.

Get video by id

Endpoint

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

Example

  https://edge.api.brightcove.com/playback/v1/accounts/57838016001/videos/38467382999

Sample response

  {
    "account_id": "107767373999",
    "ad_keys": null,
    "created_at": "2010-07-12T22:37:34.760Z",
    "description": "Avatar_MakingAScene_Featurette",
    "duration": 595560,
    "id": "38467382999",
    "long_description": null,
    "name": "Avatar_MakingAScene_Featurette",
    "published_at": "2010-07-12T22:37:34.760Z",
    "reference_id": "AvatarMakingShort",
    "text_tracks": [],
    "updated_at": "2010-07-12T22:54:29.666Z",
    "cue_points": [
      {
        "id": "111637107001",
        "name": "Pre-roll",
        "type": "AD",
        "time": 0,
        "metadata": null,
        "force_stop": false
      }
    ],
    "custom_fields": {
      "moretext": "this is the first video uploaded",
      "mylist": "abc"
    },
    "link": {
      "text": "Full Dvd at Amazon",
      "url": "http://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
    },
    "tags": [
      "copied"
    ],
    "poster_sources": [
      {
        "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999"
      }
    ],
    "thumbnail_sources": [
      {
        "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999"
      }
    ],
    "poster": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
    "thumbnail": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999",
    "sources": [
      {
        "avg_bitrate": 379000,
        "width": 320,
        "duration": 595560,
        "size": 28196307,
        "stream_name": "mp4:107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
        "codec": "H264",
        "asset_id": "111728840001",
        "container": "MP4",
        "height": 180,
        "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
      },
      {
        "avg_bitrate": 379000,
        "width": 320,
        "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
        "size": 28196307,
        "height": 180,
        "duration": 595560,
        "container": "MP4",
        "codec": "H264",
        "asset_id": "111728840001"
      }, ... 6 more sources ...

    ]
  }

Get video by reference id

Endpoint

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/videos/ref:{reference_id}

Example

  https://edge.api.brightcove.com/playback/v1/accounts/57838016001/videos/ref:nature_2010-07-12

Sample response

  {
    "account_id": "107767373999",
    "ad_keys": null,
    "created_at": "2010-07-12T22:37:34.760Z",
    "description": "Avatar_MakingAScene_Featurette",
    "duration": 595560,
    "id": "38467382999",
    "long_description": null,
    "name": "Avatar_MakingAScene_Featurette",
    "published_at": "2010-07-12T22:37:34.760Z",
    "reference_id": "nature_2010-07-12",
    "text_tracks": [],
    "updated_at": "2010-07-12T22:54:29.666Z",
    "cue_points": [
      {
        "id": "111637107001",
        "name": "Pre-roll",
        "type": "AD",
        "time": 0,
        "metadata": null,
        "force_stop": false
      }
    ],
    "custom_fields": {
      "moretext": "this is the first video uploaded",
      "mylist": "abc"
    },
    "link": {
      "text": "Full Dvd at Amazon",
      "url": "http://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
    },
    "tags": [
      "copied"
    ],
    "poster_sources": [
      {
        "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999"
      }
    ],
    "thumbnail_sources": [
      {
        "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999"
      }
    ],
    "poster": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
    "thumbnail": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999",
    "sources": [
      {
        "avg_bitrate": 379000,
        "width": 320,
        "duration": 595560,
        "size": 28196307,
        "stream_name": "mp4:107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
        "codec": "H264",
        "asset_id": "111728840001",
        "container": "MP4",
        "height": 180,
        "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
      },
      {
        "avg_bitrate": 379000,
        "width": 320,
        "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
        "size": 28196307,
        "height": 180,
        "duration": 595560,
        "container": "MP4",
        "codec": "H264",
        "asset_id": "111728840001"
      }, ... 6 more sources ...

    ]
  }

Search videos

You must use a search-enabled Policy Key, when searching for videos using the Playback API. For details, see the Playback API Reference document.

Parameters

Note that all parameters are optional. They apply to GET Videos requests only.

GET Videos Request Parameters
Parameter Description
q Query string for searches - for details, see the search guide
limit Number of videos to return - must be an integer between 1 and 100. Default: 20
offset Number of videos to skip (for paging results). Must be a positive integer. Default: 0
sort A string that specifies the field to sort by.
Start with - to sort descending.
If a value for q is provided, then the default sort is by "score" (relevance of the search results to the original query).
If no value for q is provided, then the default sort is by updated_at descending.
The following fields are valid for sort: name, reference_id, created_at, published_at, updated_at, schedule_starts_at, schedule_ends_at, state, plays_total, and plays_trailing_week
For details, see the Get Videos section of the Playback API reference

Brightcove's Playback API provides a programmatic way to search for videos in your Video Cloud library.

To perform basic and complex searches on your video data, you will use the q parameter:

https://edge.api.brightcove.com/playback/v1/accounts/1752604051111/videos?q={search terms}

For details on how to search for videos, see the Search Videos document.

Paging results

Use the limit parameter to specify how many items you want to return on a request - up to 100. You can then use the offset parameter to page through result sets that are larger than the limit. The offset is the number of items to skip.

For example, the following search returns videos 51-75 of the total result set, assuming the total result set has at least 75 videos:

  /videos?q=updated_at:2014-01-01..2014-06-30&limit=25&offset=50

The limit and offset parameters can only be used for videos.

Paging best practice

When paging through your result set from the Playback API, it is recommended to follow these steps:

  1. Use the limit and offset parameters to return groups of data from your result set.
    /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
  2. With each response, you will see that the count field always shows the maximum number of videos in your result set.
    {"count": 1471,
      "videos": [ ... ]
    }
  3. So, you can get the total count of videos from your first request can be used to determine how many more pages you will need to request.

    Alternatively, you can interrogate the count value with each response and continue until the count is less than or equal to page size times the limit.
    count <= page-number * limit

Sorting video results

Use the parameter sort=field_name to specify how the results should be sorted. You can sort on the following video fields:[1-1]

  • name
  • reference_id
  • created_at
  • published_at
  • updated_at
  • schedule_starts_at (note: this is the sort field - the search field is schedule.starts_at)
  • schedule_ends_at (note: this is the sort field - the search field is schedule.ends_at)
  • state
  • plays_total[1-2]
  • plays_trailing_week[1-2]

Notes

  • [1-1] If you do not provide a sort value for a video search call, the results will be sorted by relevance. If you do not provide a sort value for a GET videos call, the results will be sorted by updated_at descending.
  • [1-2] You can sort on plays_total or plays_trailing_week, but these fields are not included in the results

All videos and large data sets

If you are retrieving all the videos in your account, or a large number of videos, there are some things you must be aware of:

  1. You may be tempted to use the largest allowed page_size (100), but it's better to retrieve videos in batches of 25 or less to minimize the possibility of API requests timing out
  2. As you are paging through large data sets, it is possible that the video data may be updated during the operation, which could cause items to shift in responses:
    • You might see an item repeated on successive pages
    • An item might be missed, as it has shifted to a previous response set

    To account for the first possibility, your app should de-dupe the complete item list after you have finished retrieving videos. To handle the second possibility, you need to compare the total number of items retrieved (after de-duping) to the number you were expecting, and then rerun the requests, sorting the results by last_modified_date (descending) - you shouldn't need to retrieve more than one batch to pick up missed items.

  3. You can decrease the likelihood of the scenarios in the previous item by sorting the returned results appropriately. The default sorting by relevance for searches is based on a complex algorithm that looks combinations of keywords, tags, and custom field values. If you are searching for videos based on multiple keywords, tags, and/or custom fields, sort by relevance is exactly what you want. However, if you are just trying to retrieve all or a large set of your videos, setting the sort_by parameter explicitly will give you more control over the order of the returned items.

Get videos

Endpoint

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/videos

Example

  https://edge.api.brightcove.com/playback/v1/accounts/57838016001/videos?q=tags:nature,name:nature

Sample response

  {
    "count": 123,
    "videos":
      [
        {<video1 fields>},
        {<video2 fields>},
        ...
      ]
  }

Error response

if you attempt to use the Get Videos endpoint with a Policy Key that is NOT search-enabled, you will receive the following error message from the Playback API:

  [
    {
      "api_call": "search",
      "error_subcode": "API",
      "error_code": "ACCESS_DENIED",
      "message": "Access to this resource is forbidden by access policy."
    }
  ]

The Playback API allows you to search your account for videos that are related to the specified video. Based on the name and short description of the specified video, the API will search for any partial matches in the following fields:

  • name
  • short description
  • long description
  • tags

If geo-restriction is in effect, you may not receive a full page of results.

Parameters

The following URL parameters can be used for GET related videos requests:

GET Related Videos Request Params
Parameter Description
limit The number of videos to return (default=20; maximum=100)
ad_config_id Append your ad_config_id to return videos with SSAI

By default, the response will contain up to 20 videos. You may use the limit parameter to return up to a maximum of 100 videos, with a cost of increased latency.

Notice that there is no offset parameter when finding related videos, so you will not be able to page through your video results.

Get related videos using video id

Endpoint

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/videos/{video_id}/related

Example

  https://edge.api.brightcove.com/playback/v1/accounts/1752604059001/videos/5565662146001/related

Get related videos using reference id

Endpoint

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/videos/ref:{reference_id}/related

Example

  https://edge.api.brightcove.com/playback/v1/accounts/1752604059001/videos/ref:nature/related

Sample response

In the response below, notice that there is no count field, unlike the search videos response.

{
  "videos":
    [
      {<video1 fields>},
      {<video2 fields>},
      ...
    ]
}

Error response

If you attempt to use the find related endpoint with a Policy Key that is NOT search-enabled, you will receive the following error message from the Playback API:

[
  {
    "api_call": "search",
    "error_subcode": "API",
    "error_code": "ACCESS_DENIED",
    "message": "Access to this resource is forbidden by access policy."
  }
]

Video request with SSAI

Even if you are NOT using a Brightcove web player or the Brightcove Native SDKs in your application, you can still use Server-Side Ad Insertion (SSAI) with your own player.

Get video with SSAI

To return a video with SSAI, append your ad configuration id as a URL parameter to your Playback API request. With this request, you can use either a video Id or a video reference Id.

Endpoint with URL parameter

Append your ad_config_id to the end of the Playback API request:

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/videos/{video_id}?ad_config_id={ad_config_id}

Example

  https://edge.api.brightcove.com/playback/v1/accounts/1752604059001/videos/5565662146001?ad_config_id=1234abcd

In the sample response below, you will notice the following:

  • The response is similar to that if you didn't include an ad config Id.
  • The elements of the sources array will contain a new property called vmap.
  • If you want to know where the ads are located in the content, you can read the VMAP file linked in the vmap property.
  • The src property within the sources array will contain the URL to the HLS or DASH source. This is the same as the response when no ad config Id is used, but the src will have ads stitched in with the main content.

For more information about the Brightcove Once UX ad service and VMAP files, see the Brightcove Once UX Implementation guide.

Sample response

  {
    "description": "The story of a giant rabbit with a heart bigger than himself. ",
    "poster_sources": [
    	{
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/3723496277001/dd5bd69c-e962-4a43-9dbd-94faaaba1785/main/1280x720/5m17s130ms/match/image.jpg"
    	}
    ],
    "tags": [],
    "cue_points": [],
    "custom_fields": {},
    "account_id": "3723496277001",
    "sources": [
    	{
        "ext_x_version": "4",
        "vmap": "http://ssaiplayback.prod.boltdns.net/playback/once/v1/vmap/hls/v4/clear/3723496277001/7a3316d9-1b06-4d62-bec8-3919b43fffbb/dd5bd69c-e962-4a43-9dbd-94faaaba1785/content.vmap?bc_token=NTllMTMxYjNfMTdkOTY2YThhNjU5MDk5ZTQ3NDBkNmUxOTYyOGRkNzM0ZjBiM2RjMGEwOThjOGFkYjk1MWQxMzFmNGYzMjA5YQ%3D%3D",
        "type": "application/x-mpegURL",
        "src": "http://ssaiplayback.prod.boltdns.net/playback/once/v1/hls/v4/clear/3723496277001/7a3316d9-1b06-4d62-bec8-3919b43fffbb/dd5bd69c-e962-4a43-9dbd-94faaaba1785/master.m3u8?bc_token=NTllMTMxYjNfZGM5ZDg0NGM2ZGJjZDcxZTFjOGYyODBlMzM2NmNmMmJkMWNhZDczNWViNzRiMjIwNjg5MjkzZGM0ZmJlMTc1Yw%3D%3D"
    	},
      ...
    ],
    "created_at": "2017-05-15T17:09:11.171Z"
  }

Require ad_config_id

Using the Policy API, you can create a policy key that requires you to include the ad_config_id URL parameter when making requests to the Playback API. For details about setting this feature, see the Policy API Reference document.

When the policy key is set to require an ad_config_id, and you do not append it to a Playback API request, you will get the following error:

  [
    {
    	"error_subcode": "AD_CONFIG",
    	"error_code": "ACCESS_DENIED",
    	"message": "Missing required ad_config_id parameter"
    }
  ]

Playlist requests

A playlist video object can be retrieved using either the playlist id or its reference id.

Parameters

The following URL parameters can be used for playlist requests

Playlist Request Params
Parameter Description
limit The number of videos to return (default=20; maximum=100)
offset number of videos to skip (from the start of the playlist; default=0)

For example, these parameters appended to your request - ?limit=40&offset=20 - would return videos 21-60 in the playlist (assuming there are that many).

Get playlist by id

Endpoint

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/playlists/{playlist_id}

Example

  https://edge.api.brightcove.com/playback/v1/accounts/57838016001/playlists/38467382999

Sample response

  {
    "account_id": "107767373999",
    "created_at": "2010-07-12T22:43:30.290Z",
    "description": null,
    "id": "111592530001",
    "name": "Play One",
    "reference_id": null,
    "type": "EXPLICIT",
    "updated_at": "2010-07-12T22:51:25.055Z",

    "videos": [
      {
        "description": "Avatar_MakingAScene_Featurette",
        "poster_sources": [
          {
            "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999"
          }
        ],
        "tags": [
          "copied"
        ],
        "cue_points": [
          {
            "id": "111637107001",
            "name": "Pre-roll",
            "type": "AD",
            "time": 0,
            "metadata": null,
            "force_stop": false
          }
        ],
        "custom_fields": {
          "moretext": "this is the first video uploaded",
          "mylist": "abc"
        },
        "account_id": "107767373999",
        "sources": [
          {
            "avg_bitrate": 379000,
            "width": 320,
            "duration": 595560,
            "size": 28196307,
            "stream_name": "mp4:107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728840001",
            "container": "MP4",
            "height": 180,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 379000,
            "width": 320,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 28196307,
            "height": 180,
            "duration": 595560,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728840001"
          },
          {
            "avg_bitrate": 267000,
            "width": 320,
            "duration": 595560,
            "size": 19894997,
            "stream_name": "mp4:107767373999/107767373999_111728852001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728852001",
            "container": "MP4",
            "height": 180,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 267000,
            "width": 320,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728852001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 19894997,
            "height": 180,
            "duration": 595560,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728852001"
          },
          {
            "avg_bitrate": 549000,
            "width": 480,
            "duration": 595567,
            "size": 40889436,
            "stream_name": "mp4:107767373999/107767373999_111728860001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728860001",
            "container": "MP4",
            "height": 268,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 549000,
            "width": 480,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728860001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 40889436,
            "height": 268,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728860001"
          },
          {
            "avg_bitrate": 835000,
            "width": 640,
            "duration": 595567,
            "size": 62142992,
            "stream_name": "mp4:107767373999/107767373999_111728865001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728865001",
            "container": "MP4",
            "height": 360,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 835000,
            "width": 640,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728865001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 62142992,
            "height": 360,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728865001"
          },
          {
            "avg_bitrate": 1744000,
            "width": 640,
            "duration": 595567,
            "size": 129836869,
            "stream_name": "mp4:107767373999/107767373999_111735357001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111735357001",
            "container": "MP4",
            "height": 360,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 1744000,
            "width": 640,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111735357001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 129836869,
            "height": 360,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111735357001"
          },
          {
            "avg_bitrate": 1249000,
            "width": 640,
            "duration": 595567,
            "size": 92994065,
            "stream_name": "mp4:107767373999/107767373999_111735369001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111735369001",
            "container": "MP4",
            "height": 360,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 1249000,
            "width": 640,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111735369001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 92994065,
            "height": 360,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111735369001"
          }
        ],
        "name": "Avatar_MakingAScene_Featurette",
        "reference_id": "AvatarMakingShort",
        "long_description": null,
        "duration": 595560,
        "published_at": "2010-07-12T22:37:34.760Z",
        "text_tracks": [],
        "updated_at": "2010-07-12T22:54:29.666Z",
        "thumbnail": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999",
        "poster": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
        "link": {
          "text": "Full Dvd at Amazon",
          "url": "http://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
        },
        "id": "38467382999",
        "ad_keys": null,
        "thumbnail_sources": [
          {
            "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999"
          }
        ],
        "created_at": "2010-07-12T22:37:34.760Z"
      }
    ],
  }

Get playlist by reference id

Endpoint

  https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/playlists/ref:{reference_id}

Example

  https://edge.api.brightcove.com/playback/v1/accounts/57838016001/playlists/ref:nature_2010-07-12

Sample response

  {
    "account_id": "107767373999",
    "created_at": "2010-07-12T22:43:30.290Z",
    "description": null,
    "id": "111592530001",
    "name": "Play One",
    "reference_id": nature_2010-07-12,
    "type": "EXPLICIT",
    "updated_at": "2010-07-12T22:51:25.055Z",

    "videos": [
      {
        "description": "Avatar_MakingAScene_Featurette",
        "poster_sources": [
          {
            "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999"
          }
        ],
        "tags": [
          "copied"
        ],
        "cue_points": [
          {
            "id": "111637107001",
            "name": "Pre-roll",
            "type": "AD",
            "time": 0,
            "metadata": null,
            "force_stop": false
          }
        ],
        "custom_fields": {
          "moretext": "this is the first video uploaded",
          "mylist": "abc"
        },
        "account_id": "107767373999",
        "sources": [
          {
            "avg_bitrate": 379000,
            "width": 320,
            "duration": 595560,
            "size": 28196307,
            "stream_name": "mp4:107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728840001",
            "container": "MP4",
            "height": 180,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 379000,
            "width": 320,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728840001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 28196307,
            "height": 180,
            "duration": 595560,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728840001"
          },
          {
            "avg_bitrate": 267000,
            "width": 320,
            "duration": 595560,
            "size": 19894997,
            "stream_name": "mp4:107767373999/107767373999_111728852001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728852001",
            "container": "MP4",
            "height": 180,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 267000,
            "width": 320,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728852001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 19894997,
            "height": 180,
            "duration": 595560,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728852001"
          },
          {
            "avg_bitrate": 549000,
            "width": 480,
            "duration": 595567,
            "size": 40889436,
            "stream_name": "mp4:107767373999/107767373999_111728860001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728860001",
            "container": "MP4",
            "height": 268,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 549000,
            "width": 480,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728860001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 40889436,
            "height": 268,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728860001"
          },
          {
            "avg_bitrate": 835000,
            "width": 640,
            "duration": 595567,
            "size": 62142992,
            "stream_name": "mp4:107767373999/107767373999_111728865001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111728865001",
            "container": "MP4",
            "height": 360,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 835000,
            "width": 640,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111728865001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 62142992,
            "height": 360,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111728865001"
          },
          {
            "avg_bitrate": 1744000,
            "width": 640,
            "duration": 595567,
            "size": 129836869,
            "stream_name": "mp4:107767373999/107767373999_111735357001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111735357001",
            "container": "MP4",
            "height": 360,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 1744000,
            "width": 640,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111735357001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 129836869,
            "height": 360,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111735357001"
          },
          {
            "avg_bitrate": 1249000,
            "width": 640,
            "duration": 595567,
            "size": 92994065,
            "stream_name": "mp4:107767373999/107767373999_111735369001_Avatar-MakingAScene-Featurette.mp4?__nn__=1497926354001&slist=107767373999/&auth=daEciavcicRbhbtdSaBdBdVbXd0aUdTcMaX-bvRrSa-hca-slyCzrux_zJAq_HFCB_EvE&aifp=bcosuds",
            "codec": "H264",
            "asset_id": "111735369001",
            "container": "MP4",
            "height": 360,
            "app_name": "rtmp://cp150446.edgefcs.net/ondemand"
          },
          {
            "avg_bitrate": 1249000,
            "width": 640,
            "src": "http://uds.ak.o.brightcove.com/107767373999/107767373999_111735369001_Avatar-MakingAScene-Featurette.mp4?pubId=107767373999&videoId=38467382999",
            "size": 92994065,
            "height": 360,
            "duration": 595567,
            "container": "MP4",
            "codec": "H264",
            "asset_id": "111735369001"
          }
        ],
        "name": "Avatar_MakingAScene_Featurette",
        "reference_id": "AvatarMakingShort",
        "long_description": null,
        "duration": 595560,
        "published_at": "2010-07-12T22:37:34.760Z",
        "text_tracks": [],
        "updated_at": "2010-07-12T22:54:29.666Z",
        "thumbnail": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999",
        "poster": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
        "link": {
          "text": "Full Dvd at Amazon",
          "url": "http://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
        },
        "id": "38467382999",
        "ad_keys": null,
        "thumbnail_sources": [
          {
            "src": "http://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999"
          }
        ],
        "created_at": "2010-07-12T22:37:34.760Z"
      }
    ],
  }

Captions

Closed captions provide additional information about your video for individuals who wish to access it. Captions are necessary for the deaf and hard of hearing to access the audio portion of your videos. If you are new to captions, see the Overview: Adding Captions to a Video document.

External WebVTT

External WebVTT captions are text files separate from the video. You can associate captions files with a video as follows:

Sample response

Below is a sample response from the Playback API where a WebVTT captions file has been added to a video using the Media module. Notice that the text track src properties point to an external captions file.

  {
  "text_tracks": [
  {
  	"mime_type": null,
  	"account_id": "20318290001",
  	"default": true,
  	"sources": [
  		{
  			"src": "https://static.3playmedia.com/p/files/2240988/threeplay_transcripts/6418302.vtt?project_id=10127&format_id=51&refresh=1515241856"
  		}
  	],
  	"src": "https://static.3playmedia.com/p/files/2240988/threeplay_transcripts/6418302.vtt?project_id=10127&format_id=51&refresh=1515241856",
  	"asset_id": null,
  	"label": "English",
  	"id": "13d66def-d004-4e75-b160-4ac693eff7d7",
  	"kind": "captions",
  	"srclang": "en"
  }
  ],
  }

In-manifest WebVTT

In-manifest WebVTT captions are ingested with your videos. This can be done when you first ingest your video or after your video has been ingested. You can create in-manifest captions as follows:

Sample response

Below is a sample response from the Playback API where a WebVTT captions file has been added to a video using the Dynamic Ingest API. Notice that the text track src properties point to internal Brightcove files.

  {
  "text_tracks": [
  {
  	"mime_type": "text/webvtt",
  	"account_id": "1752604059001",
  	"default": false,
  	"sources": [
  		{
  			"src": "http://bcboltbde696aa-a.akamaihd.net/media/v1/text/vtt/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/text.vtt?akamai_token=exp=1518032480~acl=/media/v1/text/vtt/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/text.vtt*~hmac=5aa9f206a8e970efb4cab95278e2e9b16a29b3ccf82951a91245352d9149b173"
  		},
  		{
  			"src": "https://bcboltbde696aa-a.akamaihd.net/media/v1/text/vtt/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/text.vtt?akamai_token=exp=1518032480~acl=/media/v1/text/vtt/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/text.vtt*~hmac=5aa9f206a8e970efb4cab95278e2e9b16a29b3ccf82951a91245352d9149b173"
  		}
  		],
  	"src": "http://bcboltbde696aa-a.akamaihd.net/media/v1/text/vtt/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/text.vtt?akamai_token=exp=1518032480~acl=/media/v1/text/vtt/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/text.vtt*~hmac=5aa9f206a8e970efb4cab95278e2e9b16a29b3ccf82951a91245352d9149b173",
  	"asset_id": null,
  	"label": "EN",
  	"id": "92cb36a7-c836-4506-a87f-f649316c0cdf",
  	"kind": "captions",
  	"in_band_metadata_track_dispatch_type": "",
  	"srclang": "en"
  }
  ],
  }

Manifest

The manifest for the HLS or DASH video files also contain the necessary information to include the WebVTT captions.

HLS
  #EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio-0",NAME="en (Main)",DEFAULT=YES,AUTOSELECT=YES,LANGUAGE="en",URI="https://manifest.prod.boltdns.net/manifest/v1/hls/v4/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/8b12c808-c5ea-47f3-abfa-c23b023db297/10s/rendition.m3u8?fastly_token=NWE3YjU3ZThfNzAwNTczOWM4MWQ4Mzk2NjFkYjVjYmFhYjQwNzY2MWUzM2MyNDM5ZDA5ZGExYTFkMzRmYzA0MDdhOTlmZWJhMw%3D%3D"
  #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subtitles-0",NAME="EN",DEFAULT=YES,AUTOSELECT=YES,LANGUAGE="en",URI="https://manifest.prod.boltdns.net/manifest/v1/hls/v4/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf/rendition.m3u8?fastly_token=NWE3YjU3ZThfNDYzOThkZGJiZTU1NTlhOTdkYzA5OTA3M2UzZGRlYTgzMmRkZmUxMGIxYTJkY2Y5ZDQ1ODFiNTEyMmNiZDVhMw%3D%3D"
  #EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=519200,CODECS="mp4a.40.2,avc1.420015",RESOLUTION=480x270,AUDIO="audio-0",CLOSED-CAPTIONS=NONE,SUBTITLES="subtitles-0"
  https://manifest.prod.boltdns.net/manifest/v1/hls/v4/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/5f7850d9-9a65-4eee-8810-86a1e18e05fb/10s/rendition.m3u8?fastly_token=NWE3YjU3ZThfY2Q5YmE2ODc2OWFiNTgyZjUxMjc1MzRhNmQxMzA0ZmJmY2RlMGU4ZjBiNDExZGRmNjc3YjQ0OGQ5N2RiOTVmMA%3D%3D
  
DASH
  <AdaptationSet mimeType="text/vtt" lang="en">
  <Representation bandwidth="256" id="92cb36a7-c836-4506-a87f-f649316c0cdf">
  	<BaseURL>http://bcboltbde696aa-a.akamaihd.net/media/v1/dash/live/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a/92cb36a7-c836-4506-a87f-f649316c0cdf.vtt?akamai_token=exp=1518032494~acl=/media/v1/dash/live/clear/1752604059001/3585c49a-5a95-4783-8625-e3af727d094a*~hmac=3e2edc412c273f1255f2c18bbbcee7afc6a2edb74573f9295b0f05feda69f0e2</BaseURL>
  </Representation>
  </AdaptationSet>