Using Brightcove in Sitecore

update on 9.13.2011 - Sukiyoshi's open source license has changed to the MIT open source license.

update on 3.8.2012 - Sukiyoshi has been updated to work on Sitecore 6.4 and up and has a specific release for it you can jump over to the Sukiyoshi open source repository for the specifics.

Over the past few years I've been fortunate enough to have had the opportunity to work with Brightcove and was given a development account for their platform that I could work against. In that time I went and took the existing .NET SDK Tanaris that had implemented the video read methods and blew out the rest of the read and write methods for the videos and playlists. I ended up learning a lot and had started my own branch of the code. I named it Sukiyoshi, after my wife. I did a lot of work on Sitecore sites at the same time and after having built More Interop with Douglas Couto, which used a lot of video, I realized that being able to outsource the video management aspect of a Sitecore website could have greatly simplified our task.

This brings us to the point of our story: Brightcove in Sitecore. There are of course a thousand ways to do this and I've probably tried half of them. My current job gives me a unique opportunity to match the potential of this project with an actual need I feel like what I've come up with is a pretty good solution. I will say there is a good deal of customization that you must be comfortable with, but it will allow you some good flexibility when it comes to multilingual, multisite installations.

The installation relies on two open source libraries and a sitecore package. I'll walk through what's in the package that you should be aware of and a bit of what you'll expect when you start working with it. Let's start with the files that get installed with the sitecore package. There's two bin files: BrightcoveSDK.dll and BrightcoveSDK.SitecoreUtil.dll. They contain the bulk of the labor. The first is just the library you need to connect to Brightcove in a .NET site without Sitecore. The other will add a lot of functionality specific to Sitecore.

Next are a handful of files that live deep in the Sitecore folder. The path is provided in the image. To add buttons and dialog windows to the Rich Text Editor there is a RichText Commands-Brightcove.js file whose content must be copied into the RichText Commands.js file. Then there is an InsertVideo folder which contains the SheerUI XmlControls and some javascript that allow you to select the player/video/playlists.

There's some files in the sitecore modules folder that are the what is loaded into the custom editor tabs.

There is also a handful of changes that you must add to your web.config file so in the root website folder is a Brightcove.config file with those specific changes including the very important Brightcove account information, a handler definition, pipeline events etc.

Inside Sitecore itself there are also a good number of items that you should know about. First in the core are the content editor tabs. These are pretty essential to giving the end user a good UI to work with when they want to view a preview a video in a player or edit an item or even add images to a video. I'll go more into what those look like further into the article.

There are also two items that provide the buttons in the wysiwyg that trigger the Sheer UI XmlControl dialog windows to open. You should notice that this is only set by default to the "Full" profile and you will need to duplicate the buttons and place them in other profiles should you need to.

There are also a few templates that support the Video Library structure. Most of the fields on these items are also shared so that it's not languages specific and will be the same no matter what language you happen to be using.

The system also supports multiple accounts so when you create each account there is a branch template that prepopulates it with the subfolders you'll need to get started.

One of the features that is supported is the ability to link text to a popup of a video. To do this you'll be relying on a myriad of javascript libraries. To allow developers the flexibility to use the package of their choice, you can define a profile for each type of js library. There is a default, which is populated with prettyPhoto because that's what I use, but you can create others and define which domain name each should be used for. This is so that in the event that you want one of the ten sites your running to work with the newest prettiest thing, you will be able to do just that. There are two types of settings: attributes and querystring params. It allows you enough leverage to create customized profiles.

The only thing left that is provided on installation is the Brightcove Media library section. This is installed under the content node not under the media library node because it's not actual media, it's just content. It's semantic really and if you don't like the idea of it, feel free to download the source and change it to suit your needs. After installation one of the first things you'll need to do is create an account. Just right-click on the Brightcove Media node and insert and account folder.

I created one named "Mark" since this will be pointing to my developer account.

Once created you'll need to go to the content tab and add in your publisher id. This can be found in brightcove under the Home section if you click on the "profile" link. Punch it in and hit save.

Then click on the Brightcove Account tab and click on the "Update Library". I've provided some other options so that as you're library grows you're not overwriting something you may be working on or you want to limit what it is you're trying to do. For now you should have nothing so you'll just want to add new items. When it's finished, assuming you have videos and playlists in your account, you'll see the number of them displayed. There are some videos that are being transcoded that may not show up immediately. There are also other errors that could have occurred with your videos that may not allow them to be available from the API method calls so if the number of videos doesn't exactly match what you have in your account don't freak out just look at Brightcove first and see if there's something that might be blocking it first. At this point it's worth noting that Brightove's API only supports read/write for videos and playlists but not players. You will have to enter those by hand. I apologize if you have a lot of players and I've had to do a lot of these myself and I would have automated them but I don't make the rules or the API.

Okay so now we've got some media. What else is there?

Well on the Video Library item you'll see that you also have the option of updating just your videos. I thought it would be nice to have update items in a more granular way. There is also a video upload control that has it's visibility hidden. You can opt to use this if you trust yourself to do so. There is an upper limit to what can be uploaded this way. I've found that anything below 5MB is fine but there is no feedback to tell you how long it will take. Anything over 5MB will take so long it may stall and you'll never know. Also you don't really want your server killing itself trying to upload videos when it should be serving up pages, but it's there if you want or need it.

When you click on a Video item you'll be presented with the Video tab. I've created a form that allows you the ability to update the fields that the API allows you to update. The others that can't be updated are still visible though at the bottom. If you're going to update your videos through Sitecore you should use this tab because it updates both Brightcove and the Sitecore item. You shouldn't update the content fields in the content tab because when you do an update those values, if you have update existing items, the data will be overwritten because it was never written back to Brightcove. I'm using Sitecore only to store the information locally but the master copy is Brightcove itself and will always take priority over what is stored. You can also update the video from this tab. Again a very granular level of control. From this tab you can also delete the video. It's there but don't kill yourself with it.

Also on a video is the Image Tab. This allows you to view and upload new images for the video to Brightcove. This is actually quite useful. The API doesn't query for as many image types as you can create but what I could get I do.

On to the Playlist Library. Here you'll find the same as on the Video Library. You can update just the playlists and there are a few options. Similiarly to the Video Library Tab there is also a control that is not visible that will allow you to create playlists. Again it's up to you to uncomment it but it does work I just don't provide it by default.

On the playlist item itself I've provided a form for you to update the fields and like the equivalent on the Video Tab you should do updates to your playlists through this interface because it updates both Brightcove and Sitecore. You can also update and delete the playlist from this tab. You will have to reload the children on the parent node once you do this so the tree is updated for you or you'll get null exceptions. (fun times).

The playlist also has the ability to add a thumbnail image. I don't know why but you can so I built it.

Again as I noted the API doesn't support querying for players so you have to create them yourself. Just right-click on the Video Player Library  item and insert a Brightcove Video Player.

Once you create it you'll need to fill out a few fields. You'll need to fill out the Name, Player ID, Playlist Type, the Height and Width. The description does nothing and is just there for you to keep track. Another thing to note is that you can set the Height and Width to whatever you want. So you can create two player items that point to the same Player ID and have different dimensions. Just consider it. So once you populate the fields click save.

Now jump over to the Video Preview Tab and you'll be able to choose, from a drop down, the videos you've got in Sitecore. You can also select some other options and preview it on the tab itself. This good if you just want to test a few things out before you go banging video items into your content fields.

Here's a final note on the media library: you can create folders. If you've used Brightcove for any length of time you'll notice that you just have one giant list of videos. You can search but at times you just want to be able to sort the enormous volume of videos you've accumulated. I provided folders so that at least in Sitecore you can do just that. It won't affect when you update and you can add security to the folders. All new videos/playlists added to the system will show up in the root and if you enforce strict permissions someone will have to move new videos to their respective locations. I didn't use that much but if you do need it it's there.

Okay so you've installed and setup all your content and now you're ready to start adding things to your pages go to a Rich Text Field that is either has an HTML Profile with Full access which I explained earlier.

Once you open the editor you'll see two buttons: Embed Video and Insert Video Link.

When you click on these you'll be given a dialog window. Here you can set a number of settings that will determine how the video will display.

You should at least start by selecting a player.

What you choose next will depend on the type of player you have. You can select either a video...

or you can select a playlist or multiple playlists.

Some player types will need to have playlists selected (tabbed, combo, single list). Some will need to have only a video selected (single video). If you line up the wrong choice, when you select the "Link" button you will get a warning telling you that the video player doesn't support what you tried to do.

Now assuming you selected the right type and didn't get a warning you'll see what is known as a web control in the wysiwyg editor. Better detail of this is give by a man named John West. Embed and object tags get stripped but storing the data in what essentially is a server control tag is the best way to get the wysiwyg editor to play nice. If you inspect the html you'll see the tag is a custom server control in the BrightcoveSDK.SitecoreUtil library. There is a pipeline event that will cause this to be rendered at runtime. It is selectable and if it is selected when you hit the embed button it will pre-load the settings. You can also double-click on it and change the values as key-value pairs. The link is created using the settings from /system/modules. This is where it determines what site you're on and which settings to use. If you are running a multisite installation, this does use the current url hostname which relies on the user being logged into the specific domain which he is working on. I believe this is preferred behavior so it shouldn't be a problem but it could given there are a lot of custom variations of Sitecore out there.

This is the markup you'll see when you inspect the source. You'll see the server control and the anchor tag that are populated with the data from the dialog window. I'm also storing all Brightcove ID's instead of Sitecore ID's and this is to prevent content pointing to an ID in one environment from failing when it's package and installed on another environment. Notice that the url for the anchor tag is a handler url. This is because there is no formal file or location. I'm just catching the variables and displaying embed code within the window you've called from. The javascript window should be using an IFrame or something like it to load the page.

When you view the page this is what you'll see.

When you click on the link, here I'm using prettyPhoto, you'll see the popup window that will render the video. I would've setup a link from the wysiwyg I'm using but Sitecore Express on a hosted environment is fighting me right now so I took a screenshot instead.

 So that's about it. Where do I go next you might ask. It has been suggested that I should make a custom field type or forgo the media library altogether and use a DataProvider or pull from Brightcove directly. I might do that eventually, unfortunately I don't have a need for it yet so it's not likely to happen soon. If you end up using this or thinking of some aspects that could improve it, please let me know in the comments. I'd like to hear how it gets used. If you do use it and have issues please use the issue tracker at Sukiyoshi. It's just easier for me to have it all it one place.