README

Home Media Server
by Brian C. Lane <bcl@brianlane.com>


1. Server Installation
  == REQUIREMENTS ==

  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:

  *nat
  -A PREROUTING -p tcp -d 192.168.101.4 --dport 80 -j REDIRECT --to-ports 8888
  COMMIT

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

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

  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:
    Firefly/
    Home_Movies/
    Movies/
    Search-HD.png
    Search-SD.png
    Setup-HD.png
    Setup-SD.png

    ./Firefly:
    default-SD.png
    episodes
    Firefly-S01E01-Serenity.mp4
    Firefly-S01E01-Serenity-SD.bif
    Firefly-S01E02-TrainJob.mp4
    Firefly-S01E02-TrainJob-SD.bif

    ./Movies:
    101Dalmations.mp4
    101Dalmations-SD.bif
    101Dalmations-SD.jpg
    movies

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

  https://www.brianlane.com/clortho-a-simple-keyvalue-server.html


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

  http://sdkdocs.roku.com/display/sdkdoc/Developer+Guide#DeveloperGuide-71EnablingDevelopmentModeonyourbox

  export ROKU_DEV_TARGET=192.168.101.143

  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

  http://github.com/bcl/HMS/
  homemedia@googlegroups.com
  http://groups.google.com/group/homemedia