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

<info>
	<link type="guide" xref="index#extra"/>
        <link type="guide" xref="pluginmanager2"/>
        <link type="guide" xref="configuration#plugins"/>
	<!--link type="seealso" xref="index#channels"/-->
        <desc>Additional feature plugins</desc>
</info>
<title>→ Feature plugins</title>

<section>
<title><key>🔌 Feature</key> plugins and settings</title>

<p>Extra functionality and behaviour changes are available in
the <key>🔌 Feature</key> <link xref="configuration">configuration</link>
section.</p>


  <section>
  <title>🔌 Filter Bitrate</title>
  <p>Some channels provide lower-quality audio streams. In particular
  Xiph lists some awful radio stations. And this plugin helps filtering
  those out of station lists.</p>
  <list>
   <item><p>MP3 streams often start to sound okay at 96kbit/s.</p></item>
   <item><p>Whereas OGG Vorbis or AAC are sometimes acceptable at 64kbit/s already.</p></item>
  </list>
  <p>Note that you may end up with empty channel lists
  altogether if you set these options too high. Some channels provide all
  their streams with 64kbit/s only.</p>
  </section>

  <section>
  <title>🔌 Channel toolbar link</title>
  <p>Adds a toolbar entry which shows the current channel/directory
  service title and its homepage link. Such as:</p>
  <code><span style="bold">    ▶    ●    🏠     Shoutcast</span>
  play rcrd  hmpg   <link href="http://shoutcast.com/">//shoutcast.com/</link>
  </code>
  <p>It depends on the "update window title" option being enabled.</p>
  </section>

  <section>
  <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>
  <list>
   <item><p>This is of course intended primarily for saving your bookmarks.</p></item>
   <item><p>And it allows to import radio lists into any other music player  or playlist collection/management app (such as Rhythmbox).</p></item>
   <item><p>You can set the desired playlist format in the file saving dialog that pops up.</p></item>
  </list>
  </section>

  <section>
  <title>🔌 RadioTray hook</title>
  <p>This plugin enables an extra category in the <key>bookmarks</key> tab.
  It shows bookmarked stations from the RadioTray application, if that's
  installed. Additionally it adds a context option to save new stations
  from Streamtuner2 to RadioTray. The mapping option influences if added
  radios are recategorized in RadioTray.</p>
  <note><p> Please see the Wiki for further <link href="http://fossil.include-once.org/streamtuner2/wiki/radiotray">setup instructions</link>.</p></note>
  </section>

  <section>
  <title>🔌 User Agent Switcher</title>
  <p>This plugin merely masks Streamtuner2 as an ordinary web browser when retrieving station lists.</p>
  <list>
   <item><p> It's technically unneeded, as ST2 isn't stressful to directory websites and not blocked anywhere. </p></item>
   <item><p>It's only useful as additional privacy feature really, but shouldn't be used habitually. </p></item>
  </list>
  </section>

  <section>
  <title>🔌 History</title>
  <p>Provides the small "history" category in the bookmarks tab. The length of
  which is configurable (defaults to 20).</p>
  </section>

  <section>
  <title>🔌 Links to directory services</title>
  <p>Adds a list of weblinks to other online music services in the "links" category
  within the bookmarks tab.</p>
  </section>

  <section>
  <title>🔌 Recording options</title>
  <p>Overrides the <gui style="button"><key>●</key> record</gui> button to
  not start streamripper right away. Instead it prompts for additional
  settings before proceeding.</p>
  <p>Common options are conveniently listed and saveable on a per-station
  basis. Which allows to suppress stream splitting (record just one long
  MP3 file), or file naming schemes.</p>
  <p>Additionally it supports options of following recording backends:</p>
  <list>
   <item><p><app>streamrippper</app> - for radio stations</p></item>
   <item><p><app>fPls/fIcy</app> - for radio stations</p></item>
   <item><p><app>youtube-dl</app> - video downloads</p></item>
   <item><p><app>wget</app> - plain MOD/ZIP files</p></item>
  </list>
  <p>The plugin provides config options of its own, such as a default
  output directory, or how many / how detailed options to show.</p>
  </section>

</section>

<section>
 <title>Core feature plugins</title>
 <p>Following plugins are covered more in-depth in the according manual
 sections:</p>
 <list>
   <item><p><link xref="dragndrop">🔌 Drag and Drop</link></p></item>
   <item><p><link xref="favicon">🔌 Favicons</link></p></item>
   <item><p><link xref="global_key">🔌 Global key shortcut</link></p></item>
   <item><p><link xref="timer">🔌 Timer</link></p></item>
   <item><p><link xref="specbuttons">🔌 Specbuttons</link></p></item>
 </list>
 <p>The "<link xref="search">search</link>",
 "<link xref="configuration">configwin</link>" and
 "<link xref="edit">streamedit</link>" plugins are considered
 built-ins and cannot be disabled.</p>
</section>


<section id="contrib">
<title>Downloadable contrib/ feature plugins</title>

<p>The <link xref="pluginmanager2">Plugin Manager</link> lists more
downloadable feature plugins in the <key>📦 Add</key> tab.</p>

  <section>
    <subtitle>🔌 Soundcloud streaming</subtitle>
    <p>Enables playback of soundcloud.com links, which are only used
    in the <link xref="channel_reddit">📻 Reddit</link> plugin currently.
    Homepage links are transformed into direct MP3 streaming addresses
    on playback.</p>
    <note><p>Depends on python-soundcloud, which you can install per
    <cmd>pip install soundcloud</cmd>.</p></note>
    <p> Alternatively you could configure an external player like <link
    href="http://github.com/rekado/soundCLI">soundcli</link> of course.
    Use the pseudo type "audio/soundcloud" for the player settings table.</p>
  </section>

  <section>
    <subtitle>🔌 dev_faulthandler</subtitle>
    <p>This is a pure development plugin, meant to debug ST2 crashes.</p>
  </section>

  <section>
    <subtitle>🔌 bookmarks_show_extra</subtitle>
    <p>Is a slim UI adaption to show the `extra` field in the bookmarks
    channel. This field can contain user comments, but is used per default
    to store the originating channel in.</p>
  </section>

  <section>
    <subtitle>🔌 new_station</subtitle>
    <p>(Still unfinished). Small plugin to provide an "Add station..."
    menu entry. Note that ST2 is not meant as playlist manager, which is
    why this isn't a built-in feature. However, it's oft-requested anyway.</p>
  </section>

  <section>
    <subtitle>🔌 tmp_clean_multiurl</subtitle>
    <p>Strips extra space-separate URLs from station list. (Currently only
    required for 📻 RadioSure channel. Later ST2 versions will likely support
    such entries per default again).</p>
  </section>

  <section>
    <subtitle>🔌 Gtk theme setting</subtitle>
    <p>You can set a custom theme for Streamtuner2 using the gtk_theme
    plugin. It ought to list all available themes for Gtk2 or Gtk3 in
    the according dropdown box. The "apply instantly" option may help
    with enabling them right away.</p>
    <note style="bug"><p>Take note that not all Gtk themes will work,
    and some might crash streamtuner2.</p></note>
    <p>If you see ST2 hang at startup, then either edit
    <file>settings.json</file> to remove the <cmd>"theme": "..."</cmd>
    name, or use the <code><app>streamtuner2 -d gtk_theme</app></code>
    start command.</p>
    <p>To install/enable themes just for ST2, you could create a
    <file>~/.config/streamtuner2/themes/</file> folder, or one below
    <file>/usr/share/streamtuner2/themes/</file> even.</p>
  </section>

  <section>
    <subtitle>🔌 stop_button</subtitle>
    <p>Adds the toolbar button to stop streamripper/fpls - same as in
    streamtuner1. Has become kind of redundant due to the newer
    <link xref="specbuttons">🔌 specbuttons</link> plugin.</p>
  </section>

  <section>
    <subtitle>🔌 Config prefs</subtitle>
    <p>Introduces three main menu entries:</p>
    <list>
     <item>
       <title><guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Config save</gui></guiseq></title>
       <p>Saves the streamtuner2.json file verbatim.</p>
     </item>
     <item>
       <title><guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Config restore</gui></guiseq></title>
       <p>While the file dialog incorrectly says and behaves like a file
       save dialog, it does in fact open and load the JSON file.</p>
     </item>
     <item>
       <title><guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Config delete</gui></guiseq></title>
       <p>The config reset additionally opens the settings window and
       requires you to hit <key>Save</key> for confirmation. In any case
       ST2 should also be restarted afterwards to unload disabled plugins.</p>
     </item>
    </list>
  </section>

  <section>
    <subtitle>🔌 Cache reset</subtitle>
    <p>Adds a <key>Cache reset</key> button in the Options tab of
    the settings window. It shows how much space all cache files of
    ST2 occupy. Usually the icons take up most, while the channel/station
    archive is often just 2-3 MB. Temporary m3u/pls files can also
    be deleted. → Tick the parts you want to have removed before hitting
    the reset button.</p>
  </section>

  <section>
    <subtitle>🔌 OGG Icon</subtitle>
    <p>Introduces small state icons to make higher-quality Vorbis and
    Opus stations stand out. (Not all channels provide exact format
    information, so you'll mostly notice for Jamendo and Xiph.) </p>
  </section>

  <section>
    <subtitle>🔌  Win32/subprocess</subtitle>
    <p>Wraps the player/application exec() method. Instead of simple
    shell execution, uses the Python subprocess module or win32 API
    functions. This is mostly unneeded on Linux (kills a few features
    even), but avoids the cmd.exe popup and delay on Windows. Highly
    experimental at the moment.</p>
  </section>

</section>


</page>