Internet radio browser GUI for music/video streams from various directory services.

โŒˆโŒ‹ โŽ‡ branch:  streamtuner2


configuration.html at [8147a96b12]

File help/html/configuration.html artifact 5ef065d671 part of check-in 8147a96b12


<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title>Configuration / Settings dialog</title>
<link rel="stylesheet" type="text/css" href="C.css">
<script type="text/javascript" src="jquery.js"></script><script type="text/javascript" src="jquery.syntax.js"></script><script type="text/javascript" src="yelp.js"></script>
</head>
<body><div class="page" role="main">
<div class="header"><div class="trails" role="navigation"><div class="trail">
<a class="trail" href="index.html" title="โ™ช Streamtuner2"><span class="media"><span class="media media-image"><img src="img/logo.png" class="media media-inline" alt="โ™ช"></span></span> Streamtuner2 </a>ย โ€บ <a class="trail" href="index.html#functions" title="Functions">Functions</a>ย ยป </div></div></div>
<div class="body">
<div class="hgroup"><h1 class="title"><span class="title">Configuration / Settings dialog</span></h1></div>
<div class="region">
<div class="contents">
<p class="p">
There are various options for streamtuner2, available under <span class="guiseq"><span class="gui">Edit</span>ย โ–ธ <span class="gui">Preferences</span></span> or via <span class="key"><kbd>F12</kbd></span>.
</p>
<p class="p"><span class="media"><span class="media media-image"><img src="img/configtabs.png" class="media media-inline" alt=""></span></span></p>
<div class="terms"><div class="inner">
<div class="title title-terms"><h2><span class="title">It's grouped into:</span></h2></div>
<div class="region"><dl class="terms">
<dt class="terms">๐Ÿ”Š <span class="link"><a href="#apps" title="Player application settings">Player</a></span>
</dt>
<dd class="terms"><p class="p">Associates media formats to audio player applications or recording tools.</p></dd>
<dt class="terms">โ˜‘ <span class="link"><a href="#gui" title="Display/GUI options">Options</a></span>
</dt>
<dd class="terms"><p class="p">Influences the display of all stream/station lists, and contains some
    behaviour and system settings.</p></dd>
<dt class="terms">๐Ÿ“ป <span class="link"><a href="#plugins" title="Channel and feature plugins and settings">Channel Plugins</a></span>
</dt>
<dd class="terms"><p class="p">Allows to enable or disable channel tabs. Each can have specific
    options, which can be configured here.</p></dd>
<dt class="terms">๐Ÿ”Œ <span class="link"><a href="#plugins" title="Channel and feature plugins and settings">Feature Plugins</a></span>
</dt>
<dd class="terms"><p class="p">Another class of plugins enables internal functions, or adds extra menu
    entries, or further configuration options.</p></dd>
<dt class="terms">๐Ÿ“ฆ <span class="link"><a href="pluginmanager2.html" title="Plugin Manager 2 - ๐Ÿ“ฆ Add">Add</a></span>
</dt>
<dd class="terms"><p class="p">The <span class="link"><a href="pluginmanager2.html" title="Plugin Manager 2 - ๐Ÿ“ฆ Add">Plugin Manager 2</a></span> adds another
    tab for updating or installing new plugins.</p></dd>
</dl></div>
</div></div>
</div>
<div id="apps" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Player application settings</span></h2></div>
<div class="region"><div class="contents">
<p class="p">MIME types are abstract identifiers for media types. <span class="var">Audio/mpeg</span> for
    example represents MP3 files, and <span class="var">audio/ogg</span> means OGG Vorbis.  And the player
    setting dialog simply associates an audio type with a playback application:</p>
<p class="p"><span class="media"><span class="media media-image"><img src="img/configapps.png" class="media media-inline" alt=""></span></span></p>
<div class="list"><div class="inner"><div class="region"><ul class="list">
<li class="list"><p class="p"><span class="link"><a href="config_apps.html" title="Audio players">Application names</a></span> are most
      always lowercase binary names.</p></li>
<li class="list"><p class="p"> 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. (Only works on U*ix-systems.)</p></li>
<li class="list">
<p class="p">After the application name, you can optionally use
      <span class="link"><a href="config_apps.html#placeholders" title="URL placeholders">a placeholder</a></span>:</p>
<div class="list"><div class="inner"><div class="region"><ul class="list">
<li class="list"><p class="p"><span class="var">%pls</span> โ†’ default format</p></li>
<li class="list"><p class="p"><span class="var">%m3u</span> โ†’ older scheme</p></li>
<li class="list"><p class="p"><span class="var">%xspf</span> โ†’ modern playlists,</p></li>
<li class="list"><p class="p"><span class="var">%srv</span> โ†’ for direct streaming URLs</p></li>
</ul></div></div></div>
</li>
<li class="list">
<p class="p">The format entries can specify generic or custom handlers:</p>
<div class="list"><div class="inner"><div class="region"><ul class="list">
<li class="list"><p class="p">Catch-all specifiers like <span class="var">*/*</span> or a generic
        <span class="var">audio/*</span> entry allow to configure a default
        player.</p></li>
<li class="list"><p class="p">While <span class="var">video/youtube</span> is specific to the Youtube
        channel.</p></li>
<li class="list"><p class="p">And <span class="var">url/http</span> a pseudo MIME type to configure a
        web browser (for station homepages).</p></li>
</ul></div></div></div>
</li>
<li class="list"><p class="p">In practice you only needed one entry for <span class="var">audio/*</span>
      and one for <span class="var">video/*</span>, both can use the same player even. 
      </p></li>
<li class="list"><p class="p"> You can remove existing entries by clearing both the Format
      field and its associated Application.  Add completely new associations
      through the emtpy line.  </p></li>
</ul></div></div></div>
<div class="links topiclinks"><div class="inner"><div class="region"><div class="linkdiv "><a class="linkdiv" href="config_apps.html" title="Audio players"><span class="title">Audio players</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Common applications to use as players.</span></a></div></div></div></div>
</div></div>
</div></div>
<div id="recording" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Recording Apps</span></h2></div>
<div class="region"><div class="contents">
<p class="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>
<div class="table"><div class="inner"><div class="region"><table class="table">
<tr>
<td><p class="p"><span class="var">audio/*</span></p></td>
<td style="border-left-style: solid;"><p class="p"><span class="cmd">xterm -e streamripper %srv</span></p></td>
</tr>
<tr class="shade">
<td style="border-top-style: solid;"><p class="p"><span class="var">video/youtube</span></p></td>
<td style="border-top-style: solid;border-left-style: solid;"><p class="p"><span class="cmd">xterm -e "youtube-dl %srv"</span></p></td>
</tr>
</table></div></div></div>
<p class="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.</p>
<div class="links topiclinks"><div class="inner"><div class="region"><div class="linkdiv "><a class="linkdiv" href="recording.html" title="Recording"><span class="title">Recording</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Save radio songs as MP3 files via streamripper.</span></a></div></div></div></div>
</div></div>
</div></div>
<div id="gui" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Display/GUI options</span></h2></div>
<div class="region"><div class="contents">
<div class="terms"><div class="inner">
<div class="title title-terms"><h3><span class="title">Display settings</span></h3></div>
<div class="region"><dl class="terms">
<dt class="terms">โ˜‘ Show bookmark star</dt>
<dd class="terms"><p class="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></dd>
<dt class="terms">โ˜‘ Save window states</dt>
<dd class="terms"><p class="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 <span class="guiseq"><span class="gui">Edit</span>ย โ–ธ <span class="gui">Save States</span></span>.</p></dd>
<dt class="terms">โ˜‘ Update window title</dt>
<dd class="terms"><p class="p">When switching channel tabs, the Streamtuner2 window title usually gets the current
      channel name appended (such as "- Shoutcast" or "- Xiph"). You can disable this if it
      looks confusing. (Requires a restart to fully take effect.)</p></dd>
<dt class="terms"><span class="link"><a href="favicon.html" title="Station favicons">โ†’ Favicon plugin options</a></span></dt>
<dd class="terms"></dd>
</dl></div>
</div></div>
<div class="terms"><div class="inner">
<div class="title title-terms"><h3><span class="title">Station loading</span></h3></div>
<div class="region"><dl class="terms">
<dt class="terms">โ˜‘ Prefer HTML traversing (PyQuery) over regex</dt>
<dd class="terms"><p class="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></dd>
<dt class="terms">๐Ÿ”Ÿ Limit stream number</dt>
<dd class="terms"><p class="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></dd>
<dt class="terms">โ˜‘ Retain deleted stations</dt>
<dd class="terms"><p class="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></dd>
<dt class="terms">โ˜‘ Update favouries from freshened URLs</dt>
<dd class="terms"><p class="p">Streaming URLs in bookmarked stations get renewed on category reloads/updates. This isn't
      very reliable, as often station titles change together with the streaming URLs.</p></dd>
<dt class="terms">โ˜‘ Save station lists after updates</dt>
<dd class="terms"><p class="p">After reloading (<span class="key"><kbd>F5</kbd></span>) the updated station lists are
      autoamtically saved. For favicon updates or drag and drop events this
      only happens automatically when this option is set.</p></dd>
</dl></div>
</div></div>
<div class="terms"><div class="inner">
<div class="title title-terms"><h3><span class="title">Playlist</span></h3></div>
<div class="region"><dl class="terms">
<dt class="terms">โ˜‘ Reuse .m3u/.pls files</dt>
<dd class="terms"><p class="p">When converting online station playlists,
      streamtuner2 creates temporary files like <span class="var">shoutcast.11539398391891.m3u</span> for
      your audio player.  It'll keep those files around in /tmp/streamtuner2 until you quit. 
      That speeds up switching between and reconnecting to a previous station.  It's in
      particular necessary when you use <span class="key"><kbd>โญ</kbd></span> or <span class="key"><kbd>โช</kbd></span> directly in your player. 
      For <span class="var">%pls</span> references your player typically usues the online-only playlist
      files anyway.  If you disable this option, then converted pls/m3u/xspf files get
      recreated repeatedly.</p></dd>
<dt class="terms">โ˜‘ Forgo any playlist conversion</dt>
<dd class="terms">
<p class="p">Per default most server playlists (be they .pls or .m3u, .xpsf) are converted.
      All player/recording apps receive a default <span class="var">%pls</span> file normally.
      Set this option to disable any such placeholders from the Player tab, and avoid
      streamtuner2 pre-downloading any m3u/pls/xspf. Instead your audio  player gets passed
      the literal server/playlist streaming URL then.</p>
<div class="note" title="Note"><div class="inner"><div class="region"><div class="contents"><p class="p">Note that this is only
      a minor speedup, but may trip up some applications. A few channel sources don't
      even provide standard stream addresses and playlists. (Jamendo albums for example really
      need pre-conversion; no audio player can deal with such custom JSON playlists).
      In short: you don't normally want to enable this flag - unless you run into problems
      with streamtuner2 taking too long, or when it hang by accidentially downloading streams
      itself.</p></div></div></div></div>
</dd>
</dl></div>
</div></div>
<div class="terms"><div class="inner">
<div class="title title-terms"><h3><span class="title">System</span></h3></div>
<div class="region"><dl class="terms">
<dt class="terms">๐Ÿ”  Temporary files</dt>
<dd class="terms"><p class="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.  In recent
      versions streamtuner2 will create a <span class="file">/tmp/streamtuner2</span> directory for itself. 
      (You cannot set just `/tmp` anymore, because that will be mapped to the longer name. 
      You can trick the old behaviour with `/tmp/.` however.  Don't do that unless you have a
      reason).</p></dd>
<dt class="terms">๐Ÿ”  Config directory</dt>
<dd class="terms"><p class="p">Is where streamtuner2 keeps its <span class="file">settings.json</span> and channel caches, favicons, etc.
      You can't set this in the config dialog. This is just for display. Set the <span class="sys">XDG_CONFIG_HOME</span>
      environment variable to adapt.</p></dd>
<dt class="terms">โ˜‘ Enable debug messages</dt>
<dd class="terms"><p class="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></dd>
<dt class="terms">โ˜‘ Disable threading</dt>
<dd class="terms"><p class="p">Now "threading" is a somewhat technical term.  It
      means that an application runs different tasks internally at the same time.  It's used
      for snappier interfaces.  However, it's also difficult to get right at times.  In
      Streamtuner2 some concurrent tasks conflict with updating the Gtk3 user interface. 
      Which is why the application may crash even on reloading station lists or when switching
      between categories too quickly.  This is only an issue for Python3 on Gtk3 with
      streamtuner2.  In such cases you can disable the concurrent-tasking mode.  The GUI will
      appear slower at times, and freeze between fetching lists, but remains stable on the
      upside.  There's also a command line flag <span class="cmd">--nt</span> to enable this workaround.</p></dd>
</dl></div>
</div></div>
</div></div>
</div></div>
<div id="plugins" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Channel and feature plugins and settings</span></h2></div>
<div class="region">
<div class="contents">
<div class="table"><div class="inner"><div class="region"><table class="table"><tr>
<td><p class="p">The <span class="key"><kbd>๐Ÿ“ป Channels</kbd></span> tab shows all available directory
    services.</p></td>
<td><p class="p">While the <span class="key"><kbd>๐Ÿ”Œ Features</kbd></span> group provides internal or menu
    enhancements.</p></td>
</tr></table></div></div></div>
<p class="p">Disabling or enabling a plugin however requires a restart of Streamtuner2
    to take effect. (Unless the <span class="link"><a href="pluginmanager2.html" title="Plugin Manager 2 - ๐Ÿ“ฆ Add">Plugin Manager 2</a></span>
    is enabled, with its <span class="key"><kbd>๐Ÿ“ฆ Add</kbd></span> tab visible.)</p>
<p class="p"><span class="media"><span class="media media-image"><img src="img/configplugins.png" class="media media-inline" alt=""></span></span></p>
<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"><span class="media"><span class="media media-image"><img src="img/channel_internet_radio.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_jamendo.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_myoggradio.png" class="media media-inline" alt=""></span></span> MyOggRadio</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Open source stream directory.</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="radiobrowser.html" title="Radio-Browser"><span class="title"><span class="media"><span class="media media-image"><img src="img/channel_radiobrowser.png" class="media media-inline" alt=""></span></span> Radio-Browser</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Community-driven streaming directory</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="radionomy.html" title="Radionomy"><span class="title"><span class="media"><span class="media media-image"><img src="img/channel_radionomy.png" class="media media-inline" alt=""></span></span> Radionomy</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Large internet streaming provider</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="reddit.html" title="Reddit"><span class="title"><span class="media"><span class="media media-image"><img src="img/channel_reddit.png" class="media media-inline" alt=""></span></span> Reddit</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Music subreddit posts</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="somafm.html" title="SomaFM"><span class="title"><span class="media"><span class="media media-image"><img src="img/channel_somafm.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_surfmusik.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_tunein.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_xiph.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_youtube.png" class="media media-inline" alt=""></span></span> 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"><span class="media"><span class="media media-image"><img src="img/channel_filtermusic.png" class="media media-inline" alt=""></span></span> filtermusic</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Selection of the best radio stations</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="contrib_channels.html" title="โ†’ Contrib/Extra Channels"><span class="title">โ†’ Contrib/Extra Channels</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Downloadable channel plugins</span></a></div>
<div class="linkdiv "><a class="linkdiv" href="contrib_features.html" title="โ†’ Feature plugins"><span class="title">โ†’ Feature plugins</span><span class="linkdiv-dash"> โ€” </span><span class="desc">Additional feature plugins</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 ">
<a href="pluginmanager2.html" title="Plugin Manager 2 - ๐Ÿ“ฆ Add">Plugin Manager 2 - <span class="key"><kbd>๐Ÿ“ฆ Add</kbd></span> </a><span class="desc"> โ€” User plugin installation</span>
</li></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),
    please have a look into the channels directory /usr/share/streamtuner2/channels/ and corresponding
    *.py files. These are somewhat readable even to non-programmers, and sometimes contain more information.</p></div></div></div></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"><h2><span class="title">More Information</span></h2></div>
<div class="region"><ul><li class="links "><a href="index.html#functions" title="Functions">Functions</a></li></ul></div>
</div></div></div>
</div>
</div>
<div class="clear"></div>
</div>
<div class="footer"></div>
</div></body>
</html>