On This Page

Overview: 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.

If you only want information about the video currently in the player, you can use the mediainfo object instead of making a Playback API call.

The mediainfo object contains information about the video currently loaded in the player, whereas the Playback API can retrieve info about any video. For details, see the Video Metadata from mediainfo document.

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

The Playback API does not currently support requests coming from IP addresses that uses the IPv6 protocol.

Base URL

The base URL for the Playback API is:

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

Note: you must use https as the protocol.

Note: customers using IP Restriction must use https://edge-elb.api.brightcove.com/playback/v1 instead of the standard URL; for more details on players used outside of North America with IP restrictions, be sure to check out the information in the Player Configuration Guide to prevent issues that may arise.

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:

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.

In an Authorization header using the realm keyword BCOV-Policy:

Authorization: BCOV-Policy {policy_key}

In a BCOV-Policy header:

BCOV-Policy: {policy_key}

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.

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:

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

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:

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:

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

With each response, you will see that the count field always shows the maximum number of videos in your result set.

{"count": 171,
"videos": [ ... ]
}

Remember that the Playback API search is capped at 1000 videos.

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]

Prefix the field name with a minus sign (sort=-field_name) for descending order.

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)

[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:

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

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 sort_by parameter explicitly will give you more control over the order of the returned items.

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:

name

short description

long description

tags

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

The response results for this endpoint are subject to change as we improve the algorithm for finding related videos. If you do not want your results to change, or if you want precise control over finding related videos, then you should use the search videos functionality.

Parameters

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

Example

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.

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:

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.

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.