<p>In streamtuner2 you can configure different audio players for different audio
        formats (MP3 or OGG). In the 'Apps' section of the settings dialog, you can associate a player
        with each audio file (MIME) type. Per default this is audacious, but you can use any other
        media player (like VLC).</p>

        <note><p>Note however that some audio players will run multiple instance and won't
        allow simple station switching. In such situations it might be sensible to write
        a wrapper script, or configure special commandline arguments to your favoured audio
        player (e.g. "vlc --one-instance").</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>

        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 broad to list here.
        You can set default arguments (e.g. another default save directory) in the Config &gt; Apps
        dialog.</p>

        <p>As alternative check out <link href="http://freshcode.club/projects/ficy">fIcy/fPls</a>
	for recording ICEcast/SHOUTcast streaming servers.</p>


</page>

	<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 have to 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 oversight when switching across channel tabs,
        genres and internet radio stations.  Therefore streamtuner2 allows

        to bookmark stations to 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 go.</p>

	<section id="editing">

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <desc>iCast</desc>
</info>

	<title>iCast.io</title>

	<p>iCast is another huge collaborative radio station directory.</p>

	<p>Its support in Streamtuner2 is quite robust, as it provides a JSON API.
	It lacks in meta data information though (homepages, currently playing, listeners, etc.)</p>

</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.com</title>

	<p>Internet-Radio.com is a broad alternative to Shoutcast. It
	has regained station homepages for most entries again.
	Genres are similiar to Shoutcast.</p>

	<note><p>Note that this plugin has its own setting on how many
	links to retrieve.  Instead of stream numbers, it only counts pages
	(which however speeds up processing now).</p></note>

</page>

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <desc>iTunes (RoliSoft Playlists)</desc>
</info>

	<title>iTunes Radios via RS</title>

	<p>iTunes radio is indirectly supported through the RoliSoft Radio Playlist
        APIs.</p>

</page>

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <desc>Live365 radio network</desc>
</info>

	<title>Live365</title>

	<p>Live365 is a radio broadcasting service and directory. It categorizes stations in
        over 250 genres. Not all radio stations are free to listen however. It's a commercial
        provider. Therefore streamtuner2 tries to filter result lists.</p>

	<p>This channel plugin is known to break once in a while. And it can't be guaranteed
	to pass working streaming URLs to audio players.</p>

	<p>If it breaks once more, it's going to get removed. (Unless someone else sends in
	a patch, of course!)</p>

</page>

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <desc>MOD files.</desc>
</info>

	<title>The MOD Archive</title>

	<p>MODArchive is a collection of module/tracker files. It's a community project, and
        categorizes individual audio files. You'll need a MOD-capable audio player.</p>

        <list>
             <item><p>XMP/libxmp</p></item>
             <item><p>MikMod</p></item>
             <item><p>MODPlug for XMMS</p></item>
             <item><p>GModplay</p></item>
             <item><p>VLC (built-in support)</p></item>
        </list>

</page>

        <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's 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 per default. You need to specify an user account
	in the settings dialog, and actually bookmark stations in MyOggRadio web site.
	Shared entries are not automatically in the MOR favorite list.</p>

	<p>There's also <a href="http://freshcode.club/projects/jmorp">JMyOggRadioPlayer</a>
	as specific frontend and player for MyOggRadio.</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

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <desc>Radio and Podcast directory.</desc>
</info>

	<title>TuneIn</title>

	<p>TuneIn hosts a major radio, show and podcast directory. It also provides the
        RadioTime/AIR interface for listener feedback or something. ST2 queries the OPML
        lists only for radio stations currently.</p>

</page>

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

	<p>GUI mode: There are also --gtk3 and --gtk2 command line options. Usually the right toolkit
	is picked depending on Python version. But you can manually override this.</p>

</page>

	<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><app>Audacious</app></td>     <td><cmd>audacious %m3u</cmd></td>  <td>audio</td></tr>
		<tr><td><app>XMMS2</td>               <td><cmd>xmms2 %m3u</cmd></td>      <td>audio</td></tr>
		<tr><td><app>Amarok</app></td>        <td><cmd>amarok -l %pls</cmd></td>  <td>audio</td></tr>
		<tr><td><app>Exaile</app></td>        <td><cmd>exaile %m3u</cmd></td>     <td>audio</td></tr>
		<tr><td><app>Amarok</app></td>        <td><cmd>amarok -l %pls</cmd></td>  <td>audio</td></tr>
		<tr><td><app>mplayer</app></td>       <td><cmd>mplayer %srv</cmd></td>    <td>console</td></tr>
		<tr><td><app>VLC</app></td>           <td><cmd>vlc %u</cmd></td>          <td>video/*</td></tr>
		<tr><td><app>Totem</app></td>         <td><cmd>totem %u</cmd></td>        <td>video/*</td></tr>
		<tr><td><app>Media Player</app></td>  <td><cmd>mplayer2.exe %pls</cmd></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,
	which ends the previous player process and starts it anew.
        For VLC there's however also the <code>--one-instance</code> option, which sometimes
        works better. (And sometimes not.)</p>

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

	<code type="text/python">

from channels import *

class myplugin (ChannelPlugin):

    title = "MyNewChannel"
    module = "myplugin"

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

        return entries
        
	</code>

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

	<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">
	<thead>	<tr><td><p>keyspec</p></td>                   <td><p>corresponds to</p></td></tr> </thead>
		<tr><td><p><input>F9</input></p></td>              <td><p>Responds to only <key>F9</key>. (too generic)</p></td></tr>
		<tr><td><p><input>&lt;Meta&gt;R</input></p></td>   <td><p>often the 'Windows'-key and R</p></td></tr>
		<tr><td><p><input>&lt;Ctrl&gt;N</input></p></td>   <td><p>Control and <key>N</key></p></td></tr>
		<tr><td><p><input>&lt;Shift&gt;F1</input></p></td> <td><p>Shift and F1</p></td></tr>
		<tr><td><p><input>&lt;Alt&gt;SPACE</input></p></td> <td><p>Use Alt and <key>Space</key>. (too generic)</p></td></tr>
		<tr><td><p><input>XF86Forward</input></p></td>     <td><p>Uses a "forward" function key. (default)</p></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>

	</section>


	<section id="config_files">
  	  <title>Configuration files</title>
        <terms>
          <item>
            <title><file>/home/$USER/.config/streamtuner2/</file></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><file>~/.config/streamtuner2/settings.json</file></title>
            <p>General runtime options, plugin settings, and configured audio players.</p>
          </item>
          <item>
            <title><file>~/.config/streamtuner2/window.json</file></title>
            <p>Saved window sizes, list widths.</p>
          </item>
          <item>
            <title><file>~/.config/streamtuner2/state.json</file></title>
            <p>Last category in each channel tab.</p>
          </item>
          <item>
            <title><file>~/.config/streamtuner2/bookmarks.json</file></title>
            <p>Is a separate cache file for your bookmarked/favourite radio stations.</p>
          </item>
          <item>
            <title><file>~/.config/streamtuner2/cache/***.json</file></title>
            <p>JSON files for stream lists in each channel.</p>
          </item>
          <item>
            <title><file>~/.config/streamtuner2/icons/*.png</file></title>
            <p>Holds downloaded favicons for station homepages.</p>
          </item>
	</terms>
	</section>


	<section id="install_dirs">
  	  <title>Installation spread</title>
        <terms>
          <item>
            <title><file>/usr/bin/streamtuner2</file></title>
            <p>Is the main binary.</p>
          </item>
          <item>
            <title><file>/usr/share/streamtuner2/</file></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><file>/usr/share/doc/streamtuner2/</file></title>
            <p>Contains the README, and Mallard/gnome-help/yelp files under help/.</p>
          </item>
	</terms>
	</section>


	<section id="license">