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

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")

Copy misc/base.php and misc/streamtuned.php to a proper directory under the Apache document root.
Create a database repository
Edit base.php to configure access to the database
Change password in streamtuned.php
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

If you have problems playing a stream then start that stream directly with MPlayer (or check output using "D").
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