Media Sharing with the Media API

ProductVersionEdition
Video CloudLegacy StudioProfessional, Enterprise

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. This topic describes how to share videos using the Media API. For introductory information, read:

Media sharing is available only for Video Cloud Enterprise and Pro customers with multiple accounts. If you are interested in upgrading your Video Cloud account, please contact Brightcove for more information.

The share_video method

The Video Cloud Media API includes a share_video method you can use to share a video with an affiliate. The share_video method has this signature:

share_video(token:String, video_id:Long, sharee_account_ids:Long[],
            auto_accept:Boolean, force_reshare:Boolean):Long

To use the share_video method, pass:

  • your Media API write token
  • the ID of the video you want to share
  • a comma-separated array of the Video Cloud account IDs of the affiliates you want to share the video with
  • optionally, if your affiliate has configured its account to automatically accept shared videos, set auto_accept=true
  • optionally, if you want the shared video to overwrite any existing version of the video in the affiliate's account, set force_reshare=true

For example, to share a video with the ID 123 with two affiliates whose Video Cloud account IDs were 456 and 789, you could post something like this to http://api.brightcove.com/services/post:

{"method": "share_video",
    "params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
               "video_id" : 123,
               "sharee_account_ids":[456,789]}}

Click here to see a sample page that uses JavaScript, an HTML form, and the share_video method to share videos.

Click here to see the source code for this example.

Modifying shared videos

If you modify a video in your account after you share it, any changes you make are not automatically propagated to any accounts to which you may have shared the video. To share those subsequent changes with your affiliates, you need to share the video again using the share_video method. By default, when you share a video to an affiliate's account, and the affiliate's account already has that video because you shared it with them previously, the share_video method fails. If you have updated a shared video in your own account (for example, you may have added higher quality renditions or modified the metadata) and you want to enforce those updates in the shared copies of the video in your affliate's account, use the optional force_reshare=true argument.

When you use the force_reshare=true argument, only the affiliates whose account IDs you include in the sharee_account_ids argument will have their shared video updated. The force_reshare argument has no special effect in cases where the video has not been shared yet to one ore more of the accounts included in the sharee_account_ids argument; the video will be shared normally in that case.

Unsharing videos

When you share a video with a Brightcove affiliate, Video Cloud adds a copy of your video to the affiliate's account. If you elect to stop sharing that video with an affiliate, you can use the unshare_video method. The unshare_video method deletes specified videos from accounts where it was previously shared. It has a video_id argument for specifying the video to unshare and a sharee_account_ids argument for listing the accounts from which to delete the specified video. If a shared video does not exist in a specified sharee account, no action is taken. See unshare_video in the Media API Reference.

Deleting shared videos

The delete_video method has an optional delete_shares argument. In order to delete a video that has been shared, you must call delete_video with delete_shares="true". In that case, the video will be deleted from your account, as well as from all accounts with which the video has been shared. The delete_shares argument is optional, but if you attempt to delete a video that has been shared without using this argument, the method will fail with an error.

share_video Error Messages

The share_video method can produce the following error messages:

Message Description
The video specified was not found Video Cloud did not find a video with the specified video ID in your account
Invalid video id: null You passed null as the video ID
Shared videos cannot be re-shared You tried to share a video that your account received by sharing. Only the original account that uploaded the video can share the video.
Invalid sharee account idx: ? value: null
(where ? is the index within the passed list of account IDs)
You passed null as one of the sharee account IDs
Sharing is not allowed to account: ?
(where ? is an account id)
A sharing relationship has not been established between your account and one of the accounts whose account ID you passed. Either the account ID is wrong, or sharing has not been set up between your account and the sharee account. Contact customer support to set up the sharing relationship.