How to create you own Roku Channel

I recently got a Roku box, and while there is an impressive list of available channels, I wanted to create my own.  I searched around for a way to do this on the net, but there really is very little in the way of a good how-to for windows.  I found THIS link but its obvious the developer is using a *nix variant to develop on, and consequently doesn’t post Windows specific directions.

Links to references:

I am doing all this on Win7 running in a Virtual Machine (VMware Player).

Step 1:  Become a “developer” and install the Roku Software Development Kit (SDK).

Sign up/in to Roku with the account you created when you got your box and sign up for a developer account.

Once you have agreed to the legal stuff, you will have a link to the “Developer Site”

Click on the “Download SDK” link, download to your computer, create some directory to store the files (its not an installer), then extract the compressed archive to that directory.

You should now have something like this:

Create another directory for your “play” area where you will mess around with copies of these files instead of editing the SDK files.

Step 2:  Turn on development mode on your Roku box, and verify its running

From the developer guide pdf file in your SDK, here is how you turn on development mode on your Roku box:

Before you are able to load a development application to your box, you must enable development mode on your Roku Streaming Player. When you enter the special remote control sequence:

Your TV will clearly identify you have enabled development when you get it right.  I had to try a couple of times, with very few pauses in between the remote control key sequences.

While at the Roku box, jot down the (hopefully static) IP address of your Roku box.  You get this via Roku Player Settings –> Player Info.

Go back to your computer and pull up a web browser.  Plug in the IP of the Roku box [http://XXX.XXX.XXX.XXX/], and you should see something like this:

Step 3:  Creating the developer RSA keys

Your going to need a terminal emulator.  My favorite is Putty.  Use it or your favorite.  Get Putty free HERE.

Once you have putty running, create a connection to your Roku box:

Use the IP you validated from your web browser, but use a port of 8085 instead of 8080.

Open a connection, and it will look sort of like this:

At the > prompt, type:

genkey

You may get no response the first time (like I did) try hitting return a couple of times, then try typing genkey again, once it succeeds, it will start putting ….. ++++ type output on the screen.  If it doesn’t work after hitting enter a couple of times, disconnect, and reconnect – you may have to give it a couple of min if your rushing through this.

Once its done its work, it will present you with a Password and DevID like:

Password: i1kOBajlkAWREJTishlejklkwSWezA==
DevID: 8b8b0910-956nmdl1-0pjj-13poj2090adl2093409kd162b

Copy these now, your going to need them later.

Step 3:  Get Some Test Content

Download some content.  To help you out, and for my example, I am going to use some public domain media.  Your going to need some images, and some video.  Here are the supported formats according to the Developer Guide:

Supported Video Formats:

Supported Image Formats:

Lets use a mp4 file from the NOAA:

In a web browser navigate to [ https://marinelife.noaa.gov/media_lib/preview.aspx?ID=7276&p=img ], click on the download link.  Once it finished downloading, you may need to add an extension (mine didn’t have one).  If you need to do this, give it a file extension of .mp4

Now, we need a static image.  You can snip / cut / copy the image from above, or you can get a different image.  I am going to get another image which is from NOAA, also public domain.  I am getting mine from HERE [ https://marinelife.noaa.gov/media_lib/preview.aspx?ID=6483&p=img ].  Again, select the download link.

Now, for our use, we need to create 2 images from this downloaded image.  One is SD, the other is the HD.  Your going to need to re-scale the images (change their size).  You can do this however you want.  I prefer free tools, and I will show you 2 ways.  The first is using the GNU Image Manipulation Program (GIMP).  GIMP is a very comprehensive image manipulation program.  To use it to rescale your image, open the image in GIMP.  Then go to IMAGE –> Scale Image.  This will give you a pop-up box where you can select the correct size.  To NOT maintain the aspect ratio, you need to click on the chain link to unlink the width and height.  This will allow you to set the correct size (which may distort your image).  The HD format image should be 290 pixels wide by 218 pixels high.  The SD format image should be 214 pixels wide by 144 pixels high.

Save the image as a jpeg (export when required, accept defaults), make sure to name then so you can tell if they are HD or SD images.  My test image is by default called Attitude.jpg, so I am going to name them hd_Attitude-290×218.jpg and sd_Attitude-214×144.jpg respectively.

An alternate method, if you just want resize images for this purpose, or don’t want to install a large (but very useful) program like GIMP is to use another piece of freeware called PhotoResize.  This is VERY useful when your doing a LOT of resize operations, and you simply want to resize a whole bunch of pictures to one size (like making a bunch of thumbnails).  This doesn’t require any installation, and by simply renaming the file, you control the options for resizing.  For this purposes, you will need to have two files, one called “PhotoResize290x218.exe” and another “PhotoResize214x144.exe”.  After creating the two files, drag or original file and drop it onto the appropriate PhotoResize binary.  It will create a new file in the same directory as the original that has been resized.  Rename this to an appropriate name (if your unhappy with the new names).

By default, GIMP and PhotoResize will not create files with the same file size as the compression used for the jpeg images is different in the two programs.  The default PhotoResize files will be smaller.  Keep in mind that small images load faster in your Roku, but I am sure you want nice quality as well, so play around with the options.

Currently I have the following files downloaded (ignore the categories.xml):

Step 4:  Look at the SDK examples

Ok, now go to the directory where you downloaded your SDK.  In that directory, there is an subdirectory called “Examples”.  In that directory are two subdirectories “Source” and “Zips”.  In the “zip” subdir, find and copy the directory “videoplayer”.  Then extract this into your testing directory [7zip is a very good open source compression and extraction utility].  If we take a quick look at the contents of the subdirectories of “videoplayer” we see that there are the following contents:

If you read the readme, you will notice that some of the directories in the “Source” directory contain files that are not destined to be delivered with our “channel”, but simply server as examples of what the streaming server would be delivering to the Roku box.  We need to use them, but they should not be a part of the file that gets delivered for use by the Roku.  The easy way to see this is to compare the contents of the source dir with the contents of the same directory which has already been nicely zipped by Roku for us.  The same directories are there, but the contents differ.  For example on my box C:\ROKU-DEV\SDK\examples\source\videoplayer\xml contains files, but C:\ROKU-DEV\SDK\examples\zips\videoplayer.zip\xml does NOT.

So, what we need to know here, is that we are going to need to use some of the files in the C:\ROKU-DEV\SDK\examples\source\videoplayer, but only a subset of them are going to end up as part of our package which will be our “channel”.

Step 5:  Put Your Files on the Internet Somewhere…

Your going to need to have these files available from the internet if your going to publish your channel, even if its private.  So this is the point where you need to plop them out there.  I will explore later the possibility of only using local files (remind me if I forget).

I have my files at my hosting provider, so I will use that as my example.  I use ftp to deliver the files, and again, open source comes to the rescue with Filezilla a free and open source FTP client.  Test by opening a browser and make sure you can navigate to your files directly.

Here are my test files (available via the web directly):

HarborSeal.mp4

sd_Attitude.jpg

hd_Attitude.jpg

We also need to create a directory to store our xml files, so in the same directory where the above files are stored, lets create a directory called xml.

Step 6:  Edit the videoplayer category feeds file

Now we are going to edit the xml files which the Roku box needs to know about to find our files.  The file is located (if you have been following my directory creating scheme) at C:\ROKU-DEV\Testing\videoplayer\source\categoryFeed.brs

This file is a simple text file, written in the BrightScript language.  We don’t really need to worry too much about that at this point, just need to know how to edit.  It seems this file is formatted in a Unix format, so your going to need an editor that doesn’t make it look nasty like Notepad.exe does:

My favorite is Notepad++ a very nice notepad replacement which is also opensource and free.

If you open the file in notepad++ you see a much nicer representation:

Notice, I have also highlighted the area your going to change.

We need to change the one line:

conn.UrlPrefix   = http://rokudev.roku.com/rokudev/examples/videoplayer/xml

to represent the source for our xml file (which we have not yet created).

In my case, in the directory on my hosting provider is where this file is going to live.  I change the path to be:

conn.UrlPrefix   = http://www.herofish.com/OTHER_PAGES/Testing/xml

This allows our channel to get a listing of things to display.

Step 7:  Create / Edit our XML files to provide the content

Next we need to get two files and edit them.  The files we need are example files provided in the SDK.  They are from the source xml directory:

These are files delivered by the web server that outlines where to find the actual content.  In our test, we need the two files:

C:\ROKU-DEV\SDK\examples\source\videoplayer\xml\categories.xml

C:\ROKU-DEV\SDK\examples\source\videoplayer\xml\themind.xml

We need to copy these files to another location so we don’t mess up the default one delivered in the SDK (if you do, simply re-download the SDK and overwrite your extracted copy).

Lets copy them to C:\ROKU-DEV\Testing:

Now, open categories.xml in a text editor.  Did I mention how nice Notepad++ is?

The first thing you need to take a look at is the relationship between the two files we just copied.  You can see that there can be multiple categories, and each category can have multiple category leaves.  The category has a title, description and two pictures.  The categoryLeaf has a title, description and a feed.  The feed is an xml file.  Both of these are going to live on our webserver on the internet.

We are going to edit the highlighted areas.  First, we are going to simply delete the additional categories to keep our example simple.  Our file should now look like this:

Now, lets change where the items are pointing to, so we can use our web files.  If you want to make any name changes, this is the time to do it (for the files, and in the files).  You should now have a categories.xml file that looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<categories>

      <!– banner_ad: optional element which displays an at the top level category screen –>
      <banner_ad sd_img="http://rokudev.roku.com/rokudev/examples/videoplayer/images/missing.png" hd_img="http://rokudev.roku.com/rokudev/examples/videoplayer/images/missing.png"/>
     
    <category title="Marine Mammals" description="Streaming Video of Marine Mammals" sd_img="http://www.herofish.com/OTHER_PAGES/Testing/sd_Attitude-214×144.jpg" hd_img="http://www.herofish.com/OTHER_PAGES/Testing/hd_Attitude-290×218.jpg">
        <categoryLeaf title="Harbor Seal" description="" feed="http://www.herofish.com/OTHER_PAGES/Testing/xml/themind.xml"/>
    </category>
</categories>

Next we need to edit the file C:\ROKU-DEV\Testing\themind.xml which we copied a while ago from the source subdirectory of the SDK.  This points to the actual media to stream.  The example has a number of items that belong to this categoryLeaf:

We are going to delete all of these except for one item, and we are going to edit the resultlength and endindex to be 2 instead of 4.  We are also going to point the item to our mp4 file sitting at the hosting provider.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<feed>
    <!– resultLength indicates the total number of results for this feed –>
    <resultLength>2</resultLength>
    <!– endIndix  indicates the number of results for this *paged* section of the feed –>
    <endIndex>2</endIndex>
    <item sdImg="" hdImg="">
        <title>Harbor Seal</title>
        <contentId>10001</contentId>
        <contentType>Talk</contentType>
        <contentQuality>SD</contentQuality>
        <streamFormat>mp4</streamFormat>
        <media>
            <streamQuality>SD</streamQuality>
            <streamBitrate>1500</streamBitrate>
            <streamUrl>http://www.herofish.com/OTHER_PAGES/Testing/HarborSeal.mp4</streamUrl>
        </media>
        <synopsis>Lets have some fun streaming video to our Roku player from our own channel</synopsis>
        <genres>Clip</genres>
        <runtime>1260</runtime>
    </item>   
</feed>

Now we need to send both the files to the internet destination we decided on earler, in my case:  http://www.herofish.com/OTHER_PAGES/Testing/xml/

Step 8:  Install the development application on OUR Roku Box

Now we need to locally install this app on our Roku box. 

Navigate to the test files we copied from the zip file in the SDK (where you edited the file “categoryFeed.brs”

In my environment its :  C:\ROKU-DEV\Testing\videoplayer

Select all the files here with a compression utility (7zip works great), and add them to an archive named by the directory they are in, this should result (in my case) in a file named videoplayer.zip

Open our development application Roku webpage again, browse to the zip file you just created, then click on Install:

If its successful, it should look like this:

Click on the link “Packager”, populate a name for this application and a version seperated by a slash, then plug in your password you got from the genkey command way way back in the beginning.  Finally, click on the package button.

If successful, it will look like this:

Click on the package link so you can download the package to your computer, and lets save it in the Testing dir for now.  It will be names in the long random string just like the link shows it, but the a file extension of .pkg

Step 9:  Upload our test Channel to Roku

Next, log into Roku.com and click on “My Account” then, click on the link “Developer Site”.  Then click on the link “Manage My Channels”

Since we are testing, lets create a private channel.  Click on the box “Add Private Channel”

‘

On the first page, we are just going to accept all the defaults, and click “continue”

Fill in the information, and select “Create”:

You can add screenshots if you like, otherwise, click “Go Back”

Then, browse to the package file we downloaded from our local Roku box, and click “Save”.  You should see the next screenshot

Once you see the “Publish” button enabled go ahead and click on it

Now you have a new channel!!!

Step 10:  You thought you were done?

Now we need to verify our channel actually delivers something…

Click on our new channel link at the Roku website:

And we get offered to add this new channel to OUR Roku Channel listing

Click on Yes Add channel, and Roku should confirm the new channel was added:

Open up Putty and make a connection to our Roku box again:

Now go to your TV and add the new channel

While your monitoring the terminal session with the Roku player, (the debugger) when you try to access your channel from your TV, you should see the following:

Which indicates that our xml file was successfully read.  On your TV you should see a new channel!

NEXT – Fix the TED icons etc so we have our own Channel icons, and try some streaming content from other sites servers…

Related posts:

1. vSphere Client and general VMware/ESXi notes–Part 1