<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>
<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">
<title>Display/GUI options</title>
<terms>
<title>Display settings</title>
<item>
<title>Display favicons</title>
<p>The options for the favicons define if station entries should show little icons.
Not all stations have one, so you might as well turn this off to conserve a little memory.</p>
</item>
<item>
<title>Load favicons</title>
<p>When starting to play a station, its homepage favicon is automatically retrieved in the
background. It's not going to be displayed right away, but after you reload the category/station list.
Alternatively use <guiseq><gui>Channel</gui> <gui>Update favicons...</gui></guiseq> to update all
station icons at once.</p>
</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>
<item>
<title>Update favouries from freshened URLs</title>
<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>
</item>
<item>
<title>google station homepages</title>
<p>When playing a station that doesn't have a homepage entry, streamtuner2 tries to google
the station title. The found URL is then used/kept as station homepage. (Btw, station titles
like www.mymusicstation.com are automatically mapped to homepage URLs already.)</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>
</item>
</terms>
</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>