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

<info>
	<link type="seealso" xref="index#functions"/>
	<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
	application for all audio formats. But at least the */* media type should be handled
	by a generic player, like vlc.</p>

        <p><media type="image" src="img/configapps.png" mime="image/png" /></p>
        
        <p>A few common applications and invocation strings to use are:</p>

	<table shade="rows" rules="rows cols">
	<tr><td><p><app>audio/*</app></p></td>   <td><p><cmd>audacious</cmd></p></td> </tr>
	<tr><td><p><app>audio/*</app></p></td>   <td><p><cmd>xmms2 %m3u</cmd></p></td></tr>
	<tr><td><p><app>audio/*</app></p></td>   <td><p><cmd>amarok -l %pls</cmd></p></td></tr>
	<tr><td><p><app>audio/*</app></p></td>   <td><p><cmd>exaile</cmd></p></td></tr>
	<tr><td><p><app>video/*</app></p></td>   <td><p><cmd>mplayer %srv</cmd></p></td></tr>
	<tr><td><p><app>video/*</app></p></td>   <td><p><cmd>totem %u</cmd></p></td></tr>
	<tr><td><p><app>*/*</app></p></td>       <td><p><cmd>vlc %u</cmd></p></td></tr>
	</table>

	<p>Some audio players open a second instance when you actually want to switch radios.
	In this case it's a common workaround to write <code>pkill vlc ; vlc %u</code> instead,
	which ends the previous player process and starts it anew.
        For VLC there's however also the <code>--one-instance</code> option, which sometimes
        works better. (And sometimes not.)</p>

	<p>Some applications, like Rhythmbox or Banshee, are primarily playlist managers, not players,
        and cannot be invoked with a station URL. This makes them less suitable for use with streamtuner2.
        (Same goes for streamtuner2 itself. It's not a player, but just a playlist browser.)</p>

	<section id="placeholders">
	<title>URL placeholders</title>

	<p>Listed audio players get run with a streaming server address (URL).
	These can either be direct MP3/Ogg servers (<var>http://example.org:7843/</var>)
	and sometimes playlist files (<var>http://example.org/listen.pls</var>)
	- depending on the channel directory.</p>

	<p>Most audio players automatically handle any station URLs. Some however
	support just a few formats, or can't handle modern XSPF playlists for
	instance. Which is why you can control this by adding a placeholder
	after the configured application name:</p>

	<table shade="rows" rules="rows cols">
	<thead>	<tr><td><p>Placeholder</p></td><td><p>Alternatives</p></td><td><p>URL/Filename type</p></td></tr> </thead>
		<tr><td><p>%pls</p></td><td><p>%url %u %r</p></td><td><p>Either a remote .pls resource (fastest), or a local .pls file (if converted)</p></td></tr>
		<tr><td><p>%m3u</p></td><td><p>%f %g %m</p></td><td><p>Provides a local .m3u file for the streaming station</p></td></tr>
		<tr><td><p>%srv</p></td><td><p>%d %s</p></td><td><p>Direct link to first streaming address, e.g. http://72.5.9.33:7500</p></td></tr>
		<tr><td><p>%xspf</p></td><td><p>%x</p></td><td><p>Xiph.org shareable playlist format (for modern players)</p></td></tr>
		<tr><td><p>%jspf</p></td><td><p>%j</p></td><td><p>JSON playlist format (widely unsupported)</p></td></tr>
		<tr><td><p>%asx</p></td><td><p></p></td><td><p>Some obscure Windows playlist format (don't use that)</p></td></tr>
		<tr><td><p>%smil</p></td><td><p></p></td><td><p>Standardized multimedia sequencing lists (which nobody uses either)</p></td></tr>
	</table>

        <p>Preferrably use the long %abbr names for configuration. The
        default is <var>%pls</var> if you leave it out. (Most directories
        already provide PLS files, which avoids any extra conversion by ST2
        which sometimes delay playback.)</p>
        
        <p>A few channels (like Jamendo) send custom JSON playlist snippets,
        which no audio player would understand. Which is why they're always
        pre-converted.</p>
        
	<note style="info"><p>Most audio players like %pls, yet sometimes the
	older %m3u format more.  Streamripper requires %srv for recording.</p>

	<p>Use the newer <var>%xspf</var> format if your player supports
	it. This format retains the maximum of station infos (such as
	homepages etc.), and thus often makes for better bookmarking directly
	in your player.</p> </note>


	</section>

	<section id="row_placeholders">
	<title>Other placeholders</title>

	<p>In addition to stream URL + type placeholders (<var>%r</var>, <var>%x</var>, 
	<var>%pls</var>, <var>%m3u</var>, etc),	you can also pass station
	info placeholders. These contain the stream information like title or
	bitrate, or any other internal field:</p>

	<table shade="rows" rules="rows cols">
	<thead>	<tr><td><p>Placeholder</p></td><td><p>As variable</p></td><td><p>Field content</p></td></tr> </thead>
		<tr><td><p>%title</p></td><td><p>$title</p></td><td><p>Station title</p></td></tr>
		<tr><td><p>%genre</p></td><td><p>$genre</p></td><td><p>Stream category or genre list</p></td></tr>
		<tr><td><p>%playing</p></td><td><p>$playing</p></td><td><p>Currently playing song, or geographic location</p></td></tr>
		<tr><td><p>-</p></td><td><p>$url</p></td><td><p>Unfiltered stream url (may contain internal urn:xx:id)</p></td></tr>
		<tr><td><p>%format</p></td><td><p>$format</p></td><td><p>The MIME type ("audio/mpeg")</p></td></tr>
		<tr><td><p>%bitrate</p></td><td><p>$bitrate</p></td><td><p>Known stream bitrate, if any</p></td></tr>
		<tr><td><p>%extra</p></td><td><p>$extra</p></td><td><p>Comments or timer settings</p></td></tr>
		<tr><td><p>%favourite</p></td><td><p>$favourite</p></td><td><p>If bookmarked</p></td></tr>
	</table>

	<p>Not all fields are used in all channels. Sometimes they're repurposed (like <var>playing</var>
	often doubles as Location: field). And some channels may even use custom internal names.</p>

	<note style="info"><p>You often want to use such placeholders if you have a player or recording shell script, such as
	<link href="http://fossil.include-once.org/streamtuner2/artifact/51b695f41d9f9ad2"><file>contrib/cmdline/streamripper_addgenre</file></link>
	to handle them. Or if you define a <link xref="specbuttons">mini-toolbar specbutton</link>
	with custom commands.</p></note>
	</section>
	
<section>
<title>Other players</title>
<p>Here a few other configuration examples for other
players/backends.</p>
<terms>
  <item>
    <title>MPD</title>
    <p>
       Rocus van Oosten <link href="https://sourceforge.net/p/streamtuner2/discussion/1173108/thread/82b6be86/">recommends</link>
       following wrapper script to start playing radio streams via MPD right away:
    </p>
	<code>MPD_HOST='10.0.0.222' # or your MPD host
export MPD_HOST
mpc clear
mpc load $1
mpc play</code>
    <p>
	Save it as <file>mpc-pls</file> script and configure it in streamtuner as
	<cmd>mpc-pls %pls</cmd> for example. You can find an extended
	version in the <file>contrib/cmdline/</file> directory.
    </p>
  </item>
</terms>
</section>

<section id="windows">
<title>Windows config</title>
<p>There's a few things you have to take care of when configuring players
and recording apps on Windows. Common applications and settings would be:</p>
<table shade="rows" rules="rows cols">
  <tr><td colspan="3"><p><em>Player config</em></p></td></tr>
  <tr><td><p><app>audio/mpeg</app></p></td>  <td><p><cmd>wmplayer.exe %asx</cmd></p></td>   <td><note style="bug"><p>Windows media player doesn't understand PLS or M3U files.</p></note></td></tr>
  <tr><td><p><app>video/*</app></p></td>     <td><p><cmd>C:\Programs\VLC\vlc.exe %srv</cmd></p></td>   <td><note style="info"><p>VLC pretty much works alike on Windows.</p></note></td></tr>
  <tr><td><p><app>url/http</app></p></td>    <td><p><cmd>"C:/Program Files/Mozilla Firefox/firefox.exe" %url</cmd></p></td>   <td><note style="info"><p>It's best to enclose paths with spaces in quotes.</p></note></td></tr>
  <tr><td><p><app>url/http</app></p></td>    <td><p><cmd>iexplore.exe %url</cmd></p></td>   <td><note style="note"><p>IE is not recommended, of course.</p></note></td></tr>
  <tr><td colspan="3"><p><em>Recording apps</em></p></td></tr>
  <tr><td><p><app>audio/*</app></p></td>     <td><p><cmd>/D "C:\Programs\Streamripper" streamripper.exe %srv</cmd></p></td>   <td><note style="bug"><p>Command line programs need the /D switch first, then its path enclosed in quotes and a space before the program.</p></note></td></tr>
</table>
<p>You can avoid a few issues: if you put your executables in paths without
spaces, or set the system $PATH variable accordingly.</p>
<note style="info"><p>As reported by Oliver in the sourceforge Discussion
board.</p></note>
</section>

</page>
