Integrating Your CMS with Video Cloud

User functions

Below are functions related to Video Cloud that you might want to provide users of your CMS:

Add new videos to Video Cloud
Replace a Video Cloud video with a new version
Update metadata for videos, such as the title, description, and tags
Delete videos
Create playlists
Change the videos in a playlist
Delete playlists
Create video players
Modify video player properties, such as dimensions or styling
Add special functionality to video players through plugins
Publish single videos or playlists
Provide analytics data on video loads, views, play-rates, engagement, etc.

You may not wish to expose all this functionality to your end users - you may not want to let them delete videos, for instance. One of the advantages of integrating Video Cloud with your CMS rather than letting users go directly to Video Cloud Studio is that you can choose exactly what functionality to expose to users through the Brightcove APIs.

Authentication

For all Brightcove API requests, authentication is based on OAuth2 access tokens. There is a two-step process for obtaining access tokens:

Create client credentials with permissions for the API operations you need
Use the client credentials to create a temporary access token to authenticate an API request

Creating client credentials

Creating client credentials is a one-time operation that can be performed through Video Cloud Studio or the OAuth API . However you do it, a client_id and client_secret are returned, which you must save to request access tokens.

The client_secret is shown only when the client credential is created - it can never be retrieved again. If you lose a client secret, you must create a new client credential.

Creating an access token

Temporary access tokens are created using the OAuth API . The client_id and client_secret must be BASE64-encoded and passed as a Basic Authorization string.

The access_token returned is in turned passed in an Authorization header with the API call:

    Authorization: Bearer your_access_token

Access tokens are valid for 5 minutes. Unless you are performing some kind of batch operation that will be making hundreds of successive API calls, it makes sense to just request a new one for each API call rather than trying to keep track of the timeout.

Adding Videos

If you wish to let users add videos to Video Cloud from your CMS, you can do that using the Dynamic Ingest API . We recommend that you have users upload videos to your repository, which could be an S3 bucket or just a public-facing server. The Dynamic Ingest system can pull in the videos and add them to the Video Cloud system through a two-step process outlined below.

Adding a video object to Video Cloud

The first step is to create a video object in the Video Cloud system by making a POST request to the CMS API:

    https://cms.api.brightcove.com/v1/accounts/:account_id/videos

The request body will include basic video properties in a JSON object - minimally, the video name, but you can also include additional metadata such as a description and tags:

    {
    "name": "Woodpecker",
    "description": "A bird that hunts insects inside wood",
    "reference_id": "Bird_Woodpecker.mp4",
    "tags": ["bird", "air", "nature"]
    }

A reference_id can be added to any video. Reference ids must be unique within the account. If your videos have ids in your CMS system, it's good practice to use that id as the reference id in the Video Cloud system.

Ingesting the video

When you create the video object, the CMS API will return a JSON object containing the video properties. You will extract the video id from the JSON, and use it to make a call to the Dynamic Ingest API to request ingestion and transcoding of the video:

    https://ingest.api.brightcove.com/v1/accounts/ACCOUNT_ID/videos/VIDEO_ID/ingest-requests

Again you will send JSON in the request body specifying the location of the video file:

    {
      "master":{
        "url":"https://support.brightcove.com/test-assets/videos/Great_Blue_Heron.mp4"
      },
      "profile":"multi-platform-extended-static",
      "capture-images": true
    }

The profile here is the Ingest Profile that specifies what renditions should be created in the transcoding process. In most cases, one of the following standard profiles should be adequate:

Dynamic Delivery profiles

multi-platform-extended-static
multi-platform-standard-static

Legacy ingest profiles

videocloud-default-v1 (the default)
screencast-1280
smart-player-transition
single-bitrate-high
audio-only
single-bitrate-standard
high-resolution

However, you can create additional custom ingest profiles, if needed, using the Ingest Profiles API or using Video Cloud Studio.

If you retrieve profiles using the Ingest Profiles API the results for legacy ingest accounts will include Dynamic Delivery profiles, but using these will result in errors. You will need to filter these profiles out on the client side. You can recognize Dynamic Delivery profiles by the existence of a dynamic_origin property:

    {
        "version": 2,
        "name": "multi-platform-extended-static",
        "display_name": "Multiplatform Extended",
        "description": "Deliver high quality content for a wide range content types and screen sizes including mobile, desktop and large screens.",
        "account_id": -1,
        "brightcove_standard": true,
        "date_created": 1495114240899,
        "date_last_modified": 1503002227627,
        "digital_master": {
          "rendition": "passthrough",
          "distribute": false
        },
        "renditions": [
        ],
        "packages": [
        ],
        "dynamic_origin": {
          "renditions": [
            "default/audio64",
            "default/audio128",
            "default/video3800",
            "default/video700",
            "default/video3500",
            "default/video2000",
            "default/video1700",
            "default/video1200",
            "default/audio96",
            "default/video450",
            "default/video900",
            "default/audio192"
          ],
          "images": [
            {
              "label": "thumbnail",
              "height": 90,
              "width": 160
            },
            {
              "label": "poster",
              "height": 720,
              "width": 1280
            }
          ]
        },
        "id": "f1b16093e2dc4f81810f1488"
      }

Adding poster and thumbnail images

The capture-images option in the code above instructs Video Cloud to capture poster and thumbnail images for the video at the mid-point during the transcoding process. Alternately, you can set capture-images to false and ingest images instead, either at the same time that you ingest the video or later:

    {
    "master":{
    "url":"https://support.brightcove.com/test-assets/videos/Great_Blue_Heron.mp4"
    },
    "profile":"multi-platform-extended-static",
    "capture-images": false,
    "poster": {
    "url": "https://some.site.com/images/for_video/titmouse-poster.png",
    "width": 640,
    "height": 360
    },
    "thumbnail": {
    "url": "https://some.site.com/images/for_video/titmouse-thumbnail.png",
    "width": 160,
    "height": 90
    }
    }

See Images and the Dynamic Ingest API for more details.

Adding text tracks for captions or chapters

You can also use the Dynamic Ingest API to add text tracks in WebVTT files to videos, either at the time of ingestion or later. Text tracks are used to add captions or chapters to a video.

    {
    "master":{
    "url":"https://some.site.com/videos/mp4/Bird_Woodpecker.mp4"
    },
    "profile":"multi-platform-extended-static",
    "capture-images": false,
    "poster": {
    "url": "https://some.site.com/images/for_video/titmouse-poster.png",
    "width": 640,
    "height": 360
    },
    "thumbnail": {
    "url": "https://some.site.com/images/for_video/titmouse-thumbnail.png",
    "width": 160,
    "height": 90
    },
    "text_tracks": [
    {
    "url": "https://some.site.com/captions/for_video/Water-in-Motion.vtt",
    "srclang": "en",
    "kind": "captions",
    "label": "English",
    "default": true
    }
    ]
    }

See Ingesting WebVTT Files for more details.

Managing Videos

The CMS API allows you to get back video data for an account. (As shown above, it is also used to create video objects as part of the video ingestion process.) The most basic request is as follows:

    https://cms.api.brightcove.com/v1/accounts/account_id/videos

By default, this request returns a JSON array of 20 video objects containing a wealth of metadata, including the name, description, tags, custom fields, the dates it was created and last modified, URLs for the poster and thumbnail, and much more.

You can refine the results of the request by adding one or more of the following parameters to the request:

limit: this determines the number of video objects to return, and can be set to any number up 100 - the default is 20
offset: this determines the number of items to skip, and so is used together with limit to page through the video catalog - the default is 0
sort: this determines the video metadata field to sort the result by - by default, results are sorted by updated_at (descending, to show the most recently updated videos first)

See CMS API Overview - Parameters for detailed information on these parameters.

Searching for videos

You can also search for videos by a wide range of criteria using the q parameter. You can search by specific fields such as name, description, and tags, as well as dates and the status of the videos:

    https://cms.api.brightcove.com/v1/accounts/account_id/videos?q=tags:sea,mammal

For details and all the options for searching, see Search for Videos.

Getting and updating a specific video

To retrieve a specific video by its id or reference id:

    https://cms.api.brightcove.com/v1/accounts/account_id/videos/id
    or
    https://cms.api.brightcove.com/v1/accounts/account_id/videos/ref:reference_id

A GET request returns the video object. To update it, modify the JSON and return it using a PATCH request to the same URL.

Playlists

Playlist information is also managed using the CMS API in much the same way as video information. Note that Video Cloud supports eight types of playlists in two categories:

Manual (or EXPLICIT) playlists

contain a specified set of videos - up to 100 videos may be included

Smart playlists

built dynamically at runtime based on search criteria - there are seven varieties of smart playlists corresponding to the way the videos are ordered within the list:

ACTIVATEDOLDESTTONEWEST
ACTIVATEDNEWESTTOOLDEST
ALPHABETICAL
PLAYSTOTAL
PLAYSTRAILINGWEEK
STARTDATEOLDESTTONEWEST
STARTDATENEWESTTO_OLDEST

The limit on the number of videos can be set to any number up to 100.

As with videos, you can retrieve all playlists, using limit and offset to page through results if the account has a large number of playlists:

    https://cms.api.brightcove.com/v1/accounts/account_id/playlists

The returned array of playlist objects will include metadata for the playlist, including the type corresponding to the one of the types described above. If the type is EXPLICIT, there will also be a video_ids array containing the ids of the included videos. If the type is one of the smart playlist types, there will be a search property containing the search string that retrieves the videos, something like this:

    q=tags:fish,birds

You can also retrieve a single playlist by its id:

    https://cms.api.brightcove.com/v1/accounts/account_id/playlists/playlist_id

If you need to retrieve the full video objects for a playlist (to display information about the videos on a page), you simply add /videos to that URL:

    https://cms.api.brightcove.com/v1/accounts/account_id/playlists/playlist_id/videos

Note that for a smart playlist, the request will return the videos that match the search criteria presently, but that may change.

Creating Players

Brightcove players can be created via the Player Management API . The API allows you to create players, update their properties, and get the embed code in the form of a URL, an iframe tag, or a block of HTML to embed in the page.

You can up to 200 players per account, but it is generally less confusing to users to have as few players as you absolutely need. You should have separate players for playing single videos or playlists, but otherwise you only need different players when they will be styled differently or have different functionality added through plugins.

To create a player, you simply make a POST request to the Player Management API:

    https://players.api.brightcove.com/v2/accounts/account_id/players

In the body of the request, include the player configuration - the only thing required is a name:

    {
    "name": "Single video player for blog posts"
    }

The response will give you the player id, as well as the embed code in multiple forms:

    {
    "embed_code": "<iframe src='//players.brightcove.net/57838016001/de055fa4-4f09-45af-8531-419c6794ad04_default/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>",
    "embed_in_page": "https://players.brightcove.net/57838016001/de055fa4-4f09-45af-8531-419c6794ad04_default/in_page.embed",
    "id": "de055fa4-4f09-45af-8531-419c6794ad04",
    "preview_embed_code": "<iframe src='//preview-players.brightcove.net/v1/accounts/57838016001/players/de055fa4-4f09-45af-8531-419c6794ad04/preview/embeds/default/master/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>",
    "preview_url": "https://preview-players.brightcove.net/v1/accounts/57838016001/players/de055fa4-4f09-45af-8531-419c6794ad04/preview/embeds/default/master/index.html",
    "url": "https://players.brightcove.net/57838016001/de055fa4-4f09-45af-8531-419c6794ad04_default/index.html"
    }

To get the full player configuration, you make a request to the /players endpoint, but add the player ID that is returned in the response above:

    https://players.api.brightcove.com/v2/accounts/account_id/players/de055fa4-4f09-45af-8531-419c6794ad04

You can make a PATCH request to same endpoint to update the player configuration.

You'll notice in the response above, the preview_embed_code and preview_url. To allow testing of new players or player updates, newly created or updated players are set in preview mode to allow you to see it before pushing changes out to existing players. To push changes into production, you need to publish the player with this request:

    https://players.api.brightcove.com/v2/accounts/account_id/players/de055fa4-4f09-45af-8531-419c6794ad04/publish

Customizing Players

The Brightcove player is built with standard web technologies: HTML, CSS, and JavaScript. You can customize the player using those same technologies. This can be done in the page where the player is published, but best practice is to add your customizations to the player itself through the player configuration, updating the player via a PATCH request to the Player Management API as explained in the previous section.

You can also add additional features and functionality to the player through JavaScript plugins, and there is an extensive Player API to help you integrate your code with the player. Brightcove offers a number of ready-made plugins for such things as enabling advertising, customizing the endscreen, and adding overlays.

Publishing Videos

In the Creating Players section above we saw that when you get the player configuration object using the Player Management API, the returned data includes an iframe tag for embedding the player in an HTML page, and also a URL for the full HTML if you want to embed the player directly in a page.

For whichever embed you choose, you will need to add a Video Cloud video id or playlist id to the embed code to add content to the player. The iframe embed code looks like this:

    <iframe
    src='//players.brightcove.net/57838016001/de055fa4-4f09-45af-8531-419c6794ad04_default/index.html'
    allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>

To the URL for the player, you need to append the parameter videoId={}video_id, so that the full embed code will look like this:

    <iframe
    src='//players.brightcove.net/57838016001/de055fa4-4f09-45af-8531-419c6794ad04_default/index.html?videoId=4483119716001'
    allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>

If this is a playlist player, you use the parameter playlistId={playlist_id} instead. The modification of the in-page embed code is similar.

Unless the player dimensions are fixed in the player configuration, you will also need to size the player by adding width and height in a style attribute:

    <iframe
    src='//players.brightcove.net/57838016001/de055fa4-4f09-45af-8531-419c6794ad04_default/index.html?videoId=4483119716001'
    allowfullscreen webkitallowfullscreen mozallowfullscreen
    style=width:640px;height:360px;></iframe>

Getting Analytics Reports

The Analytics API allows you to generate analytics reports by many different dimensions. See the Dimension Guides for more information.

You can specify the date range for the report, the metrics to return, and you can get the data in JSON, csv, or xlxs format

For periods within the last month, you can also generate detailed Engagement Reports that show views for every one hundredth part of the video.

Summary of APIs

Here is a summary of the APIs useful for integrating with Video Cloud.

OAuth API

Used to create client credentials and access tokens to access the other APIs.

Media Management

Ingest Profiles API: Used to create custom ingest profiles specifying the renditions to be created for videos added to Video Cloud
Dynamic Ingest API: Used to add videos and related media assets to Video Cloud
CMS API: Used to create video objects for ingestion, and to manage videos and playlists

Brightcove Players

The Brightcove Player: The player includes a JavaScript API to interact with the player at runtime
Player Management API: Used to create and configure players, and to get the player embed code

Analytics API

Used to obtain analytics reports on video performance