Configuring Streams
1. Configuring streams
Stream Items are objects with five fields:
- folder
- name
- url
- description
- handler
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:
- Use a editor to edit a file storage
- Use MySQL client or another database tool to edit a database storage
- Use StreamTuned on another PC to manage all types of storages
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:
- default.pl (the default parser)
- icecast.pl (parsing icecast xml stream list)
- shoutcast.pl (parsing shoutcast stream list, by R. de Vos)
- podcast.pl (parsing podcast rss feeds)
- rdfcast.pl (parsing podcasts using rdf format)
- rss.pl (general rss parser)
- apple.pl (parsing iTunes movie trailers, by Michael Knoll)
- example.pl ("template"-script to use for building your own script)
- omroep/* (interactive menu for uitzendinggemist.nl (Dutch))
- wwmp/* (interactive menu for worldwidemediaproject.com)
- shoutcast/* (interactive menu for www.shoutcast.com)
- bbc/robins_links (bbc radio)
- shoutcasttv.pl (shoutcast TV channels)
- tvlinks/* (tvlinks parser)
- youtube/* (youtube rss feed reader)
- dailymotion/* (dailymotion rss feed reader)
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.
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.
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
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
- Use a browser to access the stream, view the page source to discover the stream url
- Same, but run a sniffer while browsing
- 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:
- When a recording starts, the target file (in the "Stream url"-field) will be overwritten.
- When recording fails, the target file will be deleted if it is empty
- When a scheduled, running or finished recording is deleted, the target file will be deleted too.
- 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.