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:
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
- 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.
-
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.
- Renditions for remote assets must have the
video_codecandvideo_containerfields to work properly. - MP4 renditions must have the
"progressive_download": truefield set to work properly in the Brightcove player - Mixed assets are not allowed - you cannot add a remote rendition to an ingested video
- 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.