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 close time to the URL expiration value of the account. How long a particular data set id cached will vary.
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 or JWT, which can be passed in one of four ways:
- In an argument to an
Acceptheader: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.
- In an
Authorizationheader using the realm keywordBCOV-Policy:Authorization: BCOV-Policy {policy_key} - In a
BCOV-Policyheader:BCOV-Policy: {policy_key} - Using a JSON Web Token (JWT) in a
Authorizationheader:Authorization: Bearer {JWT}
Obtaining a policy key
There are three ways you can obtain a policy key:
- 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.
- You can generate a basic policy key using the Policy Keys Quick Start
- 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 Customer Success 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
Brightcove does NOT recommend having any cache in front of the Playback API.
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": "https://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
},
"tags": [
"copied"
],
"poster_sources": [
{
"src":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999"
}
],
"thumbnail_sources": [
{
"src":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999"
}
],
"poster":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
"thumbnail":
"https://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":
"https://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": "https://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
},
"tags": [
"copied"
],
"poster_sources": [
{
"src":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999"
}
],
"thumbnail_sources": [
{
"src":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999"
}
],
"poster":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
"thumbnail":
"https://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":
"https://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.
| 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 1000. 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_weekFor details, see the Get Videos section of the Playback API reference |
config_id |
See Delivery rules |
ad_config_id |
See Video requests with SSAI |
Using search parameters
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 1000. 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:
- Use the
limitandoffsetparameters to return groups of data from your result set./accounts/578380111111/videos?q=tags:nature&limit=20&offset=50 - With each response, you will see that the
countfield always shows the maximum number of videos in your result set.{"count": 171, "videos": [ ... ] } - The total
countof videos from your first request can be used to determine how many more pages you will need to request.
Alternatively, you can interrogate thecountvalue with each response and continue until thecountis less than or equal to page size times thelimit.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
GETvideos call, the results will be sorted byupdated_atdescending. - [1-2] You can sort on
plays_totalorplays_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:
- You may be tempted to use the largest allowed
limit(1000), but it's better to retrieve videos in batches of 25 or less to minimize the possibility of API requests timing out - 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.
- 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
sortparameter 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."
}
]
Find related videos
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:
nameshort descriptionlong descriptiontags
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:
| Parameter | Description |
|---|---|
limit |
The number of videos to return (default=20; maximum=1000) |
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 1000 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."
}
]
Delivery rules
To apply delivery rules to the responses to Playback API requests, append the config_id={DELIVERY_RULES_ID} to the request.
Example
https://edge.api.brightcove.com/playback/v1/accounts/1752604059001/videos/6026822730001?config_id=9869b9f8-59a1-4490-a092-c28b6cf79764Video 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.
-
Append your
ad_config_idto the end of the Playback API request:Endpoint with URL parameter
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
sourcesarray will contain a new property calledvmap. - If you want to know where the ads are located in the content, you can read the VMAP file linked in the
vmapproperty.
Sample Playback API 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": "https://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": "https://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" } - Copy one of the
vmapURLs and paste it in a browser searchbar to see the VMAP response. -
The VMAP response contains a
<bc:Brightcovetag with acontenturiattribute. This is the URL that you should use to load your player.Sample VMAP response
Here is an example of a vmap response:
<vmap:VMAP xmlns:bc="bc" xmlns:vmap="https://www.iab.net/vmap-1.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" version="1.0"> <vmap:Extensions> <bc:Brightcove ttl="3600" contenturi="https://ssaimanifest.prod.boltdns.net/us-east-1/playback/once/v1/hls/v4/clear/1752604059001/d6190656-2095-4ff3-8afe-1a0b60d67ed2/dca41ae8-d8f5-48a6-9853-564764d60b84/6830b2e4-3298-439d-beef-e04abef9f23c/content.m3u8?bc_token=NWZkMTE5NTlfZWQxNDAzNDRkNTAxNDRlMWEwODU3MTI1MzY2YjAyZWQ5YzlmZTkzY2UwMjM5NTM1MmI2NGRjZDNhNjE2ZDhlOA%3D%3D" contentlength="24.0574" payloadlength="50.1835" contenttype="application/x-mpegURL" /> <bc:thumbnailURL type="thumbnail" width="480" height="270" bandwidth="0">https://ssai.playback.us-east-1.prod.deploys.brightcove.com/v1/thumbnail/1752604059001/dca41ae8-d8f5-48a6-9853-564764d60b84/low-res/6830b2e4-3298-439d-beef-e04abef9f23c/thumbnail.vtt?bc_token=NWZkMTE5NTlfMmVmODIzZDJjMGZkMDBjZjY1YWIxNDQ4Y2YyZmUxYTExNzg5YmIxZDI5ZTdkMjgyODBmMDBmYTViMTE2Yzc0MQ%3D%3D</bc:thumbnailURL> </vmap:Extensions> <vmap:AdBreak breakType="linear" breakId="PreRoll_0_0" timeOffset="start"> <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="0"> <vmap:VASTData> <VAST xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"> <Ad id="1"> <InLine> <AdSystem>Test Ad Server</AdSystem> <AdTitle>Portals</AdTitle> <Description>Demo ad number 6</Description> <Error></Error> <Creatives> <Creative> <Linear> <CreativeExtensions> <CreativeExtension> <BrightcoveForeignKey>1</BrightcoveForeignKey> </CreativeExtension> </CreativeExtensions> <Duration>00:00:05.9392</Duration> <AdParameters> <xml></xml> </AdParameters> <VideoClicks/> </Linear> </Creative> </Creatives> <Extensions> <Extension> <xml>data</xml> </Extension> </Extensions> </InLine> </Ad> </VAST> </vmap:VASTData> </vmap:AdSource> </vmap:AdBreak> <vmap:AdBreak breakType="linear" breakId="MidRoll_5_0" timeOffset="00:00:04.8381"> <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="1"> <vmap:VASTData> <VAST xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"> <Ad id="2"> <InLine> <AdSystem>Test Ad Server</AdSystem> <AdTitle>Marketing</AdTitle> <Description>Demo ad number 4</Description> <Error></Error> <Creatives> <Creative> <Linear skipoffset="00:00:05"> <CreativeExtensions> <CreativeExtension> <BrightcoveForeignKey>2</BrightcoveForeignKey> </CreativeExtension> </CreativeExtensions> <Duration>00:00:12.1788</Duration> <AdParameters> <xml></xml> </AdParameters> <VideoClicks/> </Linear> </Creative> </Creatives> <Extensions> <Extension> <xml>data</xml> </Extension> </Extensions> </InLine> </Ad> </VAST> </vmap:VASTData> </vmap:AdSource> </vmap:AdBreak> <vmap:AdBreak breakType="linear" breakId="PostRoll_24_0" timeOffset="end"> <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="2"> <vmap:VASTData> <VAST xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"> <Ad id="3"> <InLine> <AdSystem>Test Ad Server</AdSystem> <AdTitle>Brand</AdTitle> <Description>Demo ad number 1</Description> <Error></Error> <Creatives> <Creative> <Linear> <CreativeExtensions> <CreativeExtension> <BrightcoveForeignKey>3</BrightcoveForeignKey> </CreativeExtension> </CreativeExtensions> <Duration>00:00:08.0080</Duration> <AdParameters> <xml></xml> </AdParameters> <VideoClicks/> </Linear> </Creative> </Creatives> <Extensions> <Extension> <xml>data</xml> </Extension> </Extensions> </InLine> </Ad> </VAST> </vmap:VASTData> </vmap:AdSource> </vmap:AdBreak> </vmap:VMAP>
For details, see the Implementing SSAI with Non-Brightcove Players and SDKs document.
Configure your player
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.
Playlists may contain up to 1000 videos, but by default, only the first 20 are returned. Using the parameters
described below, you can return up to 1000 videos at a time, or use a smaller limit
and use the offset parameter to retrieve the group of videos you want, or submit
multiple requests to return them all.
Parameters
The following URL parameters can be used for playlist requests
| Parameter | Description |
|---|---|
| limit | The number of videos to return (default=20; maximum=1000) |
| offset | number of videos to skip (from the start of the playlist; default=0) |
For example, these parameters appended to your request - ?limit=100&offset=200 - would return videos 201-300 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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999",
"poster":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
"link": {
"text": "Full Dvd at Amazon",
"url": "https://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
},
"id": "38467382999",
"ad_keys": null,
"thumbnail_sources": [
{
"src":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://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":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728862001_th-111727994001.jpg?pubId=107767373999&videoId=38467382999",
"poster":
"https://brightcove04.o.brightcove.com/107767373999/107767373999_111728861001_vs-111727994001.jpg?pubId=107767373999&videoId=38467382999",
"link": {
"text": "Full Dvd at Amazon",
"url": "https://www.amazon.com/Avatar-Sam-Worthington/dp/B002VPE1AW"
},
"id": "38467382999",
"ad_keys": null,
"thumbnail_sources": [
{
"src":
"https://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":
"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":
"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":
"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",
"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>https://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>