
MythStream v0.16_5 INSTALL
=========================

UPGRADE TIPS
------------
1) If you customized a previous version of MythStream by replacing some
   images in the target directory, don't forget to backup them elsewhere.
2) Old (<0.16) repositories won't load without running conversion scripts
   on them first (see Installation step 7).
3) Examples of stream items that use the new parsers (podcasts, shoutcast, 
   apple iTunes) 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:
          setup > media settings > stream settings > storages. 
     b) then select and load this storage via menu: 
          setup > media settings > stream settings > streams
     c) to return to the 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 (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 main 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: 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>Play 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 (for the default theme):

        <buttondef name="STREAM">
            <image>stream.png</image>
            <offset>50,40</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.
     
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) ONLY IF YOU UPDATED from MythStream version < 0.16:

   Use the xxx_convert_to_v0.16.yyy scripts in the misc directory to convert your old
   database and file stream repositories (backup first):
     cd misc
     perl file_convert_to_v0.16.pl /home/myhomedir/.mythtv/mythstream/streams.res
     mysql -u root mythconverg < db_convert_to_v0.16.sql
     
?) 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
---------------------------------------------------------------------
    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.

    


