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

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

	<title>Dirble</title>
        <subtitle><link href="http://dirble.com/">//dirble.com/</link></subtitle>
	
	<p>Dirble.com is another radio station directory, made up of
	user-contributed content, and automatic streaming server polling.</p>

	<p>Dirble.com is another radio station directory, based on
	user-contributed entries and automatic streaming server polling.</p>

        <list>
	<p>It provides a JSON API, which as of v2 has a lot of unneeded meta
         <item><p>Provides a JSON API, which in v2 is easy to extract from.</p></item>
	information and internal ids. But it's actually nicer to scan, and
	contains even station homepages now.</p>

        <note><p>The config option for a custom API key is perhaps
        redundant. Should streamtuner2 -D however reveal an error, you
        can however configure your own account there.</p></note>
         <item><p>List contain even station homepages mostly.</p></item>
         <item><p>And the channel plugin selects among the available
         streaming URLs based on format (Ogg, AAC, preferred over MP3) and
         maximum bitrate.</p></item>
        </list>
	
        <note><p>There's a hidden config option for a custom API key.
        It's perhaps redundant. Should streamtuner2 -D however reveal an error,
        you can however configure your own account in <file>settings.json</file>.
        </p></note>
</page>

	<link type="guide" xref="configuration#plugins"/>
        <desc>Selection of the best radio stations</desc>
</info>

	<title>filtermusic</title>
        <subtitle><link href="http://filtermusic.net/">//filtermusic.net/</link></subtitle>


	<p>Filtermusic summarizes all the common genres, but is primarily
	focused on electro/dance/pop stations.  It elects on listener
	popularity and freshness or something.</p>
	focused on electro/dance/pop stations.</p>

        <list>
         <item><p>There's around a dozen categories with 20-30 radios each.</p></item>
         <item><p>Prioritizes stations on listener popularity and freshness or something.</p></item>
         <item><p>The plugin fetches a XML list of stations, or extracts from the homepage.</p></item>
        </list>

	<p>Which is why there are just a dozen categories with around 20-30
	stations each. Still useful if you don't like to browse around
	a lot.</p>
	<p>Most useful if you don't like to browse around, and want to
	listen to most popular stations.</p>

        <section id="options">	
        <title>Configuration</title>
	<p>Like the Xiph plugin this channel provides two/three fetch modes.</p>
	<note><p>
	There's no speed or feature differences this time. You might prefer
	the buffered mode, as it reduces update requests, but still allows
	refreshing lists.</p></note>
	</section>

</page>

        <desc>Large radio directory from the UK.</desc>
</info>

	<title>Internet-Radio</title>
        <subtitle><link href="http://internet-radio.com/">//internet-radio.com/</link></subtitle>
        
	<p>Internet-Radio.com is a broad alternative to Shoutcast.</p>

	<list>
 	 <item><p>It has regained station homepages for most entries again.</p></item>
 	 <item><p>Genres are similiar to Shoutcast.</p></item>
 	 <item><p>Updating station lists is comperatively fast.</p></item>
 	 <item><p>Uses HTML extraction (regex or pyquery) internally.</p></item>
 	</list>

        <section id="options">
        <title>Configuration</title>
	<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>
	links to retrieve.  Instead of stream numbers, it only counts pages.
	Which however speeds up processing now.</p>
	</section>

</page>

	<link type="guide" xref="configuration#plugins"/>
        <desc>Creative Commons music and artist hub.</desc>
</info>

<title>Jamendo</title>
<subtitle><link href="http://jamendo.com/">//jamendo.com/</link></subtitle>

<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>Jamendo is a Creative Comments licensing oriented music distributor. It
hosts audio files for individual musicians and artists.  It allows to list
albums, playlists, and individual tracks by genre.</p>

<list>
<p>The new Jamendo v3.0 is now utilized. It allows to list albums,
  <item><p>The new Jamendo v3.0 is now utilized, which is JSON based and easy to extract.</p></item>
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>
  <item><p>Its radio list is static. It loops over randomized songs from each genre.</p></item>
  <item><p>There's a custom JSON playlist extractor (JAMJSON), to avoid preloading stream URLs for feeds/albums. While tracks/genre lists contain direct streaming addresses already.</p></item>
  <item><p>Instead of favicons, streamtuner2 can fetch slightly larger album or track covers.</p></item>
</list>

<p>Tracks and albums can be downloaded free of charge (Creative Commons). Yeah, imagine that.</p>

<section id="options">
<title><link xref="configuration">Config</link> options</title>
<terms>
   <title>System</title>
   <item>
     <title>Streaming format</title>

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

<title>MyOggRadio</title>
<subtitle><link href="http://myoggradio.org/">//myoggradio.org/</link></subtitle>          

<p><link href="http://ehm.homelinux.org/MyOggRadio/">MyOggRadio</link> is an open
<p><link href="http://MyOggRadio.org/">MyOggRadio</link> is an open
source internet radio directory project.</p>

<p>Since it provides its station list as JSON it's very well supported.</p>

<section>
  <title>Sharing is caring</title>
  <p>To help with populating the directory further,

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
	<link type="guide" xref="configuration#plugins"/>
        <desc>Large internet streaming provider</desc>
</info>

	<title>Radionomy</title>
	<subtitle><link href="http://radionomy.com/">//radionomy.com/</link></subtitle>
<title>Radionomy</title>
<subtitle><link href="http://radionomy.com/">//radionomy.com/</link></subtitle>

	<p>Radionomy is an internet radio streaming provider, orginally
	founded in Belgium.  It commands a pretty big slice of the worldwide
	internet radio stuff these days. - It took over Shoutcast.com for
	instance.</p>
<p>Radionomy is an internet radio streaming provider, orginally
founded in Belgium.  It commands a pretty big slice of the worldwide
internet radio stuff these days. - It took over Shoutcast.com for
instance.</p>

<list>
	<p>Their primary directory on Radionomy.com only lists stations
	which radionomy itself hosts streaming servers for.  It's over 6000
	already.  Both listening and station hosting are free (given agreement
	to autoplay advertisements, and a minimum quota of daily listeners). 
	Radionomy is therefore pretty popular and growing.</p>
	
  <item><p>Its directory contains over 6000 stations already, all of them hosted by Radionomy directly.</p></item>
  <item><p>This plugin uses a mixture of RegExp/DOM extraction, JSON reading, and simulated AJAX queries to fetch station lists.</p></item>
  <item><p>Station logos are 25x25px large, and directly fetched from radionomy.com as well.</p></item>
</list>

<p>Both listening and station hosting are free (given agreement
to autoplay advertisements, and a minimum quota of daily listeners). 
Radionomy is therefore pretty popular and growing.</p>

	<p>The extraction method in streamtuner2 uses a mix of RegExp,
	DOM traversal, and JSON extraction, with some AJAX updating spiced
	in. It closely follows the website scheme to fetch station lists.
	Instead of favicons smaller station logos are displayed (25px
	in contrast to the usual 16px).
	</p>
	
	<section id="options">
	 <title>Configuration</title>
	 
         <p> You can configure the number of pages it'll try (<key>3</key> by
  	 default) to influence the length of station lists.</p>
	
	 <p> And the song title updating ("<key>OnAir Updates</key>") can be disabled.
	 Future versions of this channel plugin might poll it automatically,
	 and keep the station list auto-updated.</p>
	
	 </section>

<section id="options">
 <title>Configuration</title>
 
 <p> You can configure the number of pages it'll try (<key>3</key> by
 default) to influence the length of station lists.</p>

 <p> And the song title updating ("<key>OnAir Updates</key>") can be disabled.
 Future versions of this channel plugin might poll it automatically,
 and keep the station list auto-updated.</p>

</section>

</page>

	<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>Stream links are plain <link xref="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>

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

<info>
	<link type="guide" xref="index#channels"/>
	<link type="guide" xref="channels#list"/>
        <link type="guide" xref="configuration#channels"/>
        <link type="guide" xref="configuration#plugins"/>
        <desc>Set of radio stations</desc>
</info>

	<title>SomaFM</title>
	<subtitle><link	href="http://somafm.com/">//somafm.com/</link></subtitle>

	<p>SomaFM is a small radio station network. It provides its own

	<title>SurfMusic</title>
	<subtitle><link	href="http://surfmusic.de/">//surfmusic.de/</link></subtitle>

	<p><link href="http://surfmusic.de/">SurfMusic</link> is a user-collection of
        internet radios. It's grouped by genres, or locations / countries.</p>

        <list>
        <p>It's both pretty large and rather quick to extract listings from. And it mostly
        includes station homepage links.</p>
          <item><p>It's both pretty large and rather quick to extract listings from.</p></item>
          <item><p>Pretty much all entries already contain station homepages.</p></item>
          <item><p>This channel plugin uses raw RegExp extraction.</p></item>
        </list>

        <note style="bug"><p>The MusicTV and NewsTV sections also return results, but those are mostly
        web-based video stations. Some of them are outdated links even.</p></note>

<section id="options">
  <title>Channel options.</title>
  <terms>

        <desc>Wiki list of radio stations</desc>
</info>

	<title>UbuntuUsers</title>
	<subtitle><link	href="http://ubuntuusers.de/">//ubuntuusers.de/</link></subtitle>

	<p>There's a manually curated list of radio stations in the
	UbuntuUsers.de Wiki. Like the origin website, most entries are
	UbuntuUsers.de Wiki.</p>
	German or European stations.</p>

	<p>So this is more of an example plugin, as it's not a huge list
	of course. It's just here really, because the Wiki markup is
	
        <list>
          <item><p>Like the origin website, most entries are German or European stations.</p></item>
          <item><p>So this is more of an example plugin, as it's not a huge list.</p></item>
          <item><p>RegExp are used for extraction, because the Wiki markup is rather well-maintained and consistent.</p></item>
	pretty well-written and easy to parse.</p>
	
        </list>

	<note><p>There's also a small streaming TV list. But most entries
	aren't really accessible (anymore) without command line tools. 
	(Which that very Wiki page covers in detail.)</p></note>

</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>
	<subtitle><link	href="http://dir.xiph.org/">//dir.xiph.org/</link></subtitle>
<title>Xiph.org</title>
<subtitle><link href="http://dir.xiph.org/">//dir.xiph.org/</link></subtitle>

	<p>Xiph.org is a non-profit organization, which maintains and
	promotes the OGG streaming format, and develops audio compression
	schemes such as Vorbis, FLAC, Opus, or the Theora video encoding
	format.  It also hosts a list of ICEcast streaming stations. ICEcast
<p>Xiph.org is a non-profit organization which develops and maintains
various audio- and video-related standards.</p>

<list>
  <item><p>For example the OGG streaming/multiplexing format.</p></item>
  <item><p>Audio compression schemes like Vorbis, Speex, FLAC, Opus.</p></item>
  <item><p>Video encoding formats like Theora, Tarkin, Dirac.</p></item>
  <item><p>The ICEcast streaming server is an alternative to SHOUTcast.</p></item>
	is their non-commercial pendant to the SHOUTcast server.</p>
  <item><p>And the more modern .xspf (and .jspf) playlist format, which is used by all channel entries.</p></item>
</list>

        <p>There are different ways for streamtuner2 to retrieve the station
        lists available on dir.xiph.org.  That's because this is a primary
        plugin, and fallback solutions therefore important.  Each fetching
        mode has its own advantages and drawbacks though.</p>
<p>There are different ways for streamtuner2 to retrieve the station
lists available on dir.xiph.org.  That's because this is a primary
plugin, and fallback solutions therefore important.  Each fetching
mode has its own advantages and drawbacks though.</p>

        <p>Xiph also uses the .xspf playlist format, instead of just the
        more ancient Shoutcast .pls stream links.</p>

<section id="options">
  <title>Channel options.</title>
  <title>Channel fetch mode option</title>
  <terms>
  <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>
  <item>
    <title><code>Fetch mode</code></title>
    <p>There are now three options to retrieve Xiph directory stations.</p>
  <p>There are now three options to retrieve Xiph directory stations.</p>
    <p></p>
      <terms>
      <item>
        <title><code>Cache JSON</code></title>
        <p>There's a caching server specifically for streamtuner2. It fixes
        Xiphs quirky JSON API, and provides a simpler interface. It can't
        correct the invalid encodings however, which is why you see ????
        question marks a lot. This method does not reveal station homepages,
        but enables the channel/server search.</p>
      </item>
  <terms>
  <item>
    <title><code>Cache JSON</code></title>
    <p>There's a caching server specifically for streamtuner2. It fixes
    Xiphs quirky JSON API, and provides a simpler interface. It can't
    correct the invalid encodings however, which is why you see ????
    question marks a lot. This method does not reveal station homepages,
    but enables the channel/server search.</p>
  </item>
      <p></p>
      <item>
        <title><code>Clunky YP.XML</code></title>
        <p>The "yellow pages" YP.XML contains the full list of all known
        ICEcast streaming servers. It's however quite bulky and super slow
        to download. It furthermore clogs up a lot of memory, and requires
        manual searching (only cache search works). Which is why streamtuner2
        is trying hard to avoid it. It doesn't contain station homepages either.
        </p>
        <p>It's only still an option, because it's likely to remain accessible
        after Xiph.org rewrites their directory service. (Which though is
        getting delayed since a few years already.)
        You can set the special "buffy" mode in your <file>settings.json</file>
        to keep the whole YP.XML in memory. Which avoids the
        slow station list download/unpacking.
        </p>
      </item>
  <item>
    <title><code>Clunky YP.XML</code></title>
    <p>The "yellow pages" YP.XML contains the full list of all known
    ICEcast streaming servers. It's however quite bulky and super slow
    to download. It furthermore clogs up a lot of memory, and requires
    manual searching (only cache search works). Which is why streamtuner2
    is trying hard to avoid it. It doesn't contain station homepages either.
    </p>
    <p>It's only still an option, because it's likely to remain accessible
    after Xiph.org rewrites their directory service. (Which though is
    getting delayed since a few years already.)
    You can set the special "buffy" mode in your <file>settings.json</file>
    to keep the whole YP.XML in memory. Which avoids the
    slow station list download/unpacking.
    </p>
  </item>
      <p></p>
      <item>
        <title><code>Forbidden fruits</code></title>
        <p>As new alternative, you can let ST2 directly scrape the station
        lists from dir.xiph.org (like it does for other channels).  This is
        something which Xiph doesn't approve of.  But the drawbacks of their
        alternative offerings are too severe and user-unfriendly; which is
        why there's this raw HTML extraction mode now.</p>
        <p>The website listings contain full station homepages and a few
        more extras.  In this mode we can even acceess the XSPF playlist
        formats directly.  Both, the server search function, or browsing by
        audio/video format are supported.  </p>
        <note><p>A miximum of 100 entries get fetched in this mode however
        (which is 5 pages á 20 entries).</p></note>
      </item>
    </terms>
  <item>
    <title><code>Forbidden fruits</code></title>
    <p>As new alternative, you can let ST2 directly scrape the station
    lists from dir.xiph.org (like it does for other channels).  This is
    something which Xiph doesn't approve of.  But the drawbacks of their
    alternative offerings are too severe and user-unfriendly; which is
    why there's this raw HTML extraction mode now.</p>
    <p>The website listings contain full station homepages and a few
    more extras.  In this mode we can even acceess the XSPF playlist
    formats directly.  Both, the server search function, or browsing by
    audio/video format are supported.  </p>
    <note><p>A miximum of 100 entries get fetched in this mode however
    (which is 5 pages á 20 entries).</p></note>
  </item>
  </terms>
  </item>
  </terms>
  <p>The filter by bitrate option is now a generic plugin.</p>
</section>

</page>

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

<info>
	<link type="guide" xref="index#extra"/>
        <desc>Exporting a whole category as .pls.</desc>
</info>

	<title>Export all stations</title>

	<p>There's an "Export All" plugin available. It adds an entry under
	<guiseq><gui>Main menu</gui> <gui>Extensions</gui> <gui>Export all stations</gui></guiseq>.
	Which allows to export all stations from the currently visible channel category.</p>
	
	<p>This is of course intended primarily for saving your bookmarks.
	And it allows to import radio lists into any other music player
	or playlist collection/management app (such as Rhythmbox).</p>

	<section id="configuration">
	<title>Configuration option</title>
	<p>You can set the default export format in the settings dialog
	<key>F12</key>.</p>
	<p>It supports all common export formats now, with .PLS being the
	default.</p>
	</section>

</page>

<title>Station favicons</title>

<p>Per default you'll get a small logo / icon for any station
with a homepage link. They're automatically fetched and displayed
as soon as you play a radio entry.</p>

<list>
<p>This functionality meanwhile resides in a plugin. It's available in the
<key>🔌 Features</key> <link xref="configuration">configuration</link> tab. 
You can disable it as whole if unneeded.  Most configuration options are now
collected there.</p>
  <item><p>This functionality meanwhile resides in a plugin.</p></item>
  <item><p>It's available in the <key>🔌 Features</key> <link xref="configuration">configuration</link> tab.</p></item>
  <item><p>Most configuration options are now collected there.</p></item>
</list>

<p>Some channels (Jamendo or Radionomy) provide small album previews
or banners (Punkcast) even. Whereas normal favicons are just 16x16
or banners even. Whereas normal favicons are just 16x16 pixel images.</p>
pixel images.</p>

<p>Downloaded image files are meanwhile all sanitized (internally
<note><p>Downloaded image files are meanwhile all sanitized (internally
converted to ensure they're really image files).
Albeit that's not strictly necessary for modern Gtk versions. (But
better safe than sorry).
Images are kept in the <file>~/.config/streamtuner2/icons</file> directory.
</p>
</p></note>


<section id="configuration">
<title>Configuration options</title>

<terms>
  <item>

<p class="p">Each plugin can have its own little list of extra options. They'll be
    applied right away for already active channel/feature plugins.</p>
<div class="links topiclinks"><div class="inner"><div class="region">
<div class="linkdiv "><a class="linkdiv" href="internet_radio_org_uk.html" title="Internet-Radio"><span class="title">Internet-Radio</span><span class="linkdiv-dash"> — </span><span class="desc">Large radio directory from the UK.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="jamendo.html" title="Jamendo"><span class="title">Jamendo</span><span class="linkdiv-dash"> — </span><span class="desc">Creative Commons music and artist hub.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="myoggradio.html" title="MyOggRadio"><span class="title">MyOggRadio</span><span class="linkdiv-dash"> — </span><span class="desc">Open source stream directory.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="radionomy.html" title="Radionomy"><span class="title">Radionomy</span><span class="linkdiv-dash"> — </span><span class="desc">Large internet streaming provider</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="somafm.html" title="SomaFM"><span class="title">SomaFM</span><span class="linkdiv-dash"> — </span><span class="desc">Set of radio stations</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="surfmusik.html" title="SurfMusic"><span class="title">SurfMusic</span><span class="linkdiv-dash"> — </span><span class="desc">International radio listings.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="tunein.html" title="TuneIn"><span class="title">TuneIn</span><span class="linkdiv-dash"> — </span><span class="desc">Radio and Podcast directory.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="xiph.html" title="Xiph.org"><span class="title">Xiph.org</span><span class="linkdiv-dash"> — </span><span class="desc">ICEcast radio directory.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="youtube.html" title="Youtube"><span class="title">Youtube</span><span class="linkdiv-dash"> — </span><span class="desc">Youtube music/video listings.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="filtermusic.html" title="filtermusic"><span class="title">filtermusic</span><span class="linkdiv-dash"> — </span><span class="desc">Selection of the best radio stations</span></a></div>
</div></div></div>
</div>
<div class="sect sect-links" role="navigation">
<div class="hgroup"></div>
<div class="contents"><div class="links guidelinks"><div class="inner">
<div class="title"><h3><span class="title">More Information</span></h3></div>
<div class="region"><ul><li class="links ">
<div class="region"><ul>
<li class="links ">
<a href="pluginmanager2.html" title="Plugin Manager 2">Plugin Manager 2</a><span class="desc"> — User plugin installation</span>
</li>
<li class="links ">
<a href="contrib_channels.html" title="→ Contrib/Extra Channels">→ Contrib/Extra Channels</a><span class="desc"> — Downloadable channel plugins</span>
</li>
<li class="links ">
<a href="contrib_features.html" title="→ Feature plugins">→ Feature plugins</a><span class="desc"> — Additional feature plugins</span>
</li>
</li></ul></div>
</ul></div>
</div></div></div>
</div>
</div>
</div></div>
<div id="note" class="sect"><div class="inner">
<div class="hgroup"></div>
<div class="region"><div class="contents"><div class="note" title="Note"><div class="inner"><div class="region"><div class="contents"><p class="p">If you want to find out more about the short option descriptions (most settings are checkboxes),