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

Untitled Created with Sketch. Create Video Add Renditions Add Manifests for Segmented Stream Add Poster and Thumbnail Update Video to Add Text Tracks
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 rendition:

      {
        "video_duration": 31487,
        "name": "RA - Great Blue Heron",
        "remote_url": "//some.site.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
        }
      
    

Notes

  1. Use this endpoint only for adding full length video renditions (typically an .mp4 or .mov file) - for adding segmented streams like HLS or DASH, use the manifest endpoints described in the next section.
  2. Video Cloud does not inspect the remote video files, so providing additional metadata will enable Video Cloud to display this information in Studio (or in the Brightcove player, if you configure the player to display the metadata).

    For details of the add rendition operation, see the API Reference.

  3. Renditions for remote assets must have the video_codec and video_container fields to work properly.
  4. MP4 renditions must have the "progressive_download": true field set to work properly in the Brightcove player
  5. Mixed assets are not allowed - you cannot add a remote rendition to an ingested video
  6. If your CDN or other remote repository supports both HTTP and HTTPS delivery, then specify the URL for remote assets with a protocol-neutral URL as shown in the example above (i.e. use "//my.domain/path/..." instead of "https://my.domain/path/...")

Add manifests

Note that to add remote segmented types such as DASH and HLS renditions, you only need to create the video and then add the manifests - you do not need to "add renditions" as explained in the previous section.

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_manifests
      
    

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

      {
        "remote_url": "https://some.site.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": "https://some.site.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.

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": "https://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_type}/{asset_id}
      
    

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

Limitations

  • SSAI is not supported for remote assets.
  • DRM is supported only if you can customize the player to communicate with the DRM license server. This is possible with the Brightcove Player through a plugin. For other players, you will need to consult the player documentation.
  • Analytics: the Brightcove Analytics system depends on system-generated video metadata, such as the video duration. Analytics data for remote assets will be less rich unless you can provide this metadata for the remote asset.
  • Video Cloud Studio: the preview player section in Studio cannot display remote text track files. Therefore, the CC button will not be visible.
  • Playback guarantee: all videos ingested into Video Cloud can be played back in the Brightcove Player. This is true for almost all remote assets, but there are some edge cases where videos may not play. There are a few advanced features of DASH and HLS that we do not yet support for example. For non-Brightcove players, you will need to verify that the video format is fully supported by that player.