

STREAMTUNED v0.16 (MYTHSTREAM v0.16)
====================================

Written by : Eric Giesselbach 2003,2004
Home       : http://home.kabelfoon.nl/~moongies/streamtuned.html
Licence    : GNU GPL

MythStream is based on StreamTuned. This README is intended for both releases,
but while reading this README, bare in mind the following differences:

--> StreamTuned is a standalone application, MythStream is an unofficial plugin
    for MythTv (http://www.mythtv.org)
    
--> MythStream doesn't support recording. This is really a MythTv backend feature,
    therefore it is disabled in the frontend plugin.
    
--> This README assumes a local directory $HOME/.streamtuned. The local directory
    for mythstream is $HOME/.mythtv/mythstream.

--> StreamTuned uses streams.res as default stream repository, MythStream uses the
    table streams in the mythconverg database.

--> MythStream does not support the mplayer dump window



What is it
==========

StreamTuned is a stream player and recorder. It plays and records audio
and video streams using mplayer as backend. It also reads playlists and XML
feeds. Support for Icecast XML and Podcast RSS feeds is included, other
feeds can be supported by adding simple external scripts. Stream urls are
stored in a local file or a database, and can be made available through a
website or webservice for remote usage.


Details
=======

StreamTuned stores stream url's as stream items (combination of stream url, name, etc.)
in "repositories". Possible repositories are files, database tables, web services or
webpages. A default repository with sample stream items is included in the tarball and
activated on first run.

After installation, StreamTuned has two repositories available:
- default : a file repository streams.res with sample streams
- Ross Campbell's streams : some nice work sent in - thanks.
The repository from Ross is provided as a static page from my website. If you want
faster loading or want to add stream items to it, copy the repository to a local one.

Some items in the default repository refer to a playlist, webpage or xml feed. Examples
are the Icecast XML feed and the Podcast RSS feeds. If you select one of these items,
the contents of playlist or feed will be parsed and presented in the gui. The process of
parsing is called "harvesting". In case of XML/RSS, the parser script signals StreamTuned
how to handle the returned stream item or it's associated meta information (e.g. Podcast
file download instead of stream).

Read on to find out how to use StreamTuned to play streams, copy repositories, copy and paste
stream items between repositories and manage streams within a repository. For installing or
upgrading (repository conversion) see INSTALL.


CHANGES v0.12 --> v0.16
=======================
- podcast support
- playlist cache (to be nice to xml feeds)
- file download support (used by podcast)
- viewer for html/text data in xml feeds / playlists
- GUI: custom colors in settingsrc (streamtuned only), icons, item information display
- "copy and paste" stream items between repositories
- parsing of (icecast) xml and other playlists through external (custimizable) scripts
- workaround for mplayer hanging on .pls files without -playlist option
- improved parsing of mplayer (error) messages
- bug removal: tempfile blocking multiuser play, recovery from mplayer lockups, etc.
- support for static html stream storages (on webservers refusing POST requests)
- separate dump window showing mplayer stdout, allows for manual stream url start.
- multiple customizable CustomStreamEvents (mplayer output events) in player.xml


KEYBOARD USAGE
==============
Browse folders and streams    cursor keys
Start stream or harvester     [RETURN]
Stop stream                   [END]
Pause                         P
Start recording               R 
Stop recording                S 
Stop all recordings           Q 
Fullscreen toggle             F
Volume down                   [
Volume up                     ]
Mark a stream                 M
Store marked streams          Y
Show player dump              D 
Get item information          I   (view stream item properties, Podcast meta data)
Skip player forward           >   (if supported, e.g. Podcast files)
Skip player backward          <   (...)

Some functions can also be activated by mouse clicks on buttons.


GUI MODES
=========
StreamTuned has five different "modes":

- browse mode    : Browsing folders and stream items. Folders are listed on
                   the bottom of the display, items are listed from top to
                   bottom. The current folder and stream are highlighted.
- play mode      : Active during stream play. Stream details like name, codec,
                   buffer, stability are shown. The top right LED is green.
                   A Flashing LED means the player is buffering.
- harvester mode : Shown are URL fetch status or harvested URL's. The bottom
                   right LED is red. A flashing LED means the harvester is
                   receiving data (fetching URL's). URL's likely to be
                   streams are prefixed with ~.
- Action mode    : Several actions that require feedback present that feedback
                   using the streamtuned display. This mode always has "Cancel"
                   as last option.
- Info mode      : Displays (stream) item details. Most information is displayed
                   in the display prefixed with "I"-icons. Items "harvested" from
                   XML or other data may have embedded html or multiline text. This
                   content is presented as an entry with a dedicated icon. Selecting
                   this entry opens a separate viewer.


PARSING STREAM LISTS / ICECAST XML / PODCASTS
===============================================
StreamTuned parses playlists and xml feeds through external PERL scripts.

Normally, when you select an url, streamtuned attempts to play that url using mplayer. If
this url failes to play, the harvester will start a download on that url (using a cache and
if-modified header). The downloaded data is "harvested" for (stream) urls. If the data is
HTML, XML or some other plain text format containing url's, the result may be (depending on
the used parser) a list of stream items that is displayed in the streamtuned "harvester mode".

The parsers are PERL scripts located in the $HOME/.streamtuned/parsers directory:
- default.pl   (the default parser)
- icecast.pl (parsing icecast xml stream list)
- podcast.pl   (parsing podcast rss feeds)
- rdfcast.pl   (parsing podcasts using rdf format)
- example.pl   ("template"-script to use for building your own script)

Enter the parser filename (without extension) in the "handler" field of the stream item to tell
StreamTuned to use this parser for the stream item. If you leave the handler property empty,
streamtuned will start mplayer when selecting the stream item. When mplayer exists, the harvester
will start, using the default parser. If a parser is set, this parser will be invoked immediately
when selecting the stream item, skipping the mplayer step.

The icecast parser can parse the XML dump from http://dir.xiph.org/yp.xml. The podcast (and
rdfcast) parsers can parse podcast xml feeds. Stream items returned by these scripts can contain
additional information provided by the xml feed, like embedded html. This information is displayed
while in "info mode". If a stream item contains html or multiline text a separate text/html viewer
can be started while in info mode.

The harvester defaults to the "catch all" parser default.pl. This parser will detect every url,
but cannot detect relations between stream name and stream url other than the html hyperlink
(<a href=[stream url]>[stream name]</a>).

If you have a playlist that is not parsed properly by an existing script, just create a new one.
The existing scripts offer the information needed (if you are familiar with PERL or programming
in general). Mail the script if you want it included in the tarball (always appreciated, I have
to review it first though). Note the optional handler/viewer properties output by the scripts. The
list of possible values in this release is limited (STREAM_DL/inline,text,html) but will grow.


RECORDING
=========
Multiple (simultanious) recordings are supported. A recording can start
immediately, defaulting to one hour recording time, or be scheduled.
Scheduled, running and finished recordings are listed in the dedicated
folder "recordings". Every entry has an icon indicating it's current status.

By default, streams are recorded to files in the directory
 $HOME/.streamtuned/recordings

Replace the directory recordings by a symlink if you want to store the
files elsewhere (warning: following code deletes all recordings):
  cd $HOME/.streamtuned
  rm -Rf recordings
  ln -s /whatever/path/to/whatever/directory recordings


- record now:

Start a recording with R, or click the red recording button on the left.
If a stream is playing, that stream will be recorded. If no stream is
playing, the current browse entry is recorded.

Note that if the current browse entry is not a valid stream (i.e. isn't an
url mplayer will play) the harvester will not assist by "harvesting" the
url that failed to record. In this case, the recorder will suggest (message
in gui) starting the recording from a playing stream.


- schedule a recording:

A recording is scheduled by placing a special formed entry in the folder
"recordings". The easiest way to create such an entry is to browse to the
right stream and record a few seconds of it (press R, and press Q after the
stream started). Then edit the name of the new entry in the configuration
window. This name contains the scheduling information.

Details:
  The name of the entry will have the format:
    REC[text] yyyymmdd hhmm HHMM [stream name]
  To schedule just edit the start and stop date and time:
    yyyymmdd = start date
    hhmm     = start time
    HHMM     = stop time (if stop < start the recording ends the next day)
  Examples:
    REC0 20040314 1653 1753 Easy Belgium
    REC0 2004-03-14 16:53 17:53 Easy Belgium

  The parts [text] and [stream name] are used to make the entry unique and
    sensible, they do not affect scheduling.
  The "stream url" field contains the file to write the stream to. This
    target file will be played when playing the recording.
  The "stream description" field contains the URL to record.
  Changing target file name or stream url will not affect running
    recordings.

Errors in scheduling information are reported in the main window upon
commit. A succesful scheduled recording will be reported as scheduled or
rescheduled in the main window.


- removing and updating recordings:

The entries in the "recordings" folder affect files on harddisk in this way:
1. When a recording starts, the target file (in the "Stream url"-field) will
   be overwritten.
2. When recording fails, the target file will be deleted if it is empty
3. When a scheduled, running or finished recording is deleted, the target
   file will be deleted too.

The special meaning of a recording entry is related to the special
"recordings" folder. When a entry is moved out of the recordings folder,
the entry is treated as a normal stream entry.


- stopping recordings:

To stop all recordings press q, to stop a single recording browse to the
right recording in the recordings folder and press s.


- playing recordings:

To play a recording browse to it and press [RETURN]. Note that depending
on the stream format, mplayer can/cannot handle a growing stream file (that
is recorded at that moment). The player exists early if it can't. This will
not affect the recording.

Tip: use mencoder to transform the recorded stream to another (seekable)
     format after recording.


CONFIGURATION
=============
In the configuration module you can manage streams in a repository and
create / switch between repositories.

Managing streams : click on a stream on the left. The stream details are
                   presented on the right. Clicking "remove" removes the
                   stream, clicking "update" commits any editing. Note that
                   if you edited the folder name, an update moves the
                   stream entry to a new or existing folder.

Managing storages: Here you can create new storages or stream repositories.
                   See below.

Switching storage: Change the "connected storage" and then choose between
                   "load storage" or "overwrite storage". Use "M" and "Y"
                   copy and paste in browser mode to append items to a 
                   storage.

TIPS
====
- See INSTALL if you have problems playing (Realmedia) streams
- When harvesting a website, try to filter stream url's using
  "filter" to remove (suspected) non-stream url's from the list.
- You can override the default parser in the harvester, and use a perl script.
  see topic "parsing (XML) stream lists".
- Create a web repository for remote access to your stream list
- Replace /usr/share/streamtuned/s_picture.png to change background image
  (some background images in directory misc)
- The usage of mplayer is configured in player.xml, you can add
  custom command line parameters for mplayer in that file. See
  the first use section in INSTALL
 

BACKGROUND IMAGE
================
Background image of twin hills on Mars
  Courtesy NASA/JPL-Caltech
  http://www.jpl.nasa.gov/images/policy/index.cfm


CREATING A DATABASE REPOSITORY
==============================
1. Create database and table:

      mysql -u [login] -p
      create database [database name];
      exit;
      mysql [databasename] -u [login] -p < misc/streams.sql

2. Enter repository properties in StreamTuned configuration


CREATING A WEB REPOSITORY ("WEBSERVICE")
========================================
1. Copy misc/base.php and misc/streamtuned.php to a proper directory under
   the Apache document root.
2. Create a database repository
3. Edit base.php to configure access to the database
4. Change password in streamtuned.php
5. Enter repository properties in StreamTuned configuration

   -> php.ini must have global vars enabled.
   -> to test repository availability use a browser to open
      http://[path]/streamtuned.php?command=list&pass=[your password]

      
APPLICATION
===========
StreamTuned was written by Eric Giesselbach. The StreamTuned functionality
is also available as (unofficial) MythTV plugin, MythStream. MythStream
uses the StreamTuned libs. Both projects are protected by GNU GPL.

NOTES
=====
1. If you have problems playing a stream then start that stream directly with
   MPlayer (or check output using "D").

2. MPlayer output can be "grepped" and displayed in the GUI by defining
   properties and corresponding regular expressions in the file player.xml.
   If you want to display specific MPlayer output edit the player.xml file:
   - every MPlayer output line is treated as [label]:[value]
   - use item StreamCustomEventX with X in {0..9}

  
THANKS TO
=========
Raymond van den Houwen for testing






