
MythStream v0.17 INSTALL
=========================

---------------------
***** UPGRADERS *****
---------------------

A mythstream upgrade
- will *not* upgrade your parsers
- will *not* touch your stream repository
- *will* overwrite mythstream files below /usr/share/mythtv


More specific:
1) New or changed parsers are copied to:
      /usr[/local]/share/mythtv/mythstream/parsers/
   and mythstream will continue to use your old parsers in
      ~/.mythtv/mythstream/parsers
   until you choose to overwrite them.
     
2) Possible new streams illustrating new functionallity can be found in
   the streams.res stream repository that is included in this tarball.
   To load this repository:
     a) add the file /usr/share/mythtv/mythstream/streams.res as file storage 
        via the setup menu:
          mythfrontend setup > media settings > stream settings > storages.
     b) then select and load this storage via menu: 
          mythfrontend setup > media settings > stream settings > streams
     c) to return to your mythstream repository, just select and load the storage
        "mythstream".
     
        
INSTALLATION
------------
   See MPLAYER INSTALLATION below for information on playing RealMedia streams.

0. Install the runtime versions of wget, perl and the perl modules XML::Simple,
   XML::DOM, XML:XQL. Use the package manager of your distribution to get the perl 
   modules (like apt-get install libxml-simple-perl libxml-dom-perl libxml-xql-perl 
   for debian)
   OR
     download from CPAN (http://search.cpan.org/~grantm/XML-Simple-2.13/), unpack and do:
       perl Makefile.PL
       make
       make test
       make install
   OR
       shell> perl -MCPAN -e shell
       cpan> install XML::Simple
       ...
        
   If you use external harvester parsers not included in the tarball you might need
   additional PERL modules. Check the parser documentation or run mythfrontend from 
   the commandline to view PERL errors dumped to stdout.
   
1) check the PREFIX setting in settings.pro. If mythtv is installed in 
   /usr/share set PREFIX to /usr, for usr/local/share PREFIX should be 
   set to /usr/local.

2) Make sure you have Qt and X development packages. Check for qt-devel,
   xfree86-devel. On Debian Sarge: libqt3-mt-dev, libqt3-headers, libfreetype-dev,
   libfontconfig1, libpng12-dev, xlibs-dev, libx11-dev (see MythTV docs).

   In addition, you'll need fftw2 (not fftw3) packages. On most distributions 
   installing fftw devel or fftw2 devel packages will do. 
   On Suse you will have to compile fftw yourself because Suse provides double 
   precision fftw (dfftw) packages. You can download the fftw source from 
   http://www.fftw.org/download.html (sept 2004: version 2.1.5).

   NOTE: MythStream uses MythTV libraries. If you have a binary MythTV install,
   download the mythtv development package (Debian: libmyth-[version]-dev). When
   not available, download the MythTV source from www.mythtv.org, and make a
   symlink from the mythstream subdirectory:

   cd mythstream
   ln -s [path to mythtv source]/libs/libmyth mythtv

3) If you didn't compile Mythtv first, you probably have to set QTDIR. 
   QTDIR will be something like /usr/lib/qt-3.1 or /usr/lib/qt3,
   depending on your distribution. Check setting of QTDIR on command line with

      echo $QTDIR

   Configure QTDIR in $HOME/.bash_profile or set it on command line with

      QTDIR=/usr/lib/qt3; export QTDIR

   If you set QTDIR on command line you have to repeat that action every time
   you open a console. If QTDIR is not set properly, make will say it's not able
   to make ....mkspecs/default/qmake.conf

4) compile and install

   type 'qmake mythstream.pro' in the main directory to create the Makefile.

   type 'make' in the main directory to begin compiling

   type 'make install'.

   - libmythstream.so will go into /usr/[local/]lib/mythtv/plugins
   - data files will be put into the
     /usr/[local/]share/mythtv/mythstream directory
   - image files and ui file go to /usr/[local/]share/mythtv/themes/default

   Note: the [local/] part depends on the PREFIX in settings.pro
   
   Note: if you set QTDIR after running qmake you have to remove Makefile and
         mythstream/Makefile before running qmake again.   

5) This unofficial release needs manual configuration of mythtv files
   in the mythtv installation tree to let MythTv know the plugin exists:
   - set buttons of type STREAM in library.xml and media_settings.xml
   - define the STREAM button (stream.png) in theme.xml

     in library.xml 

        <button>
            <type>STREAM</type>
            <text>Internet Streams</text>
            <action>PLUGIN mythstream</action>
            <depends>mythstream</depends>
        </button>

     in media_settings.xml: 

        <button>
            <type>STREAM</type>
            <text>Stream settings</text>
            <action>CONFIGPLUGIN mythstream</action>
            <depends>mythstream</depends>
        </button>

     in themes/blue/theme.xml (blue theme example):

        <buttondef name="STREAM">
            <image>stream.png</image>
            <offset>60,30</offset>
        </buttondef>

     If you use a non-default theme, check out it theme xml file to add a MythStream
     image using the stream.png file. It can wait, MythStream will run without it.

     NOTE: if the "Internet Streams" menu entry doesn't appear (below the MythTV mainmenu
           "Media Library"-entry) check this:
     1) check for library.xml or media_settings.xml in your ~/.mythtv/ directory
     2) start mythfrontend from commandline and check for a "failed to load" message
        for mythstream. If mythstream failed to load, it might be compiled to the wrong
        (old) mythtv headers.
     3) check if the file libmythstream.so resides in the same directory as the other
        plugins. Problem can be solved by moving libmythstream.so in the same directory
        as it's more official friends.

        Issue 3 is a new one, and I get mixed results on different systems. Please
        drop me a mail at ericgies@kabelfoon.nl if you have this issue, thanks.

     
6) To configure streams through mythweb you can use the mythstreamweb module written
   by jK (jkei at gmx.net). This module is included as-is in the tarball and requires 
   a separate install step. 
   
   Call the install script from the mythstreamweb directory:
     cd mythstreamweb
     sh install.sh

   The script will ask for the mythweb location. The command locate program_detail.php 
   will return the correct directory.
     
     
7) If no stream items are displayed after first run, restart the plugin after deleting
   the streams table in the mythconverg database:
     shell> mysql mythconverg
     mysql> drop table streams;
   The next time mythstream is started, the file streams.res is loaded into the database.
   
   
OPTIONAL: VIDEO SCALING
------------------------
--> the file player.xml holds mplayer command line parameters. If you have a proper display
    driver installed, you might want to remove the -zoom parameter (software scaling):
      <item>
        <name>-zoom</name>
        <value></value>
      </item>

   
OPTIONAL: CHANGING THE (PODCAST) DEFAULT DOWNLOAD DIRECTORY
---------------------------------------------------------------------
    When a harvester script (podcast.pl or a custom script) adds a handler field
    with value STREAM_DL to a stream item, the stream item (probably a mp3 file)
    will be downloaded before play. This file is stored in the ~/.mythtv/downloads
    directory.

    If you want to store the downloaded files elsewhere (e.g. the mythmusic music
    directory), or if you want multiple users share the same download directory
    (when using streamtuned), change the downloads directory to a symlink pointing
    to the right location after installation.

    To store the downloaded files in the directory /var/downloads:
      - assign all users to a common group (e.g. group users)
      - create a "downloads"-directory and setgid to group users:
          cd /var
          mkdir downloads  (OR: mv $HOME/.mythtv/mythstream/downloads . )
          chgrp -R users downloads
          chmod -R 2775 downloads
      - symlink the new directory as SUBPATH/.mathtv/mythstream/downloads
          cd $HOME/.mythtv/mythstream
          rm -Rf downloads  ( don't try this at home :)
          ln -s /var/downloads .
    
      Note:
        1. upon selection of a item with STREAM_DL handler, wget will download the
           uri to the download dir.
        2. the downloading file will be renamed as [filename]_temp
        3. when download finishes the file will be renamed as filename
        4. the process that started wget is aware of the running download,
        5. other mythstream processes will regard the [filename]_temp as a
           failed download and will start a new download upon selection. What
           happens next is specified in the wget documentation (I guess).


MPLAYER INSTALLATION
---------------------------------------------------------------------
    --> display of icecast and shoutcast meta data (song title/artist)
        requires mplayer v1.0pre8
        
    The default MythStream stream repository lists several RealMedia
    stream url's (rtsp protocol or .rm, .ram files).

    MPlayer can play these streams, if RealMedia codecs are present and MPlayer
    was compiled with them. A binary MPlayer package usually doesn't include
    these codecs, but chances are MPlayer package WAS compiled with them.

    So if you can't play Realmedia streams and you have a binary MPlayer check
    wether MPlayer complains about missing codecs in /usr/local/lib/win32 or
    other paths. Run:

       mplayer rtsp://163.205.10.22:8080/broadcast/ksc1/redundant/nasatv.rm

    If MPlayer mentiones the path of the missing codecs, just create that path
    and copy the proper codecs to it. Download them from:

       http://www.mplayerhq.hu/DOCS/HTML/en/codecs.html#realvideo

    or install Realplayer for Linux and use these codecs.

    If MPlayer wasn't compiled with realmedia codecs go to MPlayer HQ, download
    the MPlayer source and the codecs mentioned above and compile.

    


