2.1.5 (unreleased)
- This is a beta release, with lots of cleanups and various bugfixes.
- Adds a self-contained PYZ package, which Python can run directly.
- Now fully utilizes the plugin meta data scheme for default settings,
  discovery, and to reduce internal complexity.
- A new channel plugin for "Radio-Browser.info" has been bundled.
- Another plugin for interfacing with "RadioTray" was introduced, to
  share bookmarks via DBUS once RadioTray implements it.
- Notebook tabs are now on the left per default, and can be rearranged
  directly in the GUI.
- The configuration dialog now indicates the availability of selected
  audio players. Default audio players are now automatically configured
  during the first startup.
- Gtk properties are now utilized more over internal UI state vars.
- The the GtkBuilder UI file is now compressed, the Gtk2 fallback removed.

- The former channel icon PNGs are now embedded.
- Theme configuration was removed.
- Category retrieval became more resilient.
- HTTP timeouts have been added.
- The bookmarks tab, settings window, search dialog, stream inspector/editor
  have been externalized into plugins; yet remain core features.
- The packaging layout has been slightly restructured - to support
  relocatable installations (for PyZIP package).
- Minor fixes to youtube, internet_radio, punkcast, timer and other plugins.
- Help pages have been updated further, as well as CREDITS, README and
  general PACKAGING infos, and most plugin short descriptions.
- The project wiki now contains a more details on plugin APIs.

2.1.4 (2015-03-25)
- Fixed Internet-Radio extraction.
- Added basic TuneIn channel.
- Removed Dirble and MusicGoal channels.
- Fix desktop and packaging infos according to Debian guidelines.
- Switch to fpm/xml for package building.

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

<info>
	<link type="guide" xref="index#functions"/>
	<link type="guide" xref="streams#actions"/>
	<desc>Edit or inspect a station entry.</desc>
</info>

	<title>Edit</title>

	<p>You probably don't often need this. But there's an
	<guiseq><gui></gui> <gui>Edit/Details</gui></guiseq> context menu
	which brings up a station editor:
	</p>
	
	<media type="image" src="img/streamedit.png" mime="image/png" />

	<p>You can see the standard title and genre fields here. But also a
	few internally kept infos. For example the "url" field contains the
	actual pls/m3u/server address. While the "format" can list a
	non-standard audio compression type.</p>

	<note>
	<p>This dialog is primarily useful for your personal bookmarks.
	It allows to shorten or rename things. You can even use
	<gui style="button">new</gui> to add new entries this way.
	(Which doesn't make sense in regular channel categories, because
	changes will be lost once you hit Reload.)</p>
	</note>


</page>

        <p>In streamtuner2 you can configure different audio players for different audio
        formats (MP3 or OGG). In the <link xref="config_apps">Apps</link> section of the
        <link xref="configuration">settings dialog</link>, you can associate one 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 instances 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>

<p>You can <link xref="configuration">configure the recording tool</link> according to audio types again.</p>

<section>
<title>Streamripper</title>

<p>The <cmd>xterm -e</cmd> prefix brings up the terminal popup. If you want
silent downloads in the background (instead of seeing its progress), remove
the xterm call.</p>

<table shade="rows" rules="rows cols">
  <thead>  <tr><td><p>Format</p></td>     <td><p>Application</p></td></tr> </thead>
  <tr><td><p><var>audio/*</var></p></td>  <td><p><cmd>xterm -e streamripper %srv</cmd></p></td></tr>
</table>

<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> or by pressing
	<key>F2</key>.  A file dialog opens, where you can adapt the title.
	</p>

	<p>The extension of the filename decides on the saved link format.  Per
	default a .m3u file is created, because that's what most audio players
	understand.</p>

</info>

	<title>Bookmarks</title>

	<p>Streamtuner2 allows to bookmark favoured streams/stations.
	Which is what the <gui style="menu">bookmarks</gui> tab is for, of course.</p>

        <p>Use right click for a stations <guiseq><gui>context menu</gui> <gui>bookmark</gui></guiseq>
        or just press <key>F8</key>.</p>

        <p>Once bookmarked the station is listed under
        <guiseq><gui style="menu">bookmarks</gui> <gui>favourite</gui></guiseq>.
        Additionally every appearance of the station in channel tabs gets a ★
        star icon.</p>

	<section id="editing">
	<title>Editing</title>
        <p>Entries can be removed from the bookmark list again. Use
        <guiseq><gui>Edit</gui> <gui>Delete</gui></guiseq> or the <key>DEL</key>
	key for that.</p>

        <p>You can also manually adapt an entry via <guiseq><gui>Station</gui> <gui>Edit</gui></guiseq>
        or by pressing <key>F3</key>.
	</p>

	</section>

	<section id="other">
	<title>Subcategories</title>
	<p>The bookmarks tab can display other categories besides "favourite". For example the

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

<terms>
  <title>Channel options.</title>
  <item>
    <title><code>Language</code></title>
    <p>There's an English and a German variant of this radio directory. Genres are
    also localized. Restart streamtuner2 after switching the Language option. Then
    use <guiseq><gui>Channel</gui> <gui>Reload category tree</gui></guiseq>.</p>
  </item>
</terms>

</page>

<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 change this option. OGG starts to sound well with 96 kbit/s (whereas
    MP3 often requires 128 or 160 kbit/s at least).</p>
  </item>
</terms>

</page>

        button simply.</p>


<terms>
  <title>Channel options.</title>
  <item>
    <title><code>Region</code></title>
    <p>With the country dropdown you can predefine which mostPopular listings are returned.</p>
  </item>
  <item>
    <title><code>My Channels</code></title>
    <p>You can edit the list of YT channel names to fetch some of your favourite artists/uploaders.
    To apply this setting, and have new categories show up in the genre pane, use
    <guiseq><gui>Channel</gui> <gui>Update category tree</gui></guiseq> first.</p>
    <p>It's not an exact map, but utilizes the search function to find channels.</p>

	</info>

	<title>Channels</title>

	<p>The tabs in the main window represent the music directory
        channels/services.  Each lists categories/genres and their associated radios/streams.</p>

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

        <p>The notebook tabs can also be repositioned with
        <guiseq><gui>Edit</gui> <gui>Channel tab position</gui> <gui>Left</gui></guiseq>.
        And since 2.1.5 you can directly reorder the channel tabs themselves,
        by dragging them around.</p>

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

	</section>

	<section id="actions">
	<title>Channel menu actions</title>
	<terms>
		<item>
			<title>Homepage of directory service</title>
			<p>Opens the website of the currently selected channel
			in your configured web browser.</p>
		</item>
		<item>
			<title>Reload</title>
			<p>Updates the current category and displays fresh station lists.</p>
		</item>
		<item>
			<title>Update favicons...</title>

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

	<p>Some applications, like Rhythmbox or Banshee, are primarily playlist managers, not players,
        and cannot be invoked with a play URL by other apps. This makes them less suitable for use with
	streamtuner2. (Same goes for streamtuner2 of course. It's not a player, just a playlist tool.)</p>

	<section id="placeholders">
	<title>URL placeholders</title>

	<p>Any listed application can be invoked with a different kind of
	URL or filename. Most are rather flexible, but some depend on
	specific playlist file types or URLs. You can control this by adding
	a placeholder after the configured application name:</p>

	<table shade="rows" rules="rows cols">
	<thead>	<tr><td><p>Placeholder</p></td><td><p>Alternatives</p></td><td><p>URL/Filename type</p></td></tr> </thead>
		<tr><td><p>%m3u</p></td><td><p>%f %g %m</p></td><td><p>Provides a local .m3u file for the streaming station</p></td></tr>
		<tr><td><p>%pls</p></td><td><p>%url %u %r</p></td><td><p>Either a remote .pls resource, or a local .pls file (if converted)</p></td></tr>
		<tr><td><p>%srv</p></td><td><p>%d %s</p></td><td><p>Direct link to first streaming address, e.g. http://72.5.9.33:7500</p></td></tr>
	</table>

<title>Settings dialog</title>

<p>
There are various options for streamtuner2, available under <guiseq><gui>Edit</gui>
<gui>Preferences</gui></guiseq> or via <key>F12</key>.
</p>
  <p><media type="image" src="img/configtabs.png" mime="image/png" /></p>

<terms>
  <title>It's separated into three main sections / tabs.</title>
  <item>
    <title>Player</title>
    <p>Lists audio formats and the audio player applications, or recording tools below.
    It's a file type to application table. Double click an entry for editing.</p>
  </item>
  <item>
    <title>Options</title>
    <p>Influences the display of all stream/station lists, and contains some system settings.</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 categorzied identifiers for file types. <var>Audio/mpeg</var> for example represents MP3 files,
    and <var>audio/ogg</var> means just OGG. And the player setting dialog simply associates an audio type with a
    playback application:</p>

<table shade="rows" rules="rows cols">
  <thead>  <tr><td><p>Format</p></td>     <td><p>Application</p></td></tr> </thead>
    <tr><td><p><var>audio/mpeg</var></p></td>     <td><p><cmd>audacious</cmd></p></td></tr>
    <tr><td><p><var>audio/ogg</var></p></td>      <td><p><cmd>audacious</cmd></p></td></tr>
    <tr><td><p><var>audio/*</var></p></td>        <td><p><cmd>vlc --one-instance</cmd></p></td></tr>
    <tr><td><p><var>video/*</var></p></td>        <td><p><cmd>totem</cmd></p></td></tr>
    <tr><td><p><var>video/youtube</var></p></td>  <td><p><cmd>vlc %srv</cmd></p></td></tr>
</table>

    <p>Application names are most always lowercase binary names. Double click an entry to edit it.
    After editing the icon next to the application name will be updated. If it stays green, it's
    likely to work. If it turns red / into a stop symbol, then the entered name is likely incorrect.</p>

   <p><media type="image" src="img/configapps.png" mime="image/png" /></p>

    <p>After the application name, you can use a placeholder like "<var>%pls</var>" (default),
    or "<var>%m3u</var>" and "<var>%src</var>". See <link xref="config_apps#placeholders">placeholders</link>.</p>

    <p>Catch-all entries like <var>*/*</var> or a generic <var>audio/*</var> entry allow to configure a default player.
    While <var>video/youtube</var> is specific to the Youtube channel. And <var>url/http</var> a psdeudo MIME type
    to configure a web browser (for station homepages).</p>
    
    <p>You can remove default entries by clearing both the Format field and its associated Application.
    Add completely new associations through the emtpy line. (Reopen the dialog to add another one.)</p>

</section>
<section id="recording">

    <title>Recording Apps</title>

    <p>The second block of entries in the 'Apps' section specifies recording applications.
    Here streamripper is preconfigured for audio streams, and youtube-dl for Youtube videos for instance.</p>

<table shade="rows" rules="rows cols">
    <tr><td><p><var>audio/*</var></p></td>         <td><p><cmd>xterm -e streamripper %srv</cmd></p></td></tr>
    <tr><td><p><var>video/youtube</var></p></td>   <td><p><cmd>xterm -e "youtube-dl %srv"</cmd></p></td></tr>
</table>

    <p>To define a target directory, you can often add commandline arguments to each. Also it's typically
    helpful to leave the xterm prefix on, so you can follow the processing state. (Alternatively to
    xterm there is x-terminal-emulator, or rxvt, gnome-terminal, xfce4-terminal, etc.)</p>
</section>


<section id="gui">

    </item>
    <item>
      <title>Show bookmark star</title>
      <p>Bookmarked stations will be marked with a ★ star in all other station lists / categories.
      That doesn't often work for the same station entry from two different channel services / tabs though.</p>
    </item>
    <item>





      <title>Save window states</title>
      <p>Automatically remember window size, selected channel tab, categories, or selected station.
      Also keeps the width of station list columns. If disabled, you can manually save the current
      layout/selections via <guiseq><gui>Edit</gui> <gui>Save States</gui></guiseq>.</p>
    </item>
 </terms>

  <terms>
    <title>Station loading</title>
    <item>
      <title>Prefer HTML traversing (PyQuery) over regex</title>
      <p>Some channels provide proper APIs to fetch station lists. Others are just websites that
      require scraping listings out. Most channel tabs provide two alternative methods for that.
      The DOM/HTML selection method is sometimes slower, but more reliable. As fallback streamtuner2
      plugins often use a regex to match text. Occassionally the regex method is surprisingly more exact,
      because directory services often use frightful unstructured HTML. If available, both methods
      are tried. You can influence the order with this setting, and thus speed it up.</p>
    </item>
    <item>
      <title>[<input>250</input>] Limit stream number</title>
      <p> Constraints the length of station lists per category.
      The number of stations option 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 many scrollable entries appear in the stream lists.</p>
    </item>
    <item>
      <title>Retain deleted stations</title> <p>When enabled, keeps old station entries when
      updating/reloading a category/genre.  Services often forget stations or throws them out when inavailable.
      With this option enabled, these entries are kept in streamtuner2 as strikethrough entries (often
      at the end of the list).</p>
    </item>

</section>

<section id="plugins">
    <title>Plugin and Channel settings</title>

    <p>This tab lists all available channel and feature plugins. Mark checkboxes for those plugins
    you want to enable. You have to restart Streamtuner2 for any changes here to take effect.</p>
    
    <p><media type="image" src="img/configplugins.png" mime="image/png" /></p>

    <p>Each channel plugin may come with its own set of addition configuration settings
    below.</p>

    <note style="note"><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></note>
</section>



</page>

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

<info>
	<link type="guide" xref="index#extra"/>
        <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 favourited 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 streamtuner2 atop your
	desktop 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 style="bug"><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>

            <title>Additional features</title>
    	</section>

	<section id="footer">
	<p>You can get additional help from the online forum. See <guiseq><gui>Help</gui> <gui>Forum</gui></guiseq>.</p>

	<p>This documentation was last updated for available functions in streamtuner2
	version 2.1.5, as of April 2015.</p>
	</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 <guiseq><gui></gui> <gui>Reload</gui></guiseq> 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>

	<section id="cachesearch">
	<title>Search window</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>

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

        <p>It either will search in all channels, or just the last active
        channel/service.</p>

	<p>Then there are two search methods.  You mostly want to use
        the live <gui>Server search</gui>.  It passes your search terms to
        the actual directory services, and loads the most recent data into a

</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>
	
	<media type="image" src="img/timer.png" mime="image/png">Timer</media>

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