Using the CMS API: Remote Assets

In this topic, you will learn how to add remote assets, including videos, renditions, manifests, images, and WebVTT text tracks, to Video Cloud using Brightcove's CMS API. This topic explains how to set up the video and then add, update, and remove remote assets.

Overview

Remote assets are mainly added through the Assets Operations, with a couple of exceptions noted below. Note that the GET operations for assets can be used for both ingested and remote assets.

Authorization

Workflow

Here are steps for setting up a remote asset:

Remote Assets Workflow
Remote Assets Workflow

In the following sections, we'll look at each of these steps.

Create the video

Before you can add remote assets, you must create a video object in your Video Cloud media library, using POST request to:

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

In the request body, include a JSON object that minimally contains the video name, but may contain additional metadata:

{
    "name": "My Remote Video",
    "description": "A short description of the video",
    "tags": ["remote", "fall_campaign"],
    "reference_id": "myUniqueReferenceID"
}

For details of the create video operation, see the API Reference.

Add Renditions

Next, add one or more full-length remote video renditions by making a POST request to:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/renditions

The JSON in the request body must contain minimally the remote url, but may contain other metadata for the rendion:

{
    "video_duration": 31487,
    "name": "RA - Great Blue Heron",
    "remote_url": "//learning-services-media.brightcove.com/videos/mp4/greatblueheron.mp4",
    "encoding_rate": 983000,
    "frame_height": 360,
    "size": 3887659,
    "frame_width": 640,
    "video_codec": "h264",
    "video_container": "MP4",
    "progressive_download": true
}

Add manifests

In addition to adding full length renditions, you can also add manifests for segmented renditions such as HLS, HDS, and ISM, by making a POST request to the endpoint for the manifest type:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/hls_manifest
https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/hds_manifest
https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/ism_manifest
https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/ismc_manifest
https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/dash_manifest

In the request body JSON, provide the remote url and a name (optional):

{
    "remote_url": "http://learning-services-media.brightcove.com/avideo/hls/chickadee/chickadee.m3u8",
    "name": "chickadee_hls"
}

For details of using the add manifest operations, consult the relevant section of the API Reference:

Add poster/thumbnail

You can add a remote poster and thumbnail to your video by making POST requests to these endpoints:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/poster
https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/thumbnail

In the request body JSON, you must include the remote url for the image, and you can add a name if you like:

{
    "remote_url": "http://learning-services-media.brightcove.com/images/great-blue-heron-poster.png"
}

For details of the operations, see the API Reference:

Add text tracks

Text tracks can be used to add captions, chapters, and other time-based metadata to your video.

Unlike renditions and images, text tracks are treated the same for remote asset videos as for videos ingested into the Video Cloud system. To actually add the text tracks to a video, you must use the Media module in Studio or the CMS API Update Video operation.

Add captions

Add DFXP captions to your video by making a POST request to:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/caption

In the request body JSON, include the remote URL for the DFXP file and a name (optional):

{
    "remote_url": "http://learning-services-media.brightcove.com/captions/Video-Cloud-Analytics-Performance-Report.DFXP.xml",
    "name": "EN DFXP Captions"
}

Replace remote with ingested

You can replace a remote asset video with an ingested one by making a request to the Dynamic Ingest API:

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

The simplest request body would look like this:

{
  "master": {
      "url": "http://host/master.mp4"
  }
}

See the Dynamic Ingest API Reference for additional options and information.

One of the common uses of remote asset videos is to create a placeholder video for use in a live streaming event. Once the event is complete, you may wish to replace the "live" video with a video-on-demand recording of the event that appears in the same player you used for the live stream. You can do this by using the method described above, though it can also be used to turn any remote asset video into one that is ingested into Video Cloud.

Modify assets

In addition to adding remote assets for a video, there are also operations for retrieving, updating, and deleting the asset information. These operations use the endpoints described above, but with GET, PATCH, or DELETE requests. For update and delete requests, you must add the asset id (which is included in the response to POST and GET requests) to request URL:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/assets/{asset_id}

See the API Reference for details of the get, update, and delete operations.

Related topics