Configuring Streams

1. Configuring streams

Stream Items are objects with five fields:

Folder and name are visible in the MythStream browse window. The handler contains information about the way the stream url should be handled. For stream item configuration purposes, the handler field is empty (stream url is passed to the player) or it contains the name of a "parser" (the stream url or the data it points to is passed to a parser).

The url field points to the actual content (stream or file). It supports one or more <:name::value:> tags. These tags bring up a popup window used to edit the value (with the virtual keyboard if desired). The value is inserted in the url before calling player or parser. The tags can be used to generate dynamic queries, or ask for a result set number (often stream index sites return searches in multiple pages). Example from the demo storage:

http://www.dailymotion.com/rss/relevance/search/<:search term::funny:>/<:page::1:>

1.1 On the fly Stream Item configuration

Action EDITITEM (key "E") will open a dialog window showing the fields of the stream item under cursor. The fields are listed in the order shown above. To edit the fields use a keyboard or press "select" on the remote to bring up the virtual keyboard.

The "Update", "Add new" or "Delete" buttons in the dialog window work as expected when editing a stream item from a writable stream storage. If the stream item is readonly, an error is displayed.

If a dynamic stream item (provided by a parser) is edited, only the "Add new" button works: it can be used to store the item in the current stream storage.

1.2 Using the Stream configuration module

The stream items visible in MythStream can be managed in the stream configuration module (MythTV frontend setup menu). This module is mouse oriented - it has not been (re)designed to work well with a remote.

In the stream configuration module, first select the storage to edit in the dropdown box on the right. Press "Load storage" to actually load the storage contents in the module.

To change a stream item, click on it in the tree in the left pane. Edit the fields in the right pane and press "Update".

To remove a stream item, click on it in the tree in the left pane and press "Remove"

To create a stream item, click on the folder the item should be added to, fill the stream item fields and press "Add"

To move a stream item to another folder, click on it in the tree in the left pane. Type the name of an existing or new folder in the folder field and press "Update".

To overwrite the contents of a stream storage with the storage visible in the streams config module select the target storage in the dropdown box on the right and press "Overwrite storage".

1.3 Copy Stream Items to another storage

Use the MARK action (key M) to mark the stream items in a folder. Use the STOREMARKED action (key Y) to copy the marked stream items to another repository. If the target folder doesn't exist in the target storage, the folder is created.

1.4 Use external tools

Other ways to manage streams:


2. Using parsers

2.1 Available parsers

MythStream parses playlists and xml feeds through external PERL scripts.
For non-PERL parser support, see the alt_parsers directory

Normally, when you select a stream item, MythStream attempts to play the stream item's url (using mplayer by default). If this url fails to play, the harvester will start a download on that url (using a cache and if-modified header). The downloaded data is then "harvested" for stream information using a parser. The resulting stream items are displayed in MythStream's "harvester mode". The stream items may or may not display proper stream names, description or other information, depending on the used parser and data retrieved.

The parsers are PERL scripts located in the $HOME/.MythStream/parsers directory:

Some parsers are also available as executables: see the separate README in the alt_parser directory.

2.2 Using parsers: the stream item handler field

Enter the parser filename (without extension) in the "handler" field of the stream item to tell MythStream to use this parser for the stream item. If you leave the handler property empty, MythStream will start mplayer when selecting the stream item. When mplayer exits, 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.

If a parser is set the harvester retrieves data from the url and passes this data to the parser. If you want your parser to get the data itself, prefix the parser name in the handler field with an asterisk (*parsername). The harvester then skips the data retrieval and calls the parser directly, giving the stream url as parameter.

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 and other parsers can contain additional information provided by the xml feed, like embedded html. This information is displayed while in "info mode" (key I). If a stream item contains html or multiline text a separate text/html viewer can be started from 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>).

Mutistage parsers can be used to create interactive menu's. These parsers return encoded state in stream urls. When the user selects a stream item generated by a parser, the fake url with state information is returned to that parser, enabling it to determine the next action based on state and user selection. Most multistage parsers use more than one PERL script (to handle the selection of stream items resulting from the interaction) and therefore have their own directory.

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 set by the scripts. See creating parsers

2.3 Parser specific information

For examples see the demo storage (press 0 and 9 for the locally stored demo storage, press 0 and 8 for the most recent online version, press 0 and 0 to return to the default mythstream storage in MythTV's mythconverg database).

When the handler field contains a parsers with *-prefix, the url is ignored. Don't leave it empty though: URL's in a stream storage must be unique. Only one stream item with empty url field is allowed. Use bogus data for the other items with *parser handlers.

default.pl
MythStream will fallback to this parser when no parser is entered in the handler field. Do not set this parser explicitly unless you want to skip the player step (also skipping stream meta file handling).

icecast.pl
url: http://dir.ziph.org/yp.xml
handler: icecast

shoutcast.pl
url: <search url>
handler: shoutcast

<search url> is the url that shoutcast.com returns in the browser address bar after searching for station and or genre.

shoutcasttv.pl
handler: *shoutcast/shoutcasttv

Not in the demo, some links not working (for me). This feed looks like a discontinued experiment?
The shoutcasttv parser does not return all stream sources available in the Shoutcast TV feed. See the parser file for details.

podcast.pl
url: <podcast rss feed>
handler: podcast

rdfcast.pl
url: <podcast rss feed>
handler: rdfcast

rss.pl
url: <general rss feed>
handler: rss

apple.pl
url: <don't care as long unique in storage>
handler: *apple

omroep/*
Uitzendinggemist.nl is a portal providing content created by the Dutch public broadcasting associations.

Alle uitzendingen 
url: http://www.uitzendinggemist.nl 
handler: omroep/program_menu

Laatste uitzendingen
url: http://www.uitzendinggemist.nl 
handler: omroep/menu 

wwmp/*
WorldWideMediaProject playlist
url: <your Playlist URL>
handler: wwmp/wwmp_pls

<your playlist URL> is the playlist url available in your user account profile on the WorldWideMediaProject.com site.

WorldWideMediaProject interactive menu
handler: *wwmp/menu

shoutcast/*
Shoutcast Genres interactive menu
url: http://www.shoutcast.com
handler: *shoutcast/menu

bbc/robins_links
BBC radio broadcasts
url: <don't care as long unique in storage>
handler: *bbc/robins_links

tvlinks/*
Episode listing
url: <url to episode page>
handler: tvlinks/listing

<url to episode page> is the url of the episode page on tv-links.co.uk

Feed reader
url: <tvlinks.co.uk RSS feed>
handler: tvlinks/rss

The demo database doesn't contain a stream item for this parser. I wrote and use it myself, and I do believe that some copyright infringement increases the world happiness index - see the YouTube and DailyMotion parsers that are present in the demo. But to bring this content one click away from your screen you have to configure the stream item yourself.

youtube/*
YouTube RSS feed reader
url: <url to YouTube.com RSS feed>
handler: youtube/feed

dailymotion/*
DailyMotion Video RSS feed (direct play, use for playlists)
url: <url to DailyMotion.com RSS feed from search result>
handler: dailymotion/playall

DailyMotion Video RSS feed (download and/or play)
url: <url to DailyMotion.com RSS feed from search result>
handler: dailymotion/feed

For more information see comments in the parser files and the README files in some parser directories.


3. Finding streams

  1. Use a browser to access the stream, view the page source to discover the stream url
  2. Same, but run a sniffer while browsing
  3. Same, but use streamsniff (as root) on your PC or on your router to dump the stream url including stream metafile (if any) to stdout

4. Recording streams

4.1 Recording

MythStream is based on StreamTuned (see same webpage you got MythStream from). StreamTuned supports recording, MythStream does not - at least not in a very usable way. If you insist, you can try to record your stream using the information below. Not tested in a long time...

Simultaneous recordings are possible. Scheduled, running and finished recordings are listed in the dedicated folder "recordings". Every entry has an icon indicating it's current status. Recording only works when the plugin is running. And it often doesn't...

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

Replace the directory recordings by a symlink if you want to store the files elsewhere (warning: following code deletes all recordings):

cd $HOME/.mythtv/mythstream
cp -dpR recordings/* /whatever/path/to/whatever/directory/
rm -Rf recordings
ln -s /whatever/path/to/whatever/directory recordings

Note that if the stream 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. Use the "store stream" folder during stream play (use cursor left or right) to store the actual stream url and use that entry for recording.

Recordings can also manually started/stopped by the actions RECORD, STOPRECORD, STOPALLRECORD. There is no keymapping provided for these actions: configure keys in the MythTV setup menu "Edit Keys".

4.2 Schedule a recording

A recording is scheduled by placing a special formed entry in the folder "recordings".

The name of the entry must have the format:
REC[text] yyyymmdd hhmm HHMM [stream name]

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 syntax rules are not fool or hack proof, be nice. 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 GUI upon commit.

4.3 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.
  4. It is possible to change the stop-time of a running recoring


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. It still points to the file, but if you delete the stream entry, the target file will remain on disk.

4.4 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.