Developing a Basic Roku Channel

The Roku box is arguably the most influential home entertainment devices created in the last 10 years.  I believe it really catalyzed the video streaming services into the main stream.  It allows for video producers to break free from the limits of streaming video viewing on a computer.  This was extremely important for Netflix as they introduced their streaming services.  It would not have gained the popularity it needed if families could not watch in their living room using their existing televisions.

But creating content for the Roku is not a closed system.  Anyone can create a Roku video channel.  The process is not very intuitive, so I wanted to show step-by-step how to create a basic Roku channel.

Note:  There are several sites that have similar tutorials.  Most are based on the Roku’s own SDK.  Over the course of the upgrades to Roku’s main operating system, some of these tutorials have incorrect information.  I can only attest that this post will stay relevant as long as the Roku system does not introduce a breaking change.

Preliminary Information

Here are some of the things you will need to begin.

• Roku Developer Account – You will need to sign-up for a developer account with Roku.  This will give you access to download the SDK files and documentation.  Go here to register http://www.roku.com/developer
• Roku SDK files and documentation – Once you have signed up for a developer account, you need to download the SDK files and documentation.  On the developer home screen, click on the “Download SDK” link to download the ZIP file.  Unzip the folder as we will be using it to develop our basic channel.
• Of course, you will need a Roku to develop your channel.  Unfortunately, they have not yet created any type of emulator to develop only on a computer.
• You must have public internet hosting.  The XML files and video files we use will need to be publicly hosted.  We will explore two ways of hosting videos: with Vimeo and with personal hosting account.
• You will need some sort of image editor.  Some image files need to be certain sizes and types.

Roku has done a really good job creating the SDK to give developers a good starting point in creating channels.  They have provided several sample channels as long as a host of documentation.  Roku utilizes the BrightScript development language to create channels.  I would bet that most seasoned developers have not used this language.  But no fears as we will not be doing any code writing in this tutorial (we will use an example channel provided by Roku.)  If we did have to do some coding, the BrightScript language is very similar to other Basic-type languages and easy to learn.

If you have time available, I would recommend reading the “Read Me” document that came with the SDK as well as the “Developer Guide” that is in the “documents” folder of the SDK.  Many of the steps in this tutorial can be further explored in the developer guide.

Getting your Roku into Developer Mode

Your Roku player is not setup to have custom channels by default.  You will need to get it into a developer mode to add your new channel.  To get into the developer mode, on the home screen press the following key combination into your Roku remote:

Home (3 times), Up (twice), Right, Left, Right, Left, Right

You will see the following screen appear.  Select the “Enable installer” and your Roku will restart.  Take note of the IP address here as it will be important as we move on.

Creating Our Basic Channel

There are 4 basic files that are used by the Roku in developing a channel:

• BrightScript files – these include the code that runs a channel.  They have a “.brs” file extension.  We will be using the scripts included in the “videoplayer” sample provided by the SDK.
• XML files – the Roku used XML files to gather the metadata for the videos it will pull for a channel.  These are not imbedded in the channel itself, but must be publicly hosted by you.  The good thing about us hosting the XML files is that we control them and can make them dynamic if we would like, thus creating a more useful and continuously updated channel.
• Image files – image files (i.e. JPG, GIF, and PNG) are used to both create a unique look of your channel but also to have screenshots of our videos.
• Video files – these are MP4 videos that will be streamed through the channel.  For exact specs supported by the Roku, refer to the developers guide.

We are going to be using the “videoplayer” sample channel provided by Roku.  For this example, I am going to create a channel that has one video.  Go to the “/samples/source/videoplayer/” folder in your Roku SDK folder.

The Images

The first thing we need to do is create the images necessary for our channel.  There are two types of images:  channel look-and-feel and video screenshots.

The channel look-and-feel images are located in the “images” folder.  The Roku sample is using the “Ted Talks” images.  I am going to change the images to be a different color to give it a unique feel.

The video screenshot images will be taken while playing the video I want to stream.  I wait until the I get the scene I want as the screenshot and then take a system screenshot.  I then use my image editor to crop out only the video section.

whole page

video screenshot cropped from page above

There are two sizes of images that needs to be created.  One is used for SD televisions and the other is for HD televisions.  Below are their sizes:

• HD – 290px width by 218px height
• SD – 214px width by 144px height

HD video image

SD video image

Please see the Design and Artwork guideline documents to see full details on images in your channel.

The Video

There are two ways that you can host videos.  One is to just put the video file on your public hosting where the Roku can access it.  The second is to use a video sharing service such as Vimeo.  We are going to use Vimeo for this as there are several advantages.

Not all video services can be used.  The one thing that these services have to offer is a MP4 downloadable version of the video.  Vimeo does support this.  We will need to get the download link for the video we want to use.  On Vimeo, if a user has given download rights to a video, you will see a “Download” link under the video itself.  Clicking this link gives you the video options.

This is where I had to fight with Vimeo a little.  We want to use the “SD .MP4 file” link.  But the link provided is not exactly what we need.  What we have to do is right click on the “SD .MP4 file” link and copy the link address.  You then paste this into your web browser’s address bar and go to the link.  You will see that Vimeo now changes the link address to the REAL link we want.  You will copy this new link in the web browser address bar into the “themind.xml” file discussed in the section below.

The XML files

All video information is inputted into XML files.  The XML files for this sample can be found in the “xml” folder of the “videoplayer” channel.  We will only be modifying two files:  “categories.xml” and “themind.xml”.

The “categories.xml” file contains the information of all the selectable categories in the main channel homepage.  Behind each channel can be a number of videos (or episodes.)  We will want to modify the XML file to the setup below.  You will need to replace the “MYDOMAINNAME” with your public hosting.  Take note of the folder layout.  You can make this anything you want, just make sure it is represented in file correctly.

The “themind.xml” file has the information on our individual videos.  We want to modify it to look like the text below.  The “sdImg” and “hdImg” tags hold the location of the screenshots we created earlier.  Also the “streamUrl” is the location of the video.

Also note that the “contentQuality” and “streamQuality” are set to “SD”.  You will want to set this to what television you are using.  I just happen to be using an old 4:3 television so I need to set my quality to “SD”.  If you have a newer widescreen television, you can set this to “HD”.

BrightScript Source Files

We are not going to be writing any code in our BrightScript files.  But we do need to modify where our channel looks for the “categories.xml” file on the internet.  In the “source” folder, we need to modify the “categoryFeed.brs” file.  Look for the InitCategoryFeedConnection function and change the UrlPrefix to point towards the XML folder on your public hosting.

The Public Hosting Setup

We now need to setup our public hosting to contain the files that will get served to our channel app.

Here is a screenshot of what I have uploaded to my public hosting.

GUI folder

Images folder

XML folder

Packaging Channel

We will be uploading a single ZIP file that contains everything needed for the channel.  The sample channel we have been using is already pretty much setup to be compressed and uploaded, but lets look at a couple of things on how this works.  The metadata of the channel is contained in the “manifest” file.  Opening this file in our text editor shows the following:

The only thing I changed was the title.  We can also change the subtitle.  These two are what shows up for our channel when we are on the Roku home screen.  It also points to a couple of images that are used.

To create the channel zip file, we will add the “artwork” folder, “images” folder, “source” folder, “xml” folder, and manifest file to a zip file.  I just named the zip file “videoplayer.zip”.

Uploading the Channel

Now that we have our zip file and our XML and video files out on the internet, we can now upload our channel to our Roku.  It helps to be in front of your television and Roku during the rest of the install and testing.

First you will need to open up your web browser and type the IP address to your Roku such as http://192.168.0.105.  You will get a screen as shown below.

Click on the “Choose File” button.  You will then be shown an open box in which you need to navigate to where you’re your channel zip file is located, select it, and then choose open.  The zip file name is now be shown next to the “Choose File” button.

Click on the “Install” button to install the channel.  You should hear a noise come from the television as the Roku verifies the channel install.    The Roku will also now show you a record on the website representing your new channel.

If you scroll to the end of your channel list on your Roku, you new channel should now be visible.  At this point, your channel is complete and ready to be used!  Congrats!

Images of Navigating Custom Channel

Roku home screen with custom channel.

Custom channel home screen with “Technology” category.

Technology category selected, showing “Video 101” video icon.

“Video 101” selected, shows details such as running time and synopsis.

Playing video. Roku video buffering screen.

Video is playing.  Hosted on Vimeo.

When Things Don’t Work

As with all software development, sometimes we run into issues and things just do not work as expected.  Even when I was creating this tutorial, I ran into issues that had to be diagnosed and fixed.  Since the number of issues that could come up are impossible to account for, I am just going to go over the bugs I had and how I fixed them.

The Roku Debug Console

The Roku is setup to be able to give us some help when trying to diagnose issues we are having.  To get to the debug console, we will need to telnet into our Roku box. Open up a command console and telnet into your Roku box’s IP address over port 8085:

telnet 192.168.0.105 8085

By default, the debugger is running.  If your channel is installed, anything you do inside that channel will start to print debug information into the console window.

Debug console running when custom channel is being used.

Reloading a Channel After a Change

If you are fixing a video or XML file, you will only need to update your public hosting and your channel should accept the changes by going all the way to the Roku home page and re-entering your channel.  If you have to change a file inside the channel zip file (such as a BrightScript file) you will need to re-upload your channel.  On the Roku webpage, click the “Delete” button next your channel.  You can then repackage your channel zip file and upload as described above.

Bug:  My channel would not open.

The first bug I experienced was that I could not open the channel.  Not a good way to start!  The first thing I did was check all the URL’s that are in the XML and BrightScript files to look for a typo.  Sure enough, in the “categoryFeed.brs” file I forgot to put the “.com” at the end of my URL to the XML folder on my public hosting.  Since this was a fix in a BrightScript file, I had to re-upload the channel.

Bug:  My episode list would not appear.

When I clicked on my “Technology” category, I would get a blank “Receiving…” screen (see image below.)

This was a little harder to fix.  What I was seeing was the Roku was having difficulties parsing the “themind.xml” file (see last line of image below.)

At this point, I wanted to verify that the “themind.xml” file was valid XML.  Most web browsers can verify XML files.  Sure enough, when I opened up the XML file in my web browser, I had made a mistake in typing my XML file (see image below.)

I made the appropriate changes and fixed the XML file.  All I had to do was replace my existing XML file on my public hosting with the new file (no channel re-upload was required.)

Bug: My video would not play

Once I was able to get to the video screen, the video would not play.  Unfortunately, the debug screen did not give me any instant help on this one.  It only gave me an obscure error message.  The error was: “Video request failure: –5 7” (see last line of image below.)

This is where Google comes to the rescue.  I searched for the specific error and was taken to the Roku developer forums that explained that you have to set the content and stream quality in the “themind.xml” file to match the television you are watching the video on.  Once I made this change, all was well.

About Hosting Video on Your Public Hosting if using IIS

In this tutorial, I showed how you can use Vimeo to host your videos.  But you may want to host the video files yourself.  Since I am a Microsoft .Net developer, all of my personal hosting is through Microsoft IIS.  What I did not realize is that IIS by default does not know how to serve an MP4 video file.

To fix this, you will need to add a new MIME type to your website.  The new type should be extension “.mp4” and the type should be “video/mpeg”.

That is the end of this tutorial.  I hope you have fun getting into Roku channel building.  As you can tell, there is much more that can be done.

Happy coding!