Roku application for streaming home media from a basic http server.
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts nobif: Print movies without .bif files Jul 21, 2013
.gitignore Added library.db to .gitignore Mar 5, 2010
LICENSE Added GPL v2 license Mar 6, 2010


Home Media Server
by Brian C. Lane <>

1. Server Installation

  A web server that can handle HTTP range requests. Apache and lighttpd are two
  examples. The server needs to be setup to serve up plain html directory
  listings. lighttpd works out of the box, Apache needs to have the fancy
  indexing disabled.

  A Roku player with developer mode.

  == Port 80 ==

  Currently most of the Roku player's APIs work with alternate ports. But not all
  of them. So it is best if you can run the server on port 80. Under Linux the
  easiest way to do this is to just connect port 80 to port 8888 of the server by
  adding this to your /etc/sysconfig/iptables (or similar) file:

  -A PREROUTING -p tcp -d --dport 80 -j REDIRECT --to-ports 8888

  Replace the IP with the IP of the server it is running on. It will direct all 
  port 80 traffic to port 8888.

  Or if you can, just run your webserver on port 80.

  == Configuration ==

  Setup the webserver so that the top level directories are your categories.
  These names will be displayed as the grid display's category names. The
  contents of the directories will be displayed as cover images that can be

  They type of playback for a directory is controlled by an empty file inside
  the directory named:

  movies    A list of movies to play
  episodes  Episode selector for the files in the directory
  songs     Play the songs using the song player
  photos    Show the images as a slideshow

  (As of Version 3.0 songs and photos are not supported)

  Videos should be valid files supported by the Roku (mp4, wmv, mov, m4v)
  If there is a file ending in .txt that will be used for the details page.

  == Cover Images ==

  If the directory has a file named default-SD.png or default-HD.png it will
  use that image if the video files do not have -SD.png images for them.

  You can add cover images for each video by naming them <video-name>-SD.png
  -HD.png, -SD.jpg or -HD.jpg

  The first row of the grid is used for the Search and Setup screens. You can
  set the images for these by placing images in the root directory of the

  Search-HD.png  Search-SD.png  Setup-HD.png  Setup-SD.png

  IMPORTANT: As of v3.1 /Setup-SD.png is required for HMS to start. If it is
  missing it will fall into the URL editing dialog.  This is so that you can
  more easily recover from entering an incorrect URL.

  Sample directory listing:



  == Keystore ==

  An optional keystore is supported at URL + /keystore/<key>

  If present it will be used to save the last selected video for each row and
  the last playback position of each video.

  The presence is detected by looking for URL + /keystore/version
  and values are stored by POST with value=<value>

  You can use my clortho project as the keystore by proxying requests to the
  /keystore/ prefix to it with lighttpd.

2. Client Installation

  Make sure your Roku is in developer mode, change to the HMS directory and
  and set the target IP for the install (you can find the IP on the Roku's
  information screen).


  You may also need to set the user and password, if one is set for your device:
  export ROKU_DEV_USER=rokudev
  export ROKU_DEV_PASSWORD=password

  And then install the application with:
  make install

3. Support/Contribute