INSTALL

MythRoku 2010 Peter Nevill
Unless otherwise stated (the @license tag at the top of the file), all files are
distributed under the GNU General Public License.

MythRoku is for streaming MythTV recordings and videos via Roku player.

Prerequisites:
 - Functioning MythTV backend and MythWeb with function streaming of recordings.
 - All recordings and videos stored in H.264 format (.mp4, .m4v, .mov).
 - Web user (e.g. apache) permissions to delete recordings.
 - php-pdo, php-xml and php-gd
 - See 'Tools' section below for some optional prerequisites.

For more information see the Roku developer site:
 - http://www.roku.com/developer

--------------------------------------------------------------------------------
Setup
--------------------------------------------------------------------------------

 1) Install the private channel or "side-load" to your Roku to development mode

    If you use the private channel (http://owner.roku.com/Account/ChannelCode/?code=YWWMH) 
    then you can skip to #2 and ignore #5
    
    With your Roku remote, enter the following:
        Home 3x, Up 2x, Right, Left, Right, Left, Right

    Make note of the IP and the password (firmware asof 5.2) that you set!
    
    add the following to your .bashrc file "ROKU_DEV_TARGET=roku.ip" 
    Where roku.ip is the ip address of your Roku player.
    
    for Roku box with 5.2 or later firmware a side-load requires authentication.
    add ROKU_DEV_PASSWORD=roku.passwd to your environment as above.
    
 2) Modify MythWeb to enable streaming of H.264 files

	Modify /usr/share/mythtv/mythweb/includes/utils.php by adding the following
    around line 247:

	    case 'mp4' : return "$url.mp4";
            case 'srt' : return "$url.srt";
            case 'bif' : return "$url.bif";

    Modify /usr/share/mythtv/mythweb/modules/stream/stream_raw.pl by adding
    additonal elseif in the file type section:

    if ($Path[3] =~ /srt/) {
        #TODO language $Path[4]
        $filename =~ s/\..+?$/\.srt/g;
        $basename =~ s/\..+?$/\.srt/g;
        $type   = 'text/plain';
        $suffix = '.srt';
    }
    elsif ($Path[3] =~ /bif/) {
        my $HdSd = "";
        $HdSd = "_$Path[4]" if ($Path[4]);
        $filename =~ s/\..+?$/$HdSd\.bif/g;
        $basename =~ s/\..+?$/$HdSd\.bif/g;
        $type   = 'image/jpeg';
        $suffix = '.bif';
    }
    elsif ($basename =~ /\.mpe?g2?$/) {

[...]

    elsif ($basename =~ /\.mp4$/) {
        $type   = 'video/mp4';
        $suffix = '.mp4';
    }
    elsif ($basename =~ /\.srt$/) {
        $type   = 'text/plain';
        $suffix = '.srt';
    }
    elsif ($basename =~ /\.bif$/) {
        $type   = 'image/jpeg';
        $suffix = '.bif';
    }

	if you are using authentication to protect your mythweb (best practice)
	you need to add the following to your mythweb.conf file (near the top)

 3) Set up the mythroku directory

    You can simply copy the mythroku directory to you mythweb directory
    (typically /usr/share/mythtv/mythweb), but it is easier to just create a
    symbolic link. Regardless, make sure this directory has the same permissions
    as your webserver.

    Ensure that the .htaccess file is in the <pathto>/mythweb/mythroku/
    directory. This simply has:

        RewriteEngine off

    This will stop mythweb from adding its templates to the XML data.

	If you are using authentication to protect MythWeb (best practice), you need
    to add the following to your mythweb.conf file (near the top):

	    <LocationMatch .*/mythroku*>
	        Allow from 192.168.1.0
	    </LocationMatch>

    Edit the settings.php file with your local parameters (i.e. webserver URL
    and MySQL credentials.

 4) Convert all video files to MPEG-4 (H.264) format

    The Roku can only stream MPEG-4 video files (.mp4, .m4v, .mov) and
    recordings generally are stored as MPEG-2 video files.

	Create a user job in mythtv (mythbackend setup-> general-> Job Queue) and
	add the following to a job command:

	    <pathtomythrokuplayer>/tools/rokuencode.sh "%DIR%" "%FILE%"

	In your mythconverge -> setting set the AutoRunUserJob1 (or whichever job
    you set it to) data = 1. This will make sure the job is run after every
    recording.

    rokuencode.sh can also be used in the command line to convert existing
    MPEG-2 files.

 5) Install MythRokuPlayer to your Roku

    Make sure you set the ROKU_DEV_TARGET environment variable to your Roku's IP
    address. See the details in <pathtomythrokuplayer>/Makefile to see how this
    is done.

	Once set, simply type the following command in <pathtomythrokuplayer>/:

	    $ make install

	When you first open the newly installed MythRokuPlayer channel, you will
    need to set the path to the mythroku directory on your webserver. For
    example:

	    http//192.168.1.10/mythweb/mythroku

 6) Copy CCExtractor & biftool to /usr/bin to make them available system wide
    if you intend to use subtitles & the Roku FF/REW bif trick files.

--------------------------------------------------------------------------------
Debugging
--------------------------------------------------------------------------------

To access the MythRoku debug console, execute the follwoing:

	telnet <roku_ip_address> 8085

For example:

	telnet $ROKU_DEV_TARGET 8085 or telnet 192.168.1.8 8085

You may need to comment out the following line in /etc/my.cnf to allow access to
MySQL:

	bind-address = 127.0.0.1

You can use mythtv_test.php to check your setup. They draw from the same data
that is used to create the XML files for the Roku. If this does not work, then
MythRoku will not.

--------------------------------------------------------------------------------
Additional Tools
--------------------------------------------------------------------------------

There are a few tools in <pathtomythrokuplayer>/tools that may help you along
the way:

mythrokumake:
    A simple wrapper script for make that does two things:
        - Avoids the need to add an entry in your ~/.bashrc file for the
          ROKU_DEV_TARGET environment variable.
        - Allows you to specify multiple Roku targets if needed.

rokuencode.sh:
    Converts MPEG-2 files to MPEG-4 (H.264) using HandBradeCLI.

    Prerequisites:
        - HandBrakeCLI: To convert recordings into H.264 format.
        - CCExtractor: To extract srt subtitles (download from http://ccextractor.sourceforge.net/download-ccextractor.html)
        - ffmpeg & biftool: To create bif trick files for fast forward/rewind; biftool is part of the Roku SDK. You must register your Roku account as a developer to download the SDK at https://owner.roku.com/Developer.