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 a scrolling list on the left side of the screen.
  The contents of the directories will be displayed as cover images that can be
  selected and played from the poster grid on the right.

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

  movies    A list of movies to play (mp4, wmv, mov, m4v)
  episodes  Episode selector for the files in the directory (mp4, wmv, mov, m4v)
  songs     Play the songs using the song player (mp3)
  photos    Show the images as a slideshow (jpg)

  Support for playback of songs and photos has not been added yet.

  Videos should be valid files supported by the Roku (mp4, wmv, mov, m4v). HandBrake
  as several Roku presets that work fine.

  == Cover Images ==

  If the directory contains a png or jpg file named for the video with a SD, HD,
  or FHD suffix it will use that as the poster. Eg. Goonies-SD.jpg
  If there is no is no specific poster file for the video it will use 'default'
  instead. eg. default-SD.jpg

  Sample directory listing:
    Firefly/
    Home_Movies/
    Movies/

    ./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 playback position of each video.

  The keystore 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 like this:

    $HTTP["host"] =~ "^movies\.lan(:[0-9]*)?$" {
        server.document-root = "/Movies/"
        dir-listing.activate = "enable"

        $HTTP["url"] =~ "(^/keystore/)" {
            proxy.debug = 1
            proxy.balance = "fair"
            proxy.server = ( "" =>
                               (( "host" => "127.0.0.1", "port" => 9002))
                             )
        }
    }

  See https://www.brianlane.com/clortho-a-simple-keyvalue-server.html for a
  blog post about the keyserver.


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
  network information screen).

  https://developer.roku.com/docs/developer-program/getting-started/developer-setup.md

  (which is - HOME, HOME, HOME, UP, UP, RIGHT, LEFT, RIGHT, LEFT, RIGHT) and then set
  a password.

  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 DEVPASSWORD=password

  And then install the application with:
  make install

  You can also install the .zip file generated by 'make install' using the web interface.
  Visit the device with a web browser, log in, and upload the zip.

3. Debugging

The Roku has a couple of open ports on it for debugging:
* 8085 is the console output from the running app
* 8080 is the debug server

4. Support/Contribute

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