<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 style="button">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 some channels (e.g. Shoutcast) don't provide them (anymore).
	If you play a station without homepage URL, it automatically gets googled. (The link will be visible
        once you reselect the genre/category.)
        </p>

	</info>

	<title>Playing</title>

	<p>Simply double click a station entry. It starts with your configured audio player.</p>

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

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

<info>
	<link type="guide" xref="streams#actions"/>
	<link type="guide" xref="configuration#recording"/>
	<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 through the command-line tool <app>streamripper</app>.  If you
select a station and press <gui style="button">● record</gui>, a console
window should appear, where streamripper shows its progress.</p>

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

<p>To configure a default download directory, use the <cmd>-d</cmd> option to streamripper.
For example <cmd>xterm -e "streamripper -d /media/music/"</cmd> would use an absolute path.
Else it downloads to the current working directory (often your HOME path),
and creates one directory per radio station there.</p>
</section>


<section>
<title>fIcy/fPls</title>

<p>As alternative to streamripper, check out <link href="http://freshcode.club/projects/ficy">fIcy/fPls</link>

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

	<note><p> But you can also save in <file>.pls</file> or <file>.xspf</file>
	or <file>.asx</file> or <file>.smil</file> format.  Note that the
	lower right dropdown has no effect.  You have to edit the extension
	into the filename field.</p></note>


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

        <p>Use the right click a stations <guiseq><gui>context menu</gui> <gui>bookmark</gui></guiseq>
        or <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 <key>F3</key>.
	</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>
	<note style="bug"><p>However the favourite list itself can not yet be categorized
	further.</p></note>
	</section>

</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 new Jamendo v3.0 is now utilized. It allows to list albums,
playlists, and individual tracks by genre.  The radio list is static
(they're looping over randomized songs from each genre.)</p>

<p>Instead of favicons, streamtuner2 can fetch album or track
covers.  Thus the images are a bit larger, and retrieving them all
via <guiseq><gui>Channel</gui> <gui>Load favicons...</gui></guiseq>
takes a while longer.</p>

<section id="options">
<title><link xref="configuration">Config</link> options</title>
<terms>
   <title>System</title>
   <item>
     <title>Streaming format</title>
     <p>You can switch between MP3 and Ogg Vorbis audio streams for Jamendo.
     It's not honored by the radio section, but albums and tracks should be
     received as Ogg when configured so.</p>
   </item>
   <item>
     <title>Preview image sizes</title>
     <p>Album covers are downloaded in lieu of favicons. They're available
     in different sizes. Use 25px if you want just favicon-sized icons.</p>
   </item>
   <item>
     <title>Result length</title>
     <p>Currently only 1 page (of 200 entries each) of album/track lists are
     fetched.</p>
     <note style="bug"><p>Setting a higher value may not work.</p></note>
   </item>
</terms>
</section>


</page>

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

	<note><p>See <link xref="recording">recording
	configuration</link> if you want to enable the download mode. (Audio
	files are packaged up in ZIP files on MODArchive.)</p></note>

</page>

	<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>To help with populating the directory further,
	streamtuner2 provides an option to share radion station links.
	Use <guiseq><gui>Station</gui> <gui>Extensions</gui>
	<gui>Share on MyOggRadio...</gui></guiseq> menu entry to upload the currently
	selected radio (e.g. 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 the MyOggRadio web site.
	Shared entries aren't automatically in the MOR favorite list.</p>

	<p>There's also <link href="http://freshcode.club/projects/jmorp">JMyOggRadioPlayer</link>
	as specific frontend and player for MyOggRadio.</p>

<terms>
  <title>Channel options.</title>
  <item>

	<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 <link xref="gloassry_pls">PLS files</link>.</p></item>
		<item><p>Genres are subcategorized, so the main groups in the category
		list must be expanded to see the interesting entries.</p></item>
        </list>

        <p>Since being sold from AOL to Radionomy, the directory got cut down. There are no longer
        entries for currently played songs, and homepage links are largely gone. Hencewhy the
        Shoutcast channel is no longer considered a primary feature.</p>










</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 148 or 192 at least).</p>
  </item>
</terms>

</page>

	<title>Youtube</title>

	<p>Googles <link href="https://youtube.com/">Youtube</link> provides a quirky
        JSON API that makes browsing channels and genres feasible. This beta plugin
        provides a little overview, and usually retrieves recent video uploads.</p>

        <p>VLC can directly play Youtube URLs. For other players one can use
        <link href="http://youtube-dl.org/">youtube-dl</link> as wrapper.
        For example <cmd>totem $(youtube-dl %srv)</cmd> as configured player
        command.</p>
        
        <p>Youtube-dl is preconfigued as "recording"/download tool for this channel
        tab.</p>

        <p>Of course you could also just invoke a specific YT video by
        opening it in your web browser - click the station <key>home</key>
        button simply.</p>


<terms>
  <title>Channel options.</title>
  <item>
    <title><code>Region</code></title>
    <p>With the country dropdown you can predefine which mostPopular listins 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>
  </item>
  <item>
    <title><code>Wadsworth constant</code></title>
    <p>Only influences the video homepage link.</p>
  </item>
</terms>

</page>

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

	<section id="actions">
	<title>Channel menu actions</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 is often only 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>

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

        <section>
        <title>GUI options</title>
	<p>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>
	</section>

</page>

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

<info>
	<link type="seealso" xref="index#configuration"/>
	<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
	<link xref="configuration">configure</link> most of them as target application. Mostly it makes sense to use a single

<page
    xmlns="http://projectmallard.org/1.0/"
    type="guide" group="first"
    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 various options for streamtuner2, available under <guiseq><gui>Edit</gui>
<gui>Preferences</gui></guiseq> or via <key>F12</key>.
</p>

<terms>
  <title>It's separated into three main areas.</title>
  <item>
    <title>Player</title>

    <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>Gtk+ theme</title>
      <p><em style="bug">Be careful</em>. While Gtk allows to select a different theme per application, not all themes
      work right away. Switching the theme might hang streamtuner2. Just restart if that happens.</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>System</title>
    <item>
      <title>Temporary files</title>
      <p>Streamtuner2 creates temporary .m3u files - for audio players that are configured to use %m3u files
      instead of %pls or %srv URLs. For archival purposes you might want to set a dedicated directory
      for this. Leave this to the default /tmp else.</p>
    </item>
    <item>
      <title>Config directory</title>
      <p>Is where streamtuner2 keeps its <file>settings.json</file> and channel caches, favicons, etc.
      You can't set this in the config dialog. This is just for display. Set the <sys>XDG_CONFIG_HOME</sys>
      environment variable to adapt.</p>
    </item>
    <item>
      <title>Enable debug messages</title>
      <p>If you start streamtuner2 from a terminal window (xterm/rxvt), you can get a load of state
      and processing or debug infos. Enable this only for testing, as it might slow down station
      rendering.</p>

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

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

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

	<title>Glossary</title>

<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, and was
	popularized by WinAmp.</p>

	<p>The MIME type of these files is <sys>audio/x-scpls</sys> and they often look like: </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>

</page>

	<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><p><link xref="playing">Play</link></p></td><td><p>Starts the radio in a configured audio player</p></td></tr>
		<tr><td><p><link xref="recording">Record</link></p></td><td><p>Opens a terminal window and streamripper, which cuts the radio broadcast into individual mp3 songs.</p></td></tr>
		<tr><td><p><link xref="bookmarks">Bookmarks</link></p></td><td><p>Copy radio entry over into the <gui>bookmarks</gui> channel.</p></td></tr>
		<tr><td><p>Homepage</p></td><td><p>Most radio stations have a homepage. Open this in a web browser.</p></td></tr>
		<tr><td><p>Saving</p></td><td><p>A radio entry can be exported as .m3u or .pls file.</p></td></tr>
		<tr><td><p>Extensions<guiseq><gui/><gui/></guiseq></p></td><td><p>Some plugins add other features in this submenu.</p></td></tr>
		<tr><td><p>Editing</p></td><td><p>This command is in the <gui>Edit</gui> and context menu, allows to inspect and modify radio descriptions.</p></td></tr>
		<tr><td><p>Searching</p></td><td><p>You can get a radio list according to search criteria.</p></td></tr>
	</table>
	<p> Play, Record and Homepage also have buttons in the toolbar.</p>

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

        <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
        result list. This might take a few seconds. And it's not implemented
        for all channel plugins however.</p>

	<p>With <gui>Cache find</gui> would just look up entries in your
        already downloaded channel/genre lists.  This is sufficient when
        you're just looking for something previously seen/listended to.</p>


	</section>

</page>

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

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

	<title>Technical information</title>


	<section id="dependecies">
        <terms>
  	  <title>Dependencies</title>
          <item><p><link action="install:python">Python 2.7 or 3.x</link></p></item>
          <item><p><link action="install:python-gtk2">PyGtk or PyGI</link></p></item>
          <item><p>Gtk2 or Gtk3</p></item>
          <item><p><link action="install:python-requests">Requests/urllib3</link></p></item>
	</terms>
        <terms>
  	  <title>Soft dependencies</title>
          <item><p><link action="install:python-lxml">Python-LXML</link></p></item>
          <item><p><link action="install:python-pyquery">Python-PyQuery</link></p></item>
          <item><p>Python-Kronos</p></item>
          <item><p>Audacious</p></item>
	</terms>
	</section>


	<section id="config_files">