
MythStream v0.18 INSTALL
==========================

More recent documentation can be found at:
  http://home.kabelfoon.nl/~moongies/howto/index.html
  
---------------------
   UPGRADERS INFO
---------------------

  CUSTOM PLAYER AND GUI SETTINGS
  ------------------------------
  If you changed player.xml or one of the stream-ui.xml files, copy them
  elsewhere before installing mythstream and run diff.
  
  PARSER UPGRADE
  --------------
  When the upgraded MythStream plugin loads for the first time:
  - new parsers are added to ~/.mythtv/mythstream/parsers;
  - existing parsers are OVERWRITTEN with the tarball versions
  - the file ~/.mythtv/mythstream/parserupdate0.18_done that
    prevents mythstream from updating parsers on next runs is
    created. So you can freely modify until the next upgrade.
  
  TARBALL STREAM STORAGE: NEW FEATURES DEMO
  -----------------------------------------
  Press 9 to open the stream database included in the tarball.
    For both Youtube as Dailymotion two parsers are added: one plays video's
     directly, the other one gives the option to download or play directly.
     When using the last parser, stream items can be marked ("key M") to
     construct a playlist (mark items and start the top one)
    The stream items in the "Interaction" folder use muti-stage parsers to
    query sites like worldwidemediaproject.com, shoutcast.com and wwitv.com
    by genre, country etc. Not every parser is used in the demo database,
    check the parser directory for more.
    
  Press 0 to return to the default (your) mythstream database
  
  Press 1..8 to open configured storages (configured in setup module)

---------------------
 END UPGRADERS INFO
---------------------



INSTALLATION (outdated, e.g. doesn't mention espeak, check link on top)
------------
   See MPLAYER INSTALLATION below for information on playing RealMedia streams.
   If you want non-PERL parser support, check the README in the alt_parsers directory.

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

SVN NOTE:

   I didn't test svn yet (oct 13). Tim Nichols suggests the following change to make
   mythstream to compile with svn (did not test that either, please report problems):

     do not use:
        ln -s [path to mythtv source]/libs/libmyth mythtv
     but use:
        ln -s [path to mythtv source]/libs/lib* .
     
     change (main.cpp):
        #include <mythtv/libmythui/myththemedmenu.h>
     to:
        #include <mythtv/libmythui/myththemedmenu.h>

     and change (main.cpp):
        gContext->GetMainWindow()->GetMainStack( )
     to:
        GetMythMainWindow()->GetMainStack()
      
3) If you didn't compile Mythtv first, you may have to set QTDIR.
   QTDIR will be something like /usr/lib/qt-3.1 or /usr/lib/qt3,
   depending on your distribution. Check 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 the 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[-wide]

   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. Easy way: make distclean.

5) Since MythTV v0.20, MythStream menu entries are included in MythTV's menu xml files.

   Some themes still need manual editing though:
   
   --> define the STREAM button in your theme's theme.xml (provides icon in menu entries)

     example: themes/blue/theme.xml
     
        <buttondef name="STREAM">
            <image>stream.png</image>
            <offset>60,30</offset>
        </buttondef>

     example: themes/MythCenter[-wide]/theme.xml
     
        <buttondef name="STREAM">
          <image>ui/button_off.png</image>
          <watermarkimage>watermark/stream.png</watermarkimage>
          <offset>0,0</offset>
        </buttondef>

 
     NOTE: the "Internet Streams" menu entry can be found behind the "Media Library" menu entry.
           if it doesn't appear:
     1) check for library.xml or media_settings.xml in your ~/.mythtv/ directory, remove
        them.
     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) There are three ways to configure streams:
   - use mythstream setup in mythfrontend
   - install streamtuned on your desktop and link it to your mythstream repository
   - use mythweb

   The last one requires 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. See the
   README in the mythstreamweb directory.
   
   
7) If no stream items are displayed after first install and 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 /usr/share/mythtv/mythstream/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 this (enables 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 version >= v1.0pre8
    --> Playing Flash video (Youtube, etc.) directly requires mplayer
        svn > 19 aug 2007
        
    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 the MPlayer package WAS compiled for 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 a rstp stream like:

       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

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

    


