support Contact Support | system status System Status
Page Contents

    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:

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

          {
            "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
          }
          
          

    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 "http://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": "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.

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

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


    Page last updated on 12 Jun 2020