<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="homepage">

	<info>
	<link type="guide" xref="index#functions"/>
	<desc>Start a web browser for a station.</desc>
	<link type="guide" xref="streams#actions"/>
	</info>

	<title>Radio homepages</title>

	<p>Most radio stations are listed with a homepage URL. Use the <gui>house</gui> symbol in the
	toolbar or <guiseq><gui>right click</gui> <gui>homepage</gui></guiseq> to open it in a web browser.</p>

        <p>Some homepage links are guessed, because for example Shoutcast doesn't list them anymore.
	And if you play a station without homepage URL, it automatically gets googled (but will not
	be displayed until you reselect the category.)
        </p>

	<section>
	<title>Channel service</title>
	<p>You can also open channel homepages. Either from the <gui>Channel</gui> menu, or via
	double clicking the channel tab.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="playing">

	<info>
	<link type="guide" xref="index#browsing"/>
	<desc>Double click a station to start it in your audio player.</desc>
	<link type="guide" xref="streams#actions"/>
	</info>

	<title>Playing</title>

	<p>Simply double click a station to start it with your audio player.</p>

        <p>In streamtuner2 you can configure different audio players for different audio
        formats. In the 'Apps' section of the settings dialog, there is one application associated
        with each audio file (MIME) type. Per default this is audacious, but you can certainly use
        any other application.</p>

        <note><p>Note however, that some audio players will start twice and won't
        allow easy station switching. In these circumstance it might be sensible to write
        a wrapper script, or configure special commandline arguments to your favoured audio
        player.</p></note>

        <p>It's also possible to save a station entry as .m3u or .pls file, and load this manually
        in your player. You might even want to collect such .m3u files for archival / backup
        purposes.</p>


</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="recording">

<info>
	<link type="guide" xref="streams#actions"/>
	<link type="guide" xref="configuration#apps"/>
	<link type="guide" xref="index#functions"/>
	<desc>Save radio songs as MP3 files via streamripper.</desc>
</info>

	<title>Recording</title>

	<p>Most stations that stream MP3 or OGG music can be recorded. This is accomplished by
        the commandline tool "streamripper". If you select a station a press the [record] button,
        a console window should appear. Within that streamripper outputs its current activity.</p>

        <p>Per default recorded streams are written into the current directory. Often this is your
        home directory. And streamripper automatically creates a directory with the recorded
        radio station title as name. Within that directory the individual music titles are split
        into separate .mp3 files.</p>

        <p>You can influence all these behaviours with -arguments to the streamripper program.
        Please refer to the manpage of streamripper. The options are too various to list here.
        You can set default arguments (e.g. another default save directory) in the 'Apps' section of
        the streamtuner2 configuration dialog.</p>


</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="saving">

<info>
	<link type="guide" xref="index#functions"/>
	<link type="guide" xref="streams#actions"/>
	<desc>Export a station entry as .m3u/.pls file.</desc>
</info>

	<title>Saving</title>

	<p>You can export the currently selected stream using <guiseq><gui>Station</gui> <gui>Save</gui></guiseq>. A file
	dialog opens, where you can adapt the title. The extension of the filename decides on
	the saved link format. Per default a .m3u file is created, because most audio players
	understand this format.</p>
	<p> But you can also save in .pls
	or .xspf or .asx or .smil format. Note that the lower right dropdown
	has no effect, you must edit the filename field.</p>


</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="bookmarks">

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
	<link type="guide" xref="streams#actions"/>
        <desc>Collect favourites via bookmark function, entry editing and deleting.</desc>
</info>

	<title>Bookmarks</title>

	<p>It's easy to lose the overview when you browse through the various channel tabs, genres
        and internet radio stations. Therefore streamtuner2 allows to create bookmarks. This way
        you can collect favoured streams in a single place.</p>

        <p>Just right click a station you want to bookmark, and choose bookmark in the context
        menu. Alternatively you can use the Streams entry in the application menu. Once bookmarked
        you can see the station entry in the (!) "bookmarks" tab, under "favourite". That's where
        they all go.</p>

	<section id="editing">
	<title>Editing</title>
        <p>Entries can be removed from the bookmark list again. Use the edit menu for that.</p>

	<p>Bookmarked stations are shown with a star in all other channel tabs. If you delete the
        entry there, it won't remove it from the real bookmarks list.</p>
	</section>

	<section id="other">
	<title>Subcategories</title>
	<p>The bookmarks tab can display other categories besides "favourite". For example the
	search feature creates a "search", while the "timer" and "links" plugins also display
	lists here.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="internet_radio_org_uk">

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
	<link type="guide" xref="configuration#plugins"/>
        <desc>Large radio directory from the UK.</desc>
</info>

	<title>Internet-Radio.org.uk</title>

	<p>I-R.org.uk is a good alternative to Shoutcast. It also lacks channel homepage in most
	cases, but is a likewise encyclopedical directory. Genres are similiar to Shoutcast.</p>

	<note><p>Note that this plugin uses its own setting for how many links to retrieve. Instead
	of stream numbers, it only counts pages. This is a lazyness related bug.</p></note>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="jamendo">

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <desc>Creative Commons music and artist hub.</desc>
</info>

	<title>Jamendo</title>

	<p>Jamendo is a Creative Comments licensing oriented music distributor. It hosts audio
	files for individual musicians and artists. Tracks and albums can thus be downloaded
	free of charge. Yeah, imagine that.</p>

        <p>The streamtuner2 plugin for Jamendo is pretty limited at the moment. It just provides
	a quick overview over top artists and most listened albums from each genre. To browse
	the whole collections, better go to the Jamendo homepage or use Rhythmbox.</p>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="myoggradio">

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
	<link type="guide" xref="configuration#plugins"/>
        <desc>Open source stream directory.</desc>
</info>

	<title>MyOggRadio</title>

	<p><link href="http://ehm.homelinux.org/MyOggRadio/">MyOggRadio</link> is an open
        source internet radio directory project. Since it provides its station list as
	JSON it is very well supported.</p>

        <p>Because the directory is currently still rather small, streamtuner2 provides the
	option to share radion station links. Use the <guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Share...</gui></guiseq>
	menu entry to upload the currently selected radio (from your favourite bookmarks).</p>

        <p>The personal section is empty, unless you specify an user account in the settings
	and actually bookmarks stations on the MyOggRadio web site. Shared entries are not
	automatically in the MOR favorite list.</p>


<terms>
  <title>Channel options.</title>
  <item>
    <title><code>Login settings</code></title>
    <p>If you want to upload station infos to MyOggRadio, you need an account there. Registration
    is free and doesn't require personal information nor email address. Specify username and
    password separated with a : colon in this field.</p>
  </item>
  <item>
    <title><code>stream URL format</code></title>
    <p>When uploading stations, the streaming URL can be converted into RAW format. You
    can however leave it as .PLS link file.</p>
  </item>
</terms>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="shoutcast">

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
	<link type="guide" xref="configuration#plugins"/>
        <desc>One of the bigger radio station lists.</desc>
</info>

	<title>Shoutcast</title>

	<p>SHOUTcast is the name of a MP3 streaming server software. It automatically collects all
	station lists on shoutcast.com.
        </p>

        <list>
		<item><p>Station entries usually provide current playing information.</p></item>
		<item><p>Stream links are plain PLS files.</p></item>
		<item><p>Genres are subcategorized, so the main groups in the category
		list must often be expanded to see the interesting entries.</p></item>
        </list>


<terms>
  <title>There are a few plugin options for this channel.</title>
  <item>
    <title><code>PyQuery parsing</code></title>
    <p>Uses an XML parser to extract station data from within HTML &lt;tags&gt; of the shoutcast.com site. This is
    slower, but often more reliable than regular expressions, which look for plain text markers.</p>
  </item>
  <item>
    <title><code>debug output</code></title>
    <p>Prints verbose messages to the console. This option is used while developing extensions for Streamtuner2.</p>
  </item>
</terms>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="xiph">

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
	<link type="guide" xref="configuration#plugins"/>
        <desc>ICEcast radio directory.</desc>
</info>

	<title>Xiph.org</title>

	<p>Xiph.org is a non-profit organization, which develops and promotes the OGG audio format.
        It also hosts a list of ICEcast streaming stations (ICEcast is the non-commercial pendant
        to the SHOUTcast server.)</p>

        <p>This channel is especially easy to read by Streamtuner2, because the source data is already
        provided as &lt;XML&gt; file. However, it lacks some essential informaitons like station
        homepages and listener numbers.</p>

        <p>Xiph also uses the .xspf format, instead of .pls stream links</p>


<terms>
  <title>Channel options.</title>
  <item>
    <title><code>Filter by minimum bitrate</code></title>
    <p>The bitrate of an audio stream determines the music quality. Many Xiph streams have simple
    and low quality microphone sources. To filter these out, and only leave high quality music
    stations, you can therefore set this option. OGG starts to sound good with 128 kbit/s (whereas
    MP3 often needs 192 at least).</p>
  </item>
</terms>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="channels">

	<info>
	<link type="guide" xref="index#browsing"/>
	<desc>Switching through the channel tabs, different radio directoriy services.</desc>
	</info>

	<title>Channels</title>

	<p>The tabs in the main window represent the music directory channels. Each lists
        categories and streams from a specific radio directory.</p>

	<media type="image" mime="image/png" src="img/channels.png">Tabs</media>

        <p>If you first select a channel tab, the categories should appear or be loading.
        Otherwise:</p>

	<steps>
		<item><p>Select a channel tab</p></item>
		<item><p>Choose <guiseq><gui>Channel</gui> <gui>Reload categories...</gui></guiseq></p></item>
		<item><p>Pick a category/genre from the overview, left.</p></item>
	</steps>

	<p>Individual channels provide different music/radio information. The table
        views are however identical in each tab. You could modify the <code>datamap[]</code>
        in the plugin files, if you want to adapt this.</p>

	<section id="list">
		<title>Available channels</title>
	</section>


	<section id="homepage">
	<title>Channel service homepage</title>
	<p>You can dobule click the channel tab to view the website of a directory services.
	Alternatively there is an entry in the <gui>Channel</gui> menu.</p>
	</section>

	<section id="homepage">
	<title>Channel menu options</title>
	<terms>
		<item>
			<title>Homepage of directory service</title>
			<p>Opens a webbrowser with the current channels website.</p>
		</item>
		<item>
			<title>Reload</title>
			<p>Updates the current category and displays fresh station lists.</p>
		</item>
		<item>
			<title>Update favicons...</title>
			<p>Starts assembling favicons for the current list of stations in the background.
			To actually display the freshly loaded favicons, reselect the current category.</p>
		</item>
		<item>
			<title>Reload category tree</title>
			<p>Updates the genre list in the left category pane.
			For most channels the category list is already complete, but it might
			change over time. So this option often only is used for initializing streamtuner2
			channels when the list is empty.</p>
		</item>
	</terms>
	<p>The channel menu also contains a list of available channels. Select an entry to switch
	into that tab.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="cli">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Console interface, exporting data.</desc>
</info>

	<title>CLI (command line interface)</title>

	<p>Streamtuner2 is a graphical tool. But it also has a limited commandline interface,
	which can be used to query station information. This is useful for interfacing with
	other applications.</p>

        <p>Open a terminal and call <code>streamtuner2 help</code> to get an overview over
	available commands.</p>


        <terms>
          <title>Examples</title>
          <item>
            <title><code>streamtuner2 play "station"</code></title>
            <p>This command looks through all channel plugins, and finds a station containing the
	    mentioned title. In the shell you must put the station title in quotes, if it contains
	    e.g. spaces. You can optionally specify a channelname before the station title.</p>
          </item>
          <item>
            <title><code>streamtuner2 url [channel] "station"</code></title>
            <p>Just looks up the streaming URL for a given station. If no channel name is given,
		ST2 searches through all available channel plugins again.</p>
          </item>
          <item>
            <title><code>streamtuner2 stream shoutcast "station"</code></title>
            <p>Prints available station data as JSON</p>
          </item>
          <item>
            <title><code>streamtuner2 category internet_radio_org_uk "Pop"</code></title>
            <p>Loads fresh data from the specified channel service, and prints out JSON data for
		the whole category. Note that the category name must have the excact case.</p>
          </item>
          <item>
            <title><code>streamtuner2 categories channel</code></title>
            <p>Fetches the current list of available categories/genres for a channel service.</p>
          </item>
        </terms>

	<p>Specifying a channel name is often optional. If you add one, it should be all-lowercase.
	You can also give a list, like "shoutcast,xiph" which would be searched then.</p>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="config_apps">

<info>
	<link type="guide" xref="configuration#apps"/>
	<desc>Common applications to use as players.</desc>
</info>

	<title>Audio players</title>

	<p>On BSD/Linux systems there are a plethora of audio players. In streamtuner2 you can
	configure most of them as target application. Mostly it makes sense to use a single
	application for all audio formats. But at least the */* media type should be handled
	by a generic player, like vlc.</p>

	<table shade="rows" rules="rows cols">
		<tr><td>Audacious</td><td>audacious %m3u</td><td>audio</td></tr>
		<tr><td>XMMS2</td><td>xmms2 %m3u</td><td>audio</td></tr>
		<tr><td>Amarok</td><td>amarok -l %pls</td><td>audio</td></tr>
		<tr><td>Exaile</td><td>exaile %m3u</td><td>audio</td></tr>
		<tr><td>Amarok</td><td>amarok -l %pls</td><td>audio</td></tr>
		<tr><td>mplayer</td><td>mplayer %srv</td><td>console</td></tr>
		<tr><td>VLC</td><td>vlc %u</td><td>video/*</td></tr>
		<tr><td>Totem</td><td>totem %u</td><td>video/*</td></tr>
		<tr><td>Media Player</td><td>mplayer2.exe %pls</td><td>Win32</td></tr>
	</table>

	<p>Some audio players open a second instance when you actually want to switch radios.
	In this case it's a common workaround to write <code>pkill vlc ; vlc %u</code> instead.
	This ends the previous player and starts it anew.</p>

	<p>Some applications, like Rhythmbox or Banshee, are pure GUI applications and cannot
	be invoked with a play URL by other apps. This makes them unsuitable for use with
	streamtuner2.</p>

	<section id="abbr">
	<title>URL placeholders</title>
	<p>Any listed application can be invoked with a different kind of URL or filename.be invoked with a play URL by other apps.
	Which to use often depends on the application.</p>
	<table shade="rows" rules="rows cols">
		<tr><td>Placeholder</td><td>Alternatives</td><td>URL/Filename type</td></tr>
		<tr><td>%m3u</td><td>%f %g %m</td><td>Provides a local .m3u file for the streaming station</td></tr>
		<tr><td>%pls</td><td>%url %u %r</td><td>Either a remote .pls resource, or a local .pls file (if converted)</td></tr>
		<tr><td>%srv</td><td>%d %s</td><td>Direct link to first streaming address, e.g. http://72.5.9.33:7500</td></tr>
	</table>
	<p>You sould preferrably use the long forms. Most audio players like %m3u most, while
	streamripper needs %srv for recording.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="configuration">

<info>
	<link type="guide" xref="index#configuration"/>
        <desc><key>F12</key> brings up the options window with the Player, Display, System and Plugin sections.</desc>
</info>

	<title>Settings dialog</title>

	<p>There are many options in streamtuner2. You can find the settings dialog in the edit menu,
        preferences (last entry).</p>

        <terms>
          <title>It is separated into four main areas.</title>
          <item>
            <title>Player</title>
            <p>Lists audio formats and the applications which shall be used for playing.</p>
          </item>
          <item>
            <title>Display</title>
            <p>Influences the display of all stream/station lists.</p>
          </item>
          <item>
            <title>System</title>
            <p>Filesystem and environment settings. Boring.</p>
          </item>
          <item>
            <title>Channel Plugins</title>
            <p>Every channel tab can have specific options. These are configured here. Also you can disable channels you don't need.</p>
          </item>
        </terms>


	<section id="apps">
		<title>Player application settings</title>
		<p>MIME types are elaborate identifiers for file types. audio/mp3 for example represents MP3 files, and audio/ogg
		means just OGG.</p>
		<p>The text entry fields can hold the application name of an audio player. Often the application name
		is just a lower case version of the program title, but you might have to look it up.</p>
		<p>Behind the application program name is a placeholder. If the audio player is invoked, this placeholder
		gets replaces with an URL (a http://..-Link) of the selected radio stream.</p>
		<p>It's introduced by percent sign, and followed by letters. %m3u for example generates a .m3u file. Most
		audio players understand that. Otherwise try %pls, which might even be faster because streamtuner2 doesn't
		have to download and preprocess it. %srv instead gives a direct stream link.</p>
		<p>The entry for */* is a catch-all. If the audio format of a radio station isn't know, this application
		gets called.</p>
		<p><title>Recording</title></p>
		<p>The last entry in the 'Apps' section specifies streamripper. It is used for recording stations. You
		might want to add some commandline -arguments here.</p>
	</section>


	<section id="gui">
		<title>Display/GUI options</title>
		<p>Most options here a self-explanatory. The options for the favicons define if station entries should
		show little icons. Not all stations have one, so you might as well turn this off to conserve a little
		memory.</p>
		<p>The number of stations setting is not honored by all channel plugins. Often it's not possible to
		load more or fewer station entries. Some plugins have own settings (in the 'Plugins' section) even.
		For the major plugins this however limits how much scroll text appears in the stream lists.</p>
		<p>"Retain deleted stations" keeps old entries, when you reload a category/genre. Shoutcast often
		forgets stations or throws them out. If you keep this option enabled, these entries are kept in
		streamtuner2. Browse down in the stations list to still see them.</p>
		<p>It's possible to select a Gtk+ theme. But not all themes work with all Gtk display engines, and
		not all themes work with streamtuner2. You just have to try it.</p>
		<p>Remembering window states makes streamtuner2 not forget which channel and category was last
		selected. You can however disable this option, and instead manually save the window states/layout
		in the edit menu, if you want.</p>
	</section>
	

	<section id="system">
		<title>System info</title>
		<p>There are just a few options here, and some are hard-wired. Usually you don't want to change them.</p>
		<p>Setting another temporary directory might be useful, if you want to keep the temporary .m3u cache
		files. They are created whenever you hit play. For archival or speed-up porposes you might want to keep
		them elsewhere. They don't take a lot of space.</p>
	</section>

	<section id="plugins">
		<title>Plugin and Channel settings</title>
		<p>Each channel plugin can bring its own list of configuration settings. These are collected here.</p>
		<p>The heading for each plugin is actually a button, which allows disabling the plugin. Alas the state
		cannot be easily discerned with all themes.</p>
		<p>If you want to find out more about the short option descriptions (most settings are checkboxes),
		please have a look into the channels directory /usr/share/streamtuner2/channels/ and corresponding
		*.py files. These are readable, and sometimes contain more information.</p>
	</section>
	
	
	
</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="extending">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Writing your own channel plugins.</desc>
</info>

	<title>Extension Howto</title>

	<p>Streamtuner2 is written in Python, a rather easy programming language. And it's also rather simple
	to write a new channel plugin.</p>

	<p>The basic layout of every channel plugin is as follows:</p>

	<p><code type="text/python">

from channels import *

class myplugin (ChannelPlugin):

    title = "MyNewChannel"
    module = "myplugin"
    homepage = "http://www.mymusicstation.com/"
    categories = []



    def update_categories(self):
    
        self.categories = []



    def update_streams(self, cat, force=0):

        entries = []

        # ...
        # get it from somewhere
        # ...        

        return entries
        
	</code></p>

	<p>There are some self-explanatory description fields, and two important methods. Sometimes you
        don't need categories even. The update_streams() function often downloads a website, parses it
	with regular expressions or PyQuery / DOM methods, and packs into into a result list.</p>	

	<p>Here entries is a list of dictionaries, with standardized entry names like "title" and "playing"
	for the description, and "homepage" for a browsable link, and most importantly "url" for the
	actual streaming link. Often you want to add a "genre" and "format" and "bitrate" info. But this depends
	on your plugins data source, really.</p>
	
	
</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="topic"
	id="global_key">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Global keyboard shortcut for radio switching.</desc>
</info>

	<title>Global_key</title>

	<p>Using the global_key extension you can define a keyboard shortcut for switching within
	a list of favourite radio stations. Per default it uses your bookmarks list, but it can be
	configured to alternate in any other channel.</p>

	<p>This is useful if you don't want to keep the streamtuner2 window in the foreground
	all the time, but still want to switch radios easily.</p>

	<p>Go into settings <key>F12</key> for plugins to define a keyboard shortcut:</p>

	<table shade="rows" rules="rows cols">
		<tr><td>keyspec:</td><td>corresponds to:</td></tr>
		<tr><td>F9</td><td>Responds to only <key>F9</key>. (too generic)</td></tr>
		<tr><td>&lt;Meta&gt;R</td><td>often the 'Windows'-key and R</td></tr>
		<tr><td>&lt;Ctrl&gt;N</td><td>Control and <key>N</key></td></tr>
		<tr><td>&lt;Shift&gt;F1</td><td>Shift and F1</td></tr>
		<tr><td>&lt;Alt&gt;SPACE</td><td>Use Alt and <key>Space</key>. (too generic)</td></tr>
		<tr><td>XF86Forward</td><td>Uses a "forward" function key. (default)</td></tr>
	</table>

	<p>To define another channel as source, enter its module name in the according field. Also
	add a category separated by : colon here.</p>

	<note><p>If the configured keyboard shortcut conflicts with another application,
	it won't work. And if you choose it too generic, you won't be able to type longer
	documents. Also found out: key names are case sensitive.</p></note>
</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="glossary">

<info>
	<link type="guide" xref="index#advanced"/>
	<desc>Technical and streamtuner2 specific terminology and jargon.</desc>
</info>

	<title>Glossary</title>



	<terms>

	  <item>
	    <title>Channel</title>
	    <p>Each tab in the main window is a "channel". It represents one
   	    music directory service.</p>
	  </item>

	  <item>
	    <title>Stream</title>
	    <p>"stream" is a technical term which means continuosly flowing
	    data.  MP3 radio music for example is streamed, because it's not
	    just a time-limited audio file, but unending (unless you stop
	    the player or paying your ISP).</p>
	    <p>In streamtuner2 we also use the terms "stream" and radio "station" interchangably.</p>
	  </item>

	  <item>
	    <title>Genre</title>
	    <p>Music genres are represented as "categories" in the left
	    pane.  Every channel groups its music stations into some
	    structure.</p>
	  </item>

	  <item>
	    <title>URL</title>
	    <p>URL stands for "Uniform Resource Locator" and simply means
	    hyperlinks and web addresses like http://www.example.org/. 
	    There is also the hipster term "URI", which is technically more
	    general (but superseeded by "IRI" and "IRL" anyway).  In
	    streamtuner2 the audio streaming link often is an URL, as is the
	    radio station homepage of course.</p>
	  </item>

	  <item>
	    <title>Radio</title>
	    <p>Plays music. Sometimes interrupted by advertisements.
   	    </p>
	  </item>

	  <item>
	    <title>Favicons</title>
	    <p>Favicons are small symbols for websites. Every website has one.
	    Or should have. As it makes it easier to associate content with
	    homepage addresses. (ST2 downloads favicons either per menu command
	    or automatically for the current station once you hit play.)
   	    </p>
	  </item>

	  <item>
	    <title>Cache</title>
	    <p>Radio lists are kept in "cache" files for efficiency reasons.
	    To not redownload stream information on every category or channel
	    flip, streamtuner2 saves this data. This avoids time consuming
	    server requests.
   	    </p>
	  </item>

	  <item>
	    <title>Python</title>
	    <p>Python is a programming language. It provides extensive constructs and
	    many functions, yet is easy to learn. See python.org and Google.</p>
	  </item>

	  <item>
	    <title>MP3</title>
	    <p>MP3 (MPEG Layer 3) is an audio file format, part of the wider MPEG (Motion Picture
	    Expert Group) video format. It's the most widespread format in use today,
	    however doesn't provide the highest audio quality..</p>
	  </item>

	  <item>
	    <title>OGG Vorbis</title>
	    <p>OGG is a multimedia file format. Vorbis is an audio compression format.
	    OGG Vorbis was developed as alternative to MP3. It's often of higher
	    quality at lower file sizes, and isn't encumbered by US software patents.</p>
	  </item>

	  <item>
	    <title>MIME</title>
	    <p>For classification of web and email content, two-factor descriptions like
	    "audio/ogg" are advised. These are called Multipurpose Internet Mail Extension
            types, and are used on the web in lieu of file extensions (which URL resources don't have).
            Note that ST2 uses the MP3 type wrong; it's officially audio/mpeg, and not audio/mp3 as shown in the settings window.</p>
	  </item>

	  <item>
	    <title>Bitrate</title>
	    <p>Audio streams are compressed with exactness loss. This can be heard
	    at lower "bitrates". For MP3 files any music with less than 100 kbit/s
	    starts to hiss, while OGG Vorbis still sounds okay at a datarate of
	    for example 64 kbit/s. So while bitrate basically means file size per duration,
	    it's commonly used as quality indicator.</p>
	  </item>

	</terms>

	<section id="filetypes">
            <title>Filetypes</title>

            <p>Besides audio formats MP3 and OGG, there are also station/streaming link files.
            These are often downloaded from the directory servers, before your music player gets activated.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="json">

<info>
	<link type="guide" xref="glossary#filetypes"/>
        <desc>JavaScript Object Notation is a common data exchange format.</desc>
</info>

	<title>JSON files</title>

	<p>JSON is a data representation format derived from Javascript (the browser embedded
        programming language for websites). Streamtuner2 uses it to store it's configuration
        and radio station data files.</p>
	<p>The MIME type of these files is application/json and they often look like: </p>

<p><code>
[
  {
    "title": "Station title..",
    "url": "http://1.2.3.4:8000/",
    "homepage": "http://radio.org/",
  },
  { "title": "second" }
]
</code></p>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="m3u">

<info>
	<link type="guide" xref="glossary#filetypes"/>
        <desc>MP3-URL playlist file.</desc>
</info>

	<title>.M3U files</title>

	<p>M3U files also contain playlists, like .pls files. But they are often used by locally installed audio players.</p>
	<p>The MIME type of these files is audio/x-mpegurl and they often look like: </p>

<p><code>
#M3U
http://123.45.67.189:8222/
http://123.45.67.222:7555/
</code></p>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="pls">

<info>
	<link type="guide" xref="glossary#filetypes"/>
        <desc>Playlist file format.</desc>
</info>

	<title>.PLS files</title>

	<p>Playlist files often have the extension .pls</p>
	<p>It's the primary station stream link format of SHOUTcast.</p>
	<p>The MIME type of these files is audio/x-scpls and they often look like: </p>
<p><code mime="audio/x-scpls">
[playlist]
numberofentries=1
File1=http://123.45.67.189:8222
Title1=(#1 - 555/2000) radio station Xyz - top 100 - all the hitzez
Length1=-1
</code></p>

</page>

#!/usr/bin/perl -p

s{(<gui>)?(\w.+( > \w.+)+)(</gui>)?}{<guiseq><gui>$2</gui></guiseq>}im;
s{(\w.+?) > (\w.+?)}{$1</gui> <gui>$2}img;
s{(\w.+?) > (\w.+?)}{$1</gui> <gui>$2}img;

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->

<svg
   xmlns:dc="http://purl.org/dc/elements/1.1/"
   xmlns:cc="http://creativecommons.org/ns#"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
   width="439.92966"
   height="274.76151"
   id="svg2"
   version="1.1"
   inkscape:version="0.47 r22583"
   sodipodi:docname="mainwindow.svg">
  <defs
     id="defs4">
    <inkscape:perspective
       sodipodi:type="inkscape:persp3d"
       inkscape:vp_x="0 : 526.18109 : 1"
       inkscape:vp_y="0 : 1000 : 0"
       inkscape:vp_z="744.09448 : 526.18109 : 1"
       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
       id="perspective10" />
    <inkscape:perspective
       id="perspective2844"
       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
       inkscape:vp_z="1 : 0.5 : 1"
       inkscape:vp_y="0 : 1000 : 0"
       inkscape:vp_x="0 : 0.5 : 1"
       sodipodi:type="inkscape:persp3d" />
    <inkscape:perspective
       id="perspective2844-9"
       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
       inkscape:vp_z="1 : 0.5 : 1"
       inkscape:vp_y="0 : 1000 : 0"
       inkscape:vp_x="0 : 0.5 : 1"
       sodipodi:type="inkscape:persp3d" />
    <inkscape:perspective
       id="perspective2844-94"
       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
       inkscape:vp_z="1 : 0.5 : 1"
       inkscape:vp_y="0 : 1000 : 0"
       inkscape:vp_x="0 : 0.5 : 1"
       sodipodi:type="inkscape:persp3d" />
    <inkscape:perspective
       id="perspective2844-3"
       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
       inkscape:vp_z="1 : 0.5 : 1"
       inkscape:vp_y="0 : 1000 : 0"
       inkscape:vp_x="0 : 0.5 : 1"
       sodipodi:type="inkscape:persp3d" />
    <inkscape:perspective
       id="perspective2939"
       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
       inkscape:vp_z="1 : 0.5 : 1"
       inkscape:vp_y="0 : 1000 : 0"
       inkscape:vp_x="0 : 0.5 : 1"
       sodipodi:type="inkscape:persp3d" />
  </defs>
  <sodipodi:namedview
     id="base"
     pagecolor="#ffffff"
     bordercolor="#666666"
     borderopacity="1.0"
     inkscape:pageopacity="0.0"
     inkscape:pageshadow="2"
     inkscape:zoom="0.98994949"
     inkscape:cx="258.4942"
     inkscape:cy="185.63951"
     inkscape:document-units="px"
     inkscape:current-layer="layer1"
     showgrid="false"
     inkscape:window-width="1146"
     inkscape:window-height="972"
     inkscape:window-x="32"
     inkscape:window-y="172"
     inkscape:window-maximized="0" />
  <metadata
     id="metadata7">
    <rdf:RDF>
      <cc:Work
         rdf:about="">
        <dc:format>image/svg+xml</dc:format>
        <dc:type
           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
        <dc:title />
      </cc:Work>
    </rdf:RDF>
  </metadata>
  <g
     inkscape:label="Ebene 1"
     inkscape:groupmode="layer"
     id="layer1"
     transform="translate(-159.09078,-322.02188)">
    <g
       id="g2852">
      <rect
         y="322.02188"
         x="159.6041"
         height="274.76151"
         width="439.41635"
         id="rect2816"
         style="fill:#e6e6e6;fill-opacity:1;stroke:none" />
      <rect
         y="322.02188"
         x="159.6041"
         height="20.203051"
         width="272.74118"
         id="rect2818"
         style="fill:#666666;fill-opacity:1;stroke:none" />
      <path
         transform="translate(6.0609153,8.0812204)"
         d="m 188.89853,353.33661 -11.36421,6.56113 -11.36422,6.56114 0,-13.12227 0,-13.12227 11.36422,6.56114 11.36421,6.56113 z"
         inkscape:randomized="0"
         inkscape:rounded="0"
         inkscape:flatsided="false"
         sodipodi:arg2="1.0471976"
         sodipodi:arg1="0"
         sodipodi:r2="7.5761442"
         sodipodi:r1="15.152288"
         sodipodi:cy="353.33661"
         sodipodi:cx="173.74625"
         sodipodi:sides="3"
         id="path2820"
         style="fill:#008000;fill-opacity:1;stroke:none"
         sodipodi:type="star" />
      <path
         transform="translate(-2.0203051,-3.0304576)"
         inkscape:transform-center-x="-6.0609153"
         d="m 233.34524,364.4483 c 0,6.69471 -5.87939,12.12183 -13.13198,12.12183 -7.2526,0 -13.13199,-5.42712 -13.13199,-12.12183 0,-6.6947 5.87939,-12.12183 13.13199,-12.12183 7.25259,0 13.13198,5.42713 13.13198,12.12183 z"
         sodipodi:ry="12.121831"
         sodipodi:rx="13.131983"
         sodipodi:cy="364.4483"
         sodipodi:cx="220.21326"
         id="path2822"
         style="fill:#800000;fill-opacity:1;stroke:none"
         sodipodi:type="arc" />
      <text
         transform="scale(0.618526,1.6167469)"
         id="text2824"
         y="230.25543"
         x="707.06281"
         style="font-size:36.30619431px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
         xml:space="preserve"><tspan
           y="230.25543"
           x="707.06281"
           id="tspan2826"
           sodipodi:role="line">streamtuner2</tspan></text>
      <path
         id="path2828"
         d="m 159.69408,399.56285 398.39683,-0.89352 36.79897,0.36494"
         style="fill:none;stroke:#000000;stroke-width:1.20659292px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
      <text
         transform="scale(0.99810497,1.0018986)"
         id="text2830"
         y="336.47824"
         x="168.58113"
         style="font-size:15.96251678px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
         xml:space="preserve"><tspan
           y="336.47824"
           x="168.58113"
           id="tspan2832"
           sodipodi:role="line">Station Edit Channel Help</tspan></text>
      <rect
         y="381.62091"
         x="168.69548"
         height="19.192898"
         width="60.609154"
         id="rect2834"
         style="fill:#999999;fill-opacity:1;stroke:none" />
      <rect
         y="382.12598"
         x="236.37569"
         height="19.192898"
         width="60.609154"
         id="rect2834-0"
         style="fill:#666666;fill-opacity:1;stroke:none" />
      <rect
         y="381.11581"
         x="304.05594"
         height="19.192898"
         width="60.609154"
         id="rect2834-09"
         style="fill:#999999;fill-opacity:1;stroke:none" />
      <rect
         y="382.12598"
         x="371.73615"
         height="19.192898"
         width="60.609154"
         id="rect2834-5"
         style="fill:#999999;fill-opacity:1;stroke:none" />
      <rect
         y="382.12598"
         x="438.40622"
         height="19.192898"
         width="60.609154"
         id="rect2834-7"
         style="fill:#999999;fill-opacity:1;stroke:none" />
      <text
         transform="scale(0.87874836,1.1379822)"
         id="text2887"
         y="348.10754"
         x="193.84726"
         style="font-size:12.21920872px;font-style:normal;font-weight:normal;fill:#e6e6e6;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
         xml:space="preserve"><tspan
           y="348.10754"
           x="193.84726"
           id="tspan2889"
           sodipodi:role="line">bookmarks   Shoutcast     Xiph            Jamendo</tspan></text>
      <rect
         y="409.90515"
         x="166.67517"
         height="167.68532"
         width="81.822365"
         id="rect2891"
         style="fill:#f9f9f9;fill-opacity:1;stroke:none" />
      <text
         transform="scale(0.98758137,1.0125748)"
         id="text2893"
         y="425.48941"
         x="175.3701"
         style="font-size:13.59386539px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
         xml:space="preserve"><tspan
           y="425.48941"
           x="175.3701"
           id="tspan2895"
           sodipodi:role="line">Category</tspan><tspan
           id="tspan2897"
           y="442.48175"
           x="175.3701"
           sodipodi:role="line">Genre</tspan><tspan
           id="tspan2899"
           y="459.47406"
           x="175.3701"
           sodipodi:role="line">genre</tspan><tspan
           id="tspan2901"
           y="476.4664"
           x="175.3701"
           sodipodi:role="line">genre</tspan><tspan
           id="tspan2903"
           y="493.45874"
           x="175.3701"
           sodipodi:role="line">genre</tspan><tspan
           id="tspan2905"
           y="510.45108"
           x="175.3701"
           sodipodi:role="line">genre</tspan></text>
      <rect
         y="410.91531"
         x="265.67014"
         height="168.69548"
         width="317.1879"
         id="rect2907"
         style="fill:#f9f9f9;fill-opacity:1;stroke:none" />
      <text
         transform="scale(1.0541937,0.94859229)"
         id="text2893-5"
         y="453.32745"
         x="260.99759"
         style="font-size:14.31282997px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
         xml:space="preserve"><tspan
           id="tspan2905-3"
           y="453.32745"
           x="260.99759"
           sodipodi:role="line">Radio station      128   http://www.radi</tspan><tspan
           id="tspan2981"
           y="471.21851"
           x="260.99759"
           sodipodi:role="line">Station title ...     128   http://123.fm/</tspan><tspan
           id="tspan2983"
           y="489.10953"
           x="260.99759"
           sodipodi:role="line">Stream title ....    128   http://www....</tspan><tspan
           id="tspan2985"
           y="507.00058"
           x="260.99759"
           sodipodi:role="line">....</tspan><tspan
           id="tspan2987"
           y="524.8916"
           x="260.99759"
           sodipodi:role="line">....</tspan><tspan
           id="tspan2989"
           y="542.78265"
           x="260.99759"
           sodipodi:role="line">...</tspan><tspan
           id="tspan2991"
           y="560.67371"
           x="260.99759"
           sodipodi:role="line">.....</tspan><tspan
           id="tspan2993"
           y="578.5647"
           x="260.99759"
           sodipodi:role="line">...</tspan><tspan
           id="tspan2995"
           y="596.45575"
           x="260.99759"
           sodipodi:role="line">........</tspan></text>
    </g>
  </g>
</svg>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="index">

	<info>
	<credit type="author"><name>Mario Salzer</name></credit>
        <desc>Documentation overview</desc>
	</info>

	<title><media type="image" mime="image/png" src="img/logo.png">♪</media> Streamtuner2 </title>

	<p>Streamtuner2 shows internet radio stations for easy browsing, playing, recording.</p>

	<section id="browsing" style="2column">
            <title>Browsing channels and radio stations</title>
    	</section>

	<section id="channels" style="2column">
            <title>Channel tabs</title>
    	</section>

	<section id="functions" style="2column">
            <title>Functions</title>
    	</section>

	<section id="configuration" style="2column">
            <title>Configuration</title>
    	</section>

	<section id="advanced" style="2column">
            <title>Advanced topics</title>
    	</section>

	<section id="footer">
	<p>You can get additional help from the online forum. See help menu for the link.</p>

	<p>Update status: This documentation is based on available functions in streamtuner2
	version 2.0.7 of August 2010. It is still incomplete however.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="introduction">

<info>
	<link type="guide" xref="index"/>
        <desc>Basic usage instructions. Selecting a channel, category, and playing a radio.</desc>
</info>

	<title>Introduction</title>

	<p>Streamtuner2 is a simple browser for internet radios. It aquires its radio lists
	from various directory services. These are represented as "channel" tabs in the main
	window. Below are the category/genre lists (left) and the stations for a genre (right).</p>

	<media src="img/mainwindow2.svg" type="image" mime="image/svg+xml" />

        <section id="play">
	<title>How to select and play a radio.</title>
	<steps>
		<item><p>Select a channel tab, like <code>Shoutcast</code>.</p></item>
		<item><p>Click one of the genres in the left pane. For example <code>Classic</code>.</p></item>
		<item><p>Now the right pane loads a radio list.</p></item>
		<item><p>Double click one of the radio streams or use the <key>play</key> toolbar button.</p></item>
	</steps>
	<p>Note that some categories can and should be exanded. In a few plugins (modarchive),
	the expandable genre/category brings up no station list on its own, while in Shoutcast
	and most others it's a valid genre in itself.</p>
	<p>Some radio stations cannot be played, because they just have a homepage. (That's the
	case for all listings in the Google Stations channel.)</p>
	</section>

	<section id="actions">
	<title>What else can you do?</title>
	<p>Double clicking an entry row in the radio list starts your audio player. But there are
	other functions available. Either go to the <guiseq><gui/><gui>Station</gui></guiseq> menu,
	or access the context menu with a right click.</p>
	<table shade="rows" rules="rows cols">
		<tr><td>Play</td><td>Starts the radio in a configured audio player</td></tr>
		<tr><td>Record</td><td>Opens a terminal window and streamripper, which cuts the radio broadcast into individual mp3 songs.</td></tr>
		<tr><td>Bookmarks</td><td>Copy radio entry over into the <gui>bookmarks</gui> channel.</td></tr>
		<tr><td>Homepage</td><td>Most radio stations have a homepage. Open this in a web browser.</td></tr>
		<tr><td>Saving</td><td>A radio entry can be exported as .m3u or .pls file.</td></tr>
		<tr><td>Extensions<guiseq><gui/><gui/></guiseq></td><td>Some plugins add other features in this submenu.</td></tr>
		<tr><td>Editing</td><td>This command is in the <gui>Edit</gui> and context menu, allows to inspect and modify radio descriptions.</td></tr>
		<tr><td>Searching</td><td>You can get a radio list according to search criteria.</td></tr>
	</table>
	<p> Play, Record and Homepage also have buttons in the toolbar.</p>
	</section>

	<section>
	<title>Radio lists get stale</title>
	<p>After some time, stream informations become obsolete. Therefore you should regularily
	refresh the lists. The <gui>Reload</gui> button in the toolbar (or <key>F5</key>) is your friend. You can
	also update the category lists with <guiseq><gui>Channel</gui> <gui>Reload Category Tree</gui></guiseq>
	and load favicons using <guiseq><gui>Channel</gui> <gui>Update favicons..</gui></guiseq>.</p>
	</section>

	<section>
	<note style="tip"><p>You should only select radio stations and genres that you like.</p></note>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="reloading">

<info>
	<link type="guide" xref="streams#actions"/>
        <desc>Updating station lists.</desc>
</info>

	<title>Reloading</title>
        <p>Station information can get stale. Especially Shoutcast invalidates old information
        frequently. Therefore you have to [reload] the lists. There is an action button below
        the menu bar for this. It retrieves the current data from the directory service.</p>

	<p>Favicons aren't loaded automatically. There is a menu entry in Channels for that, which
        works in the background and doesn't display the new icons automatically either. Simply
        reselect the category/genre in the left pane. Or again, use the station reload button.</p>


</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="search">

<info>
	<link type="guide" xref="bookmarks#other"/>
	<link type="guide" xref="index#functions"/>
        <desc>Quicksearch field and Ctrl+F compound search window.</desc>
</info>

	<title>Searching</title>

	<p>There are two search functions. The quick search field is in the toolbar, and allows
	to highlight search terms in the current station list. The cache search is available
	through the <guiseq><gui>Edit</gui> <gui>Search</gui></guiseq> menu instead and provides more details.</p>

	<section id="cachesearch">
	<title>Dialog options</title>
	<p>You can get to the search dialog via <guiseq><gui>Edit</gui> <gui>Find</gui></guiseq> or <key>Ctrl</key>+<key>F</key>. Centrally to this dialog is the
	text field, where you can specify the phrase to scan for.</p>

	<p>Above you can check which channel plugins to inspect for the search term. Using this
	allows to limit the search to specific radio station directories, but usually you want
	to search them all.</p>

	<p>Below the search phrase text box, you can specifiy which station fields to look
	into. Often you just want to search the titles of radio stations. But you can also
	have the search occour in the description/playing fields. Alternatively you could
	just search the homepage links.</p>
	</section>

	<section id="methods">
	<title>Search methods</title>
	<p>Lastly, there are three search methods. You mostly want to use the <gui>cache search</gui>,
	which just scans through the station lists streamtuner2 has downloaded. Since you are mostly
	looking for something you had already seen, this will give you the desired results.</p>
	<p>The <gui>server search</gui> would try to do a live search on the directory servers,
	providing you with the most recent data. However, it's not implemented for all channel
	plugins, and therefore brings limited output.</p>
	<p>Use the button <gui>google it</gui> as last resort, if streamtuner2 didn't find anything.</p>
	</section>

	<section id="quicksearch">
	<title>Quick search</title>
        <p>Just enter text into the quick search box. Streamtuner2 will instantly highlight
	any matches in the current stations view. If you switch tabs, just click the glass icon
	to reapply the highlighting.</p>
	</section>

</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="streams">

<info>
	<link type="guide" xref="index#browsing"/>
        <desc>Radio streams lists, station information columns, entry actions.</desc>
</info>

	<title>Streams / Stations</title>

	<p>Radio stations are listed in the right pane. Usually they have a title and a
        description. The description is often the last played song. (This isn't updated
        automatically to conserve bandwidth and because live information is seldomly available.)</p>

	<media type="image" mime="image/png" src="img/streams.png">Station list</media>

        <p>You can double click a station line to get it to play. Alternatively there are the
        play and record buttons in the menubar. You can also invoke a stations homepage, if it
        has one.</p>


<section id="actions">
	<title>Actions</title>
</section>

<section>
	<title>Context menu</title>

        <p>Additionally most actions are available in a context menu. Right click
        a station entry to display it.</p>

	<note><p>Reshuffling of station entries in the list is possible by dragging them. But
	this is only a visual effect and will confuse the internal ordering of entries. Don't
	do it.</p></note>

	<p>You can always click the current category in the left list, to have the current
	station list redisplayed. Which is useful after updating favicons, or accidental
	dragging of entries.</p>
</section>

</page>

.\" this is one of the nanoweb man pages
.\" (many thanks to the manpage howto!)
.\"
.TH streamtuner2 "July 2010" "BSD/Linux" "User Manuals"
.SH NAME
streamtuner2 \- Browser for internet radio stations
.SH SYNOPSIS
.B streamtuner2
.I command
[
.BI channel ,...
] [
.IB title
]

.SH DESCRIPTION
Streamtuner2 is a graphical application for browsing through internet
radio station directories, like
.BR Shoutcast.com " and " Xiph.org " or " Internet-Radio.org.uk .
It is written in Python and easy to extend. And besides the grapical
interface, has a commandline interface.

.SH OPTIONS

.B Display data from cache

.TP
.BI help
Prints out a summary of available commands.
.TP
.BI stream " channel title"
Searches for a station with the given title. Either looks in a single
channel, or scans all plugins.
.TP
.BI url " channel title"
Prints out only the streaming URL.
.TP
.BI play " " [ channel ] " title"
Invokes the configured audio player.

.PP
.B Load data from directory service

.TP
.BI categories " channelname"
Returns a nested JSON list of all categories/genres.
.TP
.BI category " ""channelname"" ""Category"""
Prints out a JSON list of the genre. Each entry constains title, url and
other meta information. Note that the category must have the exact case.

.SH EXAMPLES
.TP
.BI streamtuner2 " stream" " shoutcast,xiph" " ""Top 100"""
Searches for the term "Top 100" in the shoutcast and xiph channels, and
returns all info about the first match as JSON output.
.TP
.BI streamtuner2 " play frequence3"
Looks for the first occourence, and starts the audio player for FREQUENCE3.


.SH FILES
.IR /home/ $USER /.config/streamtuner2/settings.json
.SH "SEE ALSO"
.BR streamripper (1) 
.BR audacious (1)
.BR json (5)
.BR m3u (5)
.BR pls (5)

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="technical">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Filenames, Directories, Dependencies</desc>
</info>

	<title>Technical information</title>


	<section id="dependecies">
  	  <title>Dependencies</title>
        <terms>
          <item><p>Python 2.5</p></item>
          <item><p>PyGtk</p></item>
          <item><p>Gtk+ 2.12</p></item>
	</terms>
        <terms>
  	  <title>Soft dependencies</title>
          <item><p>Python-LXML</p></item>
          <item><p>Python-PyQuery</p></item>
          <item><p>Audacious</p></item>
	</terms>
	</section>


	<section id="config_files">
  	  <title>Configuration files</title>
        <terms>
          <item>
            <title>/home/$USER/.config/streamtuner2/</title>
            <p>Corresponds to the XDG_CONFIG_HOME setting. All ST2 configuration settings
            are contained within here and are in JSON format.</p>
          </item>
          <item>
            <title>~/.config/streamtuner2/settings.json</title>
            <p>General runtime options, plugin settings, and configured audio players.</p>
          </item>
          <item>
            <title>~/.config/streamtuner2/window.json</title>
            <p>Saved window sizes, list widths.</p>
          </item>
          <item>
            <title>~/.config/streamtuner2/state.json</title>
            <p>Last category in each channel tab.</p>
          </item>
          <item>
            <title>~/.config/streamtuner2/bookmarks.json</title>
            <p>Is a separate cahce file for your bookmarked/favourite radio stations.</p>
          </item>
          <item>
            <title>~/.config/streamtuner2/cache/***.json</title>
            <p>JSON files for stream lists in each channel.</p>
          </item>
          <item>
            <title>~/.config/streamtuner2/icons/*.png</title>
            <p>Holds downloaded favicons for station homepages.</p>
          </item>
	</terms>
	</section>


	<section id="install_dirs">
  	  <title>Installation spread</title>
        <terms>
          <item>
            <title>/usr/bin/streamtuner2</title>
            <p>Is the main binary.</p>
          </item>
          <item>
            <title>/usr/share/streamtuner2/</title>
            <p>Contains the individual ST2 python modules, and plugins in channels/. Also packages in pyquery/, but which is only used if the according modules aren't installed by the distribution.</p>
          </item>
          <item>
            <title>/usr/share/doc/streamtuner2/</title>
            <p>Contains the README, and Mallard/gnome-help/yelp files under help/.</p>
          </item>
	</terms>
	</section>


	<section id="license">
	<title>Public Domain</title>
	<p>There is no licensing requirement with this application. All code can be copied, modified
	and distributed unrestrictively.</p>
	</section>


</page>

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="timer">

<info>
	<link type="guide" xref="bookmarks#other"/>
	<link type="guide" xref="index#advanced"/>
        <desc>Programming recurring play and recording events.</desc>
</info>

	<title>Timer</title>

	<p>You can programm play/recording events with the timer plugin. Simply select a station
	and choose <guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Add timer...</gui></guiseq>.
	A small popup will ask for a data/time string. If you press <key>OK</key> the station
	and the programmed time
	will be stored in the bookmarks channel in the "timer" category.</p>

        <note style="tip"><p>Note that streamtuner2 must be running for the programmed timer events to work.
	(In a future version there might be the option to have it handled by the system cron
	daemon.)</p></note>


	<section id="timestring">
	<title>Time specification strings</title>
	<p>The time and date specificators follow a simple scheme. It's always one or more day names
	followed by a clock range, and finally the action.</p>
	<p>For example "<code>Mon,Tue,Wed</code>" will make the event occour on the first
	three days of each week, while just "Fri" would limit it to Fridays.</p>
	<p>A clock range of "<code>18:00-20:00</code>"
	would start the event at 18 o'clock and last it two hours. Note that for "play" events, the end
	time is irrelevant, since streamtuner2 can't kill your audio player anyway.</p>
        <p>The end time is only important, if you replace "play" with the word "<code>record</code>"
        in the timer event string. This runs streamripper instead and limits the recording time.</p>
	</section>

	<section id="editing">
	<title>Editing events</title>
        <p>You can remove entries from the "timer" list again. Use the normal <guiseq><gui>Edit</gui> <gui>Delete</gui></guiseq> for
	that. It's also possible to modify the date+time strings by editing the stream info and
	the specification in the "playing" field.</p>

	<note style="warning"><p>However, such changes don't take effect until you restart streamtuner2. The timer
	events are only scheduled when adding a new event, or on starting streamtuner2.</p></note>
	</section>

</page>