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.image
  • 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.

Photo Jul 18, 2 01 06 PM

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.

MainMenu_Icon_CenterFocus_HD

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.

image
whole page

image
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

video_hd
HD video image

video_sd
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.

image

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.

image

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”.

image

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.

image

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.

image
GUI folder

image
Images folder

image
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:

image

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.

image

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.

image

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.

image

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

Photo Jul 18, 7 15 07 PM
Roku home screen with custom channel.

Photo Jul 18, 7 15 17 PM
Custom channel home screen with “Technology” category.

Photo Jul 18, 7 15 26 PM
Technology category selected, showing “Video 101” video icon.

Photo Jul 18, 7 15 35 PM
“Video 101” selected, shows details such as running time and synopsis.

Photo Jul 18, 7 15 59 PM
Playing video. Roku video buffering screen.

Photo Jul 18, 7 15 43 PM
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.

image
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.)

Photo Jul 18, 7 48 42 PM

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.)

image

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.)

image

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.)

image

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!



Comments

  1. Daniel Rizzo October 11th

    Comment Arrow

    Congratulations on this blog!

    This is probably the best article describing how to create your own Roku channel without having to read the entire Roku SDK documentation.

    For those broadcasters interested in delivering their message through their own Roku channel but without the time, technical knowledge or patience to build it on their own, Frontlayer is an AWS-powered cloud video platform that bundled the development, web-based management, content hosting and CDN distribution into a single service:

    http://www.frontlayer.com/roku-channels

    It may even be of great interest for developers who have created and published their own Roku channels, but are looking for an easy way to manage all of their content, both VOD (pre-recorded) and live, from a single web-based interface, with direct cloud storage, CDN integration and instant channel updates already bundled.


  2. Trey Gourley October 12th

    Comment Arrow

    Daniel,

    Thanks for visiting and you find it useful. Your technology and services look interesting and would definitely be worth a look for roku devs.

    Thanks again!


  3. Stephen October 22nd

    Comment Arrow

    Hi Trey, I was able to get my first channel approved and it is now in the channel store.
    I am however having problems with my second channel.
    The changes I am making are not showing up when I sideload. I am still seing the graphics that came with the example, not the new graphics that i inserted. Do I need to reset the Roku Box.


  4. Trey Gourley October 23rd

    Comment Arrow

    Stephen,

    Congrats on your first channel! As for your issue, it could be the case that you might need to reset. If you have pushed multiple versions up, it might work to remove it completely, and then reload new.


  5. jason January 23rd

    Comment Arrow

    Great tutorial, but the images don’t seem to be showing any longer? Any chance you would fix?


  6. Trey Gourley January 23rd

    Comment Arrow

    @jason sorry for the image issue. I recently switched hosting and it messed up the images. It is fixed now.


  7. MrQuestion February 17th

    Comment Arrow

    Cool tutorial

    I’m fighting with “can’t parse feed” error

    I wrote some software that genned the XML from a database – getting close!

    On your comment to F Ramos on June 5 – if he or she zipped up the application from the folder (and not the individual files and subdirectories) they will get the Manifest Missing error.

    You can’t zip up the whole folder – you have to do it so the manifest file is in the root of the zip package.

    Jeez there are a LOT of missing, finicky, ill explained things in the ROKU docs – thankfully there are people like you to help us muddle through.

    just an FYI


  8. George Brown August 16th

    Comment Arrow

    Hello Trey,
    I created a channel using videoplayer to stream live and vod contents. When streaming live content I keep getting 0m on my screen.
    Here is a part of my xml code.

    Live Stream
    10003
    Live
    SD
    hls

    hls
    SD
    0
    http://golive24.christianworldmedia.com:1935/emmanuelstream/emmanuelstream/playlist.m3u8

    Live Stream
    Live
    Live

    Is there a way to fix this. Thanks for your help.


  9. DevNoob August 17th

    Comment Arrow

    I am new to development and I found this tutorial to be straight forward and awesome. Thanks!


  10. Bill September 26th

    Comment Arrow

    Interesting information. I got into making my own roku channels about 4 years ago. I have two in the channel store. Military Chronicle and Tips For Survival. I also have several private channels. One of them is John 3:16 channel which features sermons by John C. Vaughn.


  11. Kevin Duggan January 25th

    Comment Arrow

    Thanks for the help here, I was hoping to use Videos I have on YouTube, will this be possible? I see you advise to use Vimeo,.
    Thanks
    Kevin


  12. Mike February 20th

    Comment Arrow

    Thank you for this Cool Tutorial.
    I was very happy to create my first channel using the tutorial.
    It was successfully published to Roku.

    While I was learning with roku, I found a very useful website that creates Roku channel without any complex configurations and no need to side load, they called it Channel Maker http://www.findstep.com I’ve created more channels here and published also to roku.

    But without this tutorial, might be my mind will not be opened with the possibilities. Thanks


  13. Cris March 14th

    Comment Arrow

    Hi Trey, I made a Roku channel following your directions and it works great (IN HD). But as soon as I go to roku>settings> and change the screen size to 4:3 SD for testing the channel, my channel loads, but the videos won’t play. So, my channel only works in HD. I am using Vimeo Pro, and the videos do work in HD mode, so I don’t think that’s the problem. Do you know how I can solve this issue? I am using the videoplayer from the Roku SDK.


  14. Alex June 14th

    Comment Arrow

    Nice tutorial, but the part on Vimeo needs to be updated. First, the method of getting the actual URL would not work because the resulting URL uses SSL. Even if it did work, it would expire and stop working after a while. The trick is to obtain the actual URL to the mp4 file from the redirected URL (which does not change) using BrightScript, and then pass this URL to the player.
    If you could update the article to show how to use Vimeo as the streaming server, that would be great.


  15. Jason Dowd July 29th

    Comment Arrow

    Hi Trey,

    I built the Roku Channel and it got published. We want to incorporate our Live365 radio stream. We want to have a category for it, then when they click the category it goes to our radio stream. Roku said that we need to use a roAudioPlayer but I have no idea how to make that work for us. The Categories work off an XML manifest, they said springboard to the roAudioPlayer but I don’t have that file in my manifest either. Can you help?


  16. Arun January 29th

    Comment Arrow

    i wish to write a web browser for roku. can you point me to some development links.


  17. Arun January 29th

    Comment Arrow

    i wish to write a web browser for roku can you point me to developer links


  18. Bon February 15th

    Comment Arrow

    My doubt is as simple as launching a web URL. Do we have a container or component like web view to wrap the web content or does it need to be parsed and re written using script ?


  19. Bon February 15th

    Comment Arrow

    Hi ,

    My issue is as simple as launching a web url. Do we have some container or component like web view for same or some other work around ?


  20. Chris April 13th

    Comment Arrow

    Hello, can someone help me on modifying my monthly subscription channel to check the users account to see if the subscription is still active at launch please? currently my channel is installed starting the monthly subscription but when the month runs out and they have canceled, the channel still works 🙁 Thank you


  21. vishnu vijayan April 28th

    Comment Arrow

    Hi Trey Gourley … your tutorial is really nice for a basic or new roku developer .. i need more information about roku . Brightscript working and the methods using


  22. Stephen Lovell August 12th

    Comment Arrow

    Hi guys, I hope that this forum remains active. It was a great help to me when I was building my channels.


  23. Long May 16th

    Comment Arrow

    Hi Trey,
    I had spent two days trying to find where are my errors, but couldn’t. Thanks to your lesson, at last I found where were my errors – the content and stream quality in my xml files did not match the television i connect my Roku with.
    Thank you so much.


Add Yours

  • Author Avatar

    YOU


Comment Arrow




About Author

Trey Gourley

I was born-and-raised in Muncie, Indiana where I obtained a degree in Computer Science from Ball State University in 2005. Aside from my various web development activities, I enjoy music, playing the guitar, singing, exercising, reading, and relaxing in-front of the television. I still live here in Muncie with my wife, Jena, and Australian Shepherd, Mik Dundee.