Media Sharing with the Media API

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
• Getting Started with the Media API

Media sharing is available only for Video Cloud Enterprise customers 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: