Media Sharing

Introduction

Media sharing is a feature of Video Cloud that lets publishers share videos with other publishers, enabling you to more easily manage videos across multiple accounts. For example, publishers can keep a Master account of video content and then share videos out to other divisions or subsidiaries of the organization.

Note that all media sharing operation can be performed in Studio as well. See Managing Media Sharing Settings.

Shared media & billing

For information on how billing works for shared media, please see Media Sharing using the Media Module.

Terminology

In media sharing, there is a relationship between a Master account (that shares videos) and one or more Affiliate accounts (that receive shared videos) involved:

Media Sharing Terminology
Account	Description
Master	The account that created the original video. The Master owns the content and is responsible for setting up, managing and providing content to Affiliates.
Affiliate	The account that is receiving the video. The Affiliate can accept content shared to it from a Master.
Channel	A pipeline through which content is shared from a Master to any number of Affiliates. When media sharing is enabled a `default` channel will be created in your account.
Relationship	Describes the interaction between a Master and an Affiliate. A relationship is comprised of a Master to share content, a Channel through which content is shared, a Contract for accepting content, and an Affiliate to receive content.
Contract	Describes sharing relationship between a Master and an Affiliate. A contract is created by the Master, and then must be accepted for sharing to be enabled. The Affiliate can also specify whether shared videos are accepted automatically or must be approved one by one.

Base URL

As for all CMS API requests, the base URL for the operations discussed below is:

      https://cms.api.brightcove.com/v1

All endpoints discussed below will be appended to the base URL when you make requests.

Authentication

Authentication for requests requires an Authorization header:

          Authorization: Bearer {access_token}

The access_token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Note that all operations around relationships required new permissions:

      video-cloud/video/all
      video-cloud/sharing-relationships/read
      video-cloud/sharing-relationships/create
      video-cloud/sharing-relationships/update
      video-cloud/sharing-relationships/delete

Alternatively, you can just use:

      video-cloud/sharing-relationships/all

In the Studio API Authentication Admin page, two permissions are shown:

Sharing Read (equivalent to video-cloud/sharing-relationships/read)
Sharing Read/Write (equivalent to video-cloud/sharing-relationships/all)

Restrictions on sharing

By default, all videos can be shared. You can, however, prevent sharing if:

The affiliate account does not a have a custom field for which a value is set on the video in the master account
The master account has geo-filtering enabled, but the affiliate account does not

Custom field matching

You can enforce custom field matching for a channel, which means that video shares will fail if the video has values for custom fields that are not present in the affiliate account. Videos will still share successfully if the video does not have values for any non-matching custom fields

By default, custom field matching is not enforced.

If a video share fails because of non-matching custom fields, you will see an error like this in the response:

      {
        "video_id": "5691312273001",
        "affiliate_id": "47509719001",
        "affiliate_video_id": null,
        "status": "PROCESSING",
        "error_message": [{"error_code":"MISSING_CUSTOM_FIELDS","error_message":"Affiliate account is missing custom fields: [subject]"}],
        "shared_at": "2018-01-03T16:29:19.080Z",
        "updated_at": "2018-01-03T16:29:19.080Z"
      }

Geo-filtering matching

If geo-filtering matching is enabled for a channel, videos cannot be shared if the master account has geo-filtering enabled and the affiliate account does not.

By default, geo-filtering matching is enforced.

The error will look like this:

      {
        "video_id": "5691312273001",
        "affiliate_id": "47509719001",
        "affiliate_video_id": null,
        "status": "PROCESSING",
        "error_message": [{"error_code":"CONFLICT","error_message":"Affiliate account is not configured for geo restriction."}],
        "shared_at": "2018-01-03T16:29:19.080Z",
        "updated_at": "2018-01-03T16:29:19.080Z"

See Update channel below to see how you update a channel to enforce custom field and/or geo-filtering matching.

What is shared?

This section explains what gets shared, and how subsequent changes to the video are handled.

When the video is shared

Most of the video metadata fields are copied from the Master to the Affiliate account when the video is shared. The notable exceptions are:

id - the video will have its own unique id in the Affiliate account
date fields such as created_at and updated_at

All the video assets (renditions, images, text_tracks, etc.) are used by the Affiliate accounts for playback.

After the video is shared

After the video has been shared, some changes to the video in the Master account are automatically inherited by the Affiliate accounts, and some are not.

Video assets

Except for images, Master changes to the video assets are always inherited by Affiliates. Affiliates cannot change assets such as renditions, manifests, text tracks, or the digital master.

Changes to images by the Master are inherited by the Affiliate unless the Affiliate has replaced the image(s). Once an Affiliate changes an image, that image will no longer be inherited from the Master.

Video metadata

Any video metadata (such as the name, description, and reference id) can be modified by the Affiliate, and changes made on the Master video are not inherited by the Affiliate.

Resharing videos

Note, however, that if the Master re-shares the video (this can only be done through the CMS API, not in Studio), all assets and metadata (aside from data/time fields) will be shared to Affiliates, overwriting any changes the Affiliates have made.

Overview of media sharing steps

Setting up a relationship

Below is a summary of the operations for setting up a relationship (click on the operation name for more details):

Master operations

List channels

Method/Endpoint

GET

/accounts/ master_account_id/channels

Description

Get a list of channels for the account

Get channel details

Method/Endpoint

GET

/accounts/ master_account_id/channels/ channel_name ^[2-1]

Description

Get details of a channe

Notes

^[2-1] Currently there is only one channel named default

Update channel

Method/Endpoint

POST

/accounts/ master_account_id/channels/ channel_name

Description

Update channels settings

List channel affiliates

Method/Endpoint

GET

/accounts/ master_account_id/channels/default/members

Description

Get the affiliates for a channel

Add affiliates

Method/Endpoint

PUT

/accounts/ master_account_id/channels/default/members

Description

Add affiliates to a channel/p>

Remove affiliate

Method/Endpoint

DELETE

/accounts/ master_account_id/channels/default/members/ affiliate_account_id

Description

Removes an affiliate from a channel

Affiliate operations

List available contracts

Method/Endpoint

GET

/accounts/ affiliate_account_id/contracts

Description

Removes an affiliate from a channel

Get contract for a specific account

Method/Endpoint

GET

/accounts/ affiliate_account_id/contracts/ master_account_id

Description

Gets a contract, if any, from a specific account

Approve a contract

Method/Endpoint

PATCH

PATCH /accounts/ affiliate_account_id/contracts/ master_account_id

Description

Accept and configure acceptance conditions of contract

Sharing videos

Video sharing operations are performed by the Master account. The Affiliate account can accept the share (if auto_accept is set to false) and can update shared video metadata and images using the standard Update Video operation.

Here are the sharing operations that can be performed once a relationship is set up (click on an operation name for more details):

List existing shares

Method/Endpoint

GET

/accounts/ master_account_id/videos/ video_id/shares

Description

Get a list of existing shares for a video - this is important because of the consequences of re-sharing a video when it has already be shared.

Share a video

Method/Endpoint

POST

/accounts/ master_account_id/videos/ video_id/shares

Description

Share a video to one or more affiliates - note that if the video has already been shared, this operation will re-share it - that is probably not what you want to do.

Share a video

Method/Endpoint

POST

/accounts/ master_account_id/videos/ video_id/shares

Description

Share a video to one or more affiliates - note that if the video has already been shared, this operation will re-share it - that is probably not what you want to do.

Un-share a video for an Affiliate

Method/Endpoint

DELETE

/accounts/ master_account_id/videos/ video_id/shares

Description

Un-shares a video for a specific Affiliates - note that un-sharing and re-sharing will result in the shared video having a new video id in the Affiliate account.

Affiliate operations

Accept a shared video

Method/Endpoint

PATCH

/accounts/ affiliate_account_id/videos/ video_id

Description

Accept a shared video (if auto_accept is turned off).

Note: to identify shared videos waiting to be accepted, search for videos that have state:pending:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos?q=state:pending

or

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos?query=state:PENDING

CMS API requests - setup

This section lists the CMS API operations involved in setting up media sharing.

Master operations

List channel(s)

Method

GET

Endpoint

Request body

none

Sample response

List Channels
`/accounts/ master_account_id/channels`
`[ { "account_id": "57838016001", "name": "default", "enforce_custom_fields": false, "enforce_geo": false, "account_name": "BrightcoveLearning", "created_at": "2017-08-23T17:11:18.474Z", "updated_at": "2017-08-23T17:11:18.474Z" } ]`

/accounts/ master_account_id/channels

      [
        {
          "account_id": "57838016001",
          "name": "default",
          "enforce_custom_fields": false,
          "enforce_geo": false,
          "account_name": "BrightcoveLearning",
          "created_at": "2017-08-23T17:11:18.474Z",
          "updated_at": "2017-08-23T17:11:18.474Z"
        }
      ]

Get channel details

Method

GET

Endpoint

https://cms.api.brightcove.com/v1/accounts/ master_account_id/channels/ channel_name ^[5-1]

Request body

None

Sample response

{
  "account_id": "57838016001",
  "name": "default",
  "enforce_custom_fields": false,
  "enforce_geo": false,
  "account_name": "BrightcoveLearning",
  "created_at": "2017-08-23T17:11:18.474Z",
  "updated_at": "2017-08-23T17:11:18.474Z"
}

Notes

^[5-1] Currently there is only one channel named default

Update channel

Method

PATCH

Endpoint

/accounts/ master_account_id/channels/ channel_name ^[6-1]

Request body

{
  "enforce_custom_fields" : true,
  "enforce_geo" : true
}

Sample response

{
  "account_id": "57838016001",
  "name": "default",
  "enforce_custom_fields": true,
  "enforce_geo": true,
  "account_name": "BrightcoveLearning",
  "created_at": "2017-08-23T17:11:18.474Z",
  "updated_at": "2017-12-30T15:06:27.015Z"
}

Notes

^[6-1] Currently there is only one channel named default

List affiliates for channel

Method

GET

Endpoint

/accounts/ master_account_id/channels/default/members

Request body

none

Sample response

[
  {
    "account_id": "20318290001",
    "approved": false,
    "account_name": "Brightcove Training"
  },
  {
    "account_id": "1485884786001",
    "approved": true,
    "account_name": "Brightcove Learning Doc Samples"
  },
  {
    "account_id": "1752604059001",
    "approved": true,
    "account_name": "BC Training Videos"
  }
]

Note: the value of the approved field indicates whether or not the Affiliate has approved the contract.

Add affiliate to channel

Method

PUT

Endpoint

/accounts/ master_account_id/channels/default/members/ affiliate_account_id

Request body

{
  "account_id":"affiliate_account_id"
}

Sample response

{
  "account_id": "1485884786001"
}

Remove affiliate from channel

Method

DELETE

Endpoint

/accounts/ master_account_id/channels/default/members/ affiliate_account_id

Request body

none

Sample response

204 NO CONTENT (empty response body)

Affiliate operations

List available contracts

Method

GET

Endpoint

/accounts/ affiliate_account_id/contracts

Request body

none

Sample response

[
  {
    "account_id": "1485884786001",
    "channel": {
      "account_id": "57838016001",
      "name": "default"
    },
    "approved": false,
    "auto_accept": false,
    "approved_at": null,
    "updated_at": "2017-08-23T17:45:41.556Z",
    "created_at": "2017-08-23T17:45:41.556Z"
  }
]

The two essential fields in the response are:

approved - when set to true, the contract is accepted by the Affiliate
auto-accept - when set to true, videos shared through this contract will be automatically accepted by the Affiliate; otherwise, they must be approved one by one

We will see how to update the contract below.

Get contract for a specific account

Method

GET

Endpoint

/accounts/ affiliate_account_id/contracts/ master_account_id

Request body

none

Sample response

{
  "account_id": "1485884786001",
  "channel": {
    "account_id": "57838016001",
    "name": "default"
  },
  "approved": false,
  "auto_accept": false,
  "approved_at": null,
  "created_at": "2017-08-23T17:45:41.556Z",
  "updated_at": "2017-08-23T17:45:41.556Z"
}

Approve contract

Method

PATCH

Endpoint

/accounts/ affiliate_account_id/contracts/ master_account_id

Request body

{
  "approved": true,
  "auto_accept": true
}

Sample response

{
  "account_id": "1485884786001",
  "channel": {
    "account_id": "57838016001",
    "name": "default"
  },
    "approved": true,
  "auto_accept": true,
  "approved_at": "2017-08-27T12:27:21.582Z",
  "created_at": "2017-08-23T17:45:41.556Z",
  "updated_at": "2017-08-27T12:27:21.582Z"
}

If you include only "approved":true, each video will have to be approved individually.

CMS API requests - sharing

This section details the CMS API requests used in sharing videos. Media sharing operations are performed by the Master account. The Affiliate account can accept shares if auto_accept is turned off.

Master operations

List existing shares

To find out if a video has already been shared to other accounts, you can use the request below.

Method

GET

Endpoint

/accounts/ master_account_id/videos/ video_id/shares

Request body

none

Sample response

[
  {
    "video_id": "5553744346001",
    "affiliate_id": "1752604059001",
    "affiliate_video_id": "5553754248001",
    "status": "COMPLETE",
    "shared_at": "2017-08-27T14:35:01.890Z",
    "updated_at": "2017-08-27T14:35:25.630Z"
  },
  {
    "video_id": "5553744346001",
    "affiliate_id": "1485884786001",
    "affiliate_video_id": "5553758415001",
    "status": "COMPLETE",
    "shared_at": "2017-08-27T14:34:34.919Z",
    "updated_at": "2017-08-27T14:35:25.212Z"
  }
]

Sharing (or resharing) a video

The request described below will share a video to one or more Affiliate accounts.

Method

POST

Endpoint

/accounts/ master_account_id/videos/ video_id/shares

Request body

[
  { "id": "affiliate_account_id_1" },
  { "id": "affiliate_account_id_2" }
]

Sample response

Success response

[
{
  "video_id": "5553744346001",
  "affiliate_id": "1485884786001",
  "affiliate_video_id": null,
  "status": "PROCESSING",
  "shared_at": "2017-08-27T14:25:55.710Z",
  "updated_at": "2017-08-27T14:25:55.710Z"
}
]

Failure response

{
  "video_id": "5553744346001",
  "affiliate_id": "1485884786001",
  "affiliate_video_id": null,
  "status": "ERROR",
  "error_message": "[{\"error_code\":\"MISSING_CUSTOM_FIELDS\",\"error_message\":\"Affiliate account is missing custom fields: [myfieldname]\"}]",
  "shared_at": "2017-10-23T15:21:38.541Z",
  "updated_at": "2017-10-23T15:22:58.519Z"
}

Sharing will create a new video in the Affiliate's account. The state of the video share will be PROCESSING until the share is complete and the video is created in the Affiliate account. The Affiliate may still need to accept the video (if auto_accept is set to false on the contract by the Affiliate - see the previous section on setting up sharing).

A GET shares request by the Master account will not return the Affiliate video id until the share status is COMPLETE.

Unsharing a video for an Affiliate

Method

DELETE

Endpoint

/accounts/ master_account_id/videos/ video_id/shares/ affiliate_account_id

Request body

none

Sample response

202 ACCEPTED (empty response body) - the response indicates that the request has been accepted for processing, but the operation may not be completed for a couple of minutes

Affiliate operations

Accept shared video

To accept a shared video, the Affiliate updates the shared video, setting its state to ACTIVE. (Setting the state to INACTIVE rejects the share.)

Method

PATCH

Endpoint

/accounts/ affiliate_account_id/videos/ affiliate_video_id

Request body


  {
    "state": "ACTIVE"
  }

Sample response

{
  "id": "5557656136001",
  "account_id": "1485884786001",
  "ad_keys": null,
  "clip_source_video_id": null,
  "complete": true,
  "created_at": "2017-08-30T13:35:51.796Z",
  "cue_points": [
  ],
  "custom_fields": {
  },
  "delivery_type": "dynamic_origin",
  "description": null,
  "digital_master_id": "4728546275001",
  "duration": 11111,
  "economics": "AD_SUPPORTED",
  "folder_id": null,
  "geo": null,
  "has_digital_master": true,
  "images": {
    "thumbnail": {
      "asset_id": "5473683978001",
      "remote": false,
      "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
      "sources": [
        {
          "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
          "height": 90,
          "width": 160
        },
        {
          "src": "https://brightcove.hs.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
          "height": 90,
          "width": 160
        }
      ]
    },
    "poster": {
      "asset_id": "5473684427001",
      "remote": false,
      "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
      "sources": [
        {
          "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
          "height": 720,
          "width": 1280
        },
        {
          "src": "https://brightcove.hs.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
          "height": 720,
          "width": 1280
        }
      ]
    }
  },
  "link": null,
  "long_description": null,
  "name": "oystercatcher.mp4",
  "original_filename": "57838016001_4728546275001_4728519374001.mp4",
  "projection": null,
  "published_at": "2017-08-30T13:41:13.974Z",
  "reference_id": "2016-01-29T21:41:33.225Z-screencast-1280",
  "schedule": null,
  "sharing": {
    "by_external_acct": true,
    "by_id": "57838016001",
    "source_id": "4728519374001",
    "to_external_acct": false,
    "by_reference": true
  },
  "state": "ACTIVE",
  "tags": [
    "newtag",
    "foo"
  ],
  "text_tracks": [
  ],
  "updated_at": "2017-08-30T13:41:14.075Z"
}

Set the state to INACTIVE to reject the share.

Note that there is no special notification indicating that a video has been shared to your account. However, if you search videos for state:pending, that will find any unaccepted shares. Alternatively, you can use the Shares Pending list in the Studio Media module to see and accept/reject pending shares:

Errors

Media sharing errors are not returned as a separate error response to the API request, but rather in an error_message field in the normal response:

      [
        {
          "video_id" : "1239817239128",
          "affiliate_id" : "32871239",
          "affiliate_video_id" : "30308254055202",
          "status" : "COMPLETE",
          "shared_at" : "2017-12-11T17:57:45.530Z",
          "updated_at" : "2017-12-11T18:03:32.789Z",
          "error_message" : "[{"error_code":"MISSING_CUSTOM_FIELDS","error_message":"Affiliate account is missing custom fields: [whisky]"}]"
        }
      ]

See the CMS API Error Reference for more details.

Limitations

Currently, media sharing has the following limitations:

DRM: media sharing via the CMS API is currently not supported for DRM-enabled accounts. Sharing videos from an account that is not DRM-enabled to an account that is DRM-enabled is supported, but the shared videos will not be packaged for DRM.
If the channel defined by the master account has set enforce_custom_fields to true, and then shares a video that has a custom field with a value that is not allowed by the affiliate account, that share attempt will fail. The share status will be updated with an error message something like this:
```
      [{"error_code": "ILLEGAL_CUSTOM_FIELD_VALUE", "error_message": "Illegal value for custom fields: [topic]"}]
      
```
If the channel defined by the master account has set enforce_custom_fields to false, and then shares a video that has a custom field with a value that is not allowed by the affiliate account, then the share attempt will work, but the field with the bad value will not be included on the affiliate copy of the video.
When playing a shared video with SSAI, SSAI Macro replacement will use the metadata from the parent video instead of the child Video. SSAI will also skip the ad lookup if the parent video is marked as Advertising='Free', even if the child video is labeled as Ad Supported.