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

⌈⌋ ⎇ branch:  streamtuner2


Check-in [497073df0d]

Overview
Comment:Document current reuse_m3u and nothreads config behaviour. Rewrite placeholder and application help pages to be more understandable. Mention GUI alternatives to streamripper.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 497073df0df4cda1cff50a22c8b261e043a4e9c8
User & Date: mario on 2015-04-24 19:21:32
Other Links: manifest | tags
Context
2015-04-24
19:21
Use generic `audio/mod-zip` for all MOD Archive urls. check-in: fed23f23f7 user: mario tags: trunk
19:21
Document current reuse_m3u and nothreads config behaviour. Rewrite placeholder and application help pages to be more understandable. Mention GUI alternatives to streamripper. check-in: 497073df0d user: mario tags: trunk
19:20
Prepare bookmarks-category DND as target (for internal stream moving). Fix FILE_NAME being passed as text not uris XSelection type. Use underscores in place of spaces to avoid urlencoding file:// references. Move log.DND colorization to config. check-in: 1569b57c42 user: mario tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Modified help/action_recording.page from [f19b531796] to [f946f040e0].

︙
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

47

















48
49
50
51
52
53

54
55
56
57
58
59
60
61
62
63


64
65
66
67



68
69
70
71

32
33
34
35
36
37
38

39
40
41
42
43
44

45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

69
70
71
72
73
74
75
76
77


78
79
80



81
82
83
84
85
86
87








-






-
+

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+





-
+








-
-
+
+

-
-
-
+
+
+






<p>To configure a default download directory, use the <cmd>-d</cmd> option to streamripper.
For example <cmd>xterm -e "streamripper -d /media/music/"</cmd> would use an absolute path.
Else it downloads to the current working directory (often your HOME path),
and creates one directory per radio station there.</p>
</section>


<section>
<title>fIcy/fPls</title>

<p>As alternative to streamripper, check out <link href="http://freshcode.club/projects/ficy">fIcy/fPls</link>
for recording ICEcast/SHOUTcast streaming servers.</p>

<p>It can be configured with <cmd>xterm -e "fPls %srv"</cmd> simply.</p>
<p>It can be configured with <cmd>xterm -e "fPls %pls"</cmd> simply.</p>
</section>


<section>
<title>Graphical stream recording tools</title>
<p>You might also want to try a streamripper GUI or graphical
reimplementation. For instance there are:</p>
<list>
<item><p><link href="http://sourceforge.net/projects/stripper/">StreamRipStar</link> (Java), works best per drag and drop.</p></item>
<item><p><link href="http://launchpad.net/streamtastic">Streamtastic</link> (Java)</p></item>
<item><p><link href="http://kstreamripper.sourceforge.net/">KStreamRipper</link>, though no current version in distros.</p></item>
<item><p>VLC has built-in recording capabilities.</p></item>
</list>
<p>Which simplify defining a custom download directory, or how radio
streams are split (between advertisement breaks), and the naming scheme
for resulting *.mp3 filenames of course.</p>
</section>



<section>
<title>Youtube-DL</title>

<p>The recording settings have a specific entry for "video/youtube" URLs. To configure a specific download
<p>The recording settings have a specific entry for "video/youtube" URLs. To configure a custom download
directory, use <cmd>xterm -e "cd /media/music ; youtube-dl %srv"</cmd> for example. (The <cmd>cd</cmd>
trick works with streamripper too.)</p>
</section>


<section>
<title>Wget for MOD files</title>

<p>To download audio files from The MOD Archive directly, you can define a
few custom handlers.  Scroll/click on the empty row in the recording apps
<p>To download audio files from The MOD Archive directly, you can also
define a custom handler.  Scroll/click on the empty row in the recording apps
table.  There create a new recording MIME type <var>audio/mod+zip</var> with
a command like <cmd>xterm -e wget %srv</cmd>.  Copy it alike for
<var>audio/it+zip</var> and <var>audio/xm+zip</var> to cover the most common
file types.  Using <cmd>curl</cmd> would also work of course.  </p>
a command like <cmd>xterm -e wget %srv</cmd>.  All mod formats (IT, XM, S3M,
etc.) are mapped to this generic type specifier. Using <cmd>curl</cmd> would
also work of course.</p>
</section>


</page>

Modified help/channel_modarchive.page from [755a76a43d] to [472c7bd913].

︙
18
19
20
21
22
23
24
25
26




27
28

18
19
20
21
22
23
24


25
26
27
28
29
30








-
-
+
+
+
+



             <item><p>MikMod</p></item>
             <item><p>MODPlug for XMMS</p></item>
             <item><p>GModplay</p></item>
             <item><p>VLC (built-in support)</p></item>
        </list>

	<note><p>See <link xref="recording">recording
	configuration</link> if you want to enable the download mode. (Audio
	files are packaged up in ZIP files on MODArchive.)</p></note>
	configuration</link> if you want to enable the download mode. Audio
	files are packaged up in ZIP files on MODArchive. While they are
	different formats (IT, S3M, XM, etc) they'll all carry a generic
	<var>audio/mod+zip</var> type specifier in streamtuner2.</p></note>

</page>

Modified help/config_apps.page from [d8a5ff9529] to [88f4824a2c].

︙
29
30
31
32
33
34
35
36
37


38
39
40
41
42
43
44
45









46
47
48
49
50
51
52
53
54
55
56
57
58




59




60
61
62



63
64




65
66
67
68

29
30
31
32
33
34
35


36
37
38
39
40
41




42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

63
64
65
66
67
68
69
70
71



72
73
74


75
76
77
78
79
80
81
82








-
-
+
+




-
-
-
-
+
+
+
+
+
+
+
+
+












-
+
+
+
+

+
+
+
+
-
-
-
+
+
+
-
-
+
+
+
+





	<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 play URL by other apps. This makes them less suitable for use with
	streamtuner2. (Same goes for streamtuner2 of course. It's not a player, just a playlist tool.)</p>
        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>Any listed application can be invoked with a different kind of
	URL or filename. Most are rather flexible, but some depend on
	specific playlist file types or URLs. You can control this by adding
	a placeholder after the configured application name:</p>
	<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.</p>
        <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>
	
	<note style="info"><p>Most audio players like %pls, yet sometimes the
	older %m3u format more.  Streamripper requires %srv for recording.</p>

	<p>Leave it to the default %pls to avoid Streamtuner2 doing unneeded
	extra conversions (just delays playback).</p> </note>
	<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>

</page>

Modified help/configuration.page from [cec2e8132d] to [76215508f0].

︙
50
51
52
53
54
55
56
57

58
59
60
61
62
63



64
65
66
67
68
69
70

50
51
52
53
54
55
56

57
58
59
60
61


62
63
64
65
66
67
68
69
70
71








-
+




-
-
+
+
+








    <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
    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>%srv</var>". See <link xref="config_apps#placeholders">placeholders</link>.</p>
    <p>After the application name, you can optionally use a placeholder like "<var>%pls</var>" (default),
    "<var>%m3u</var>" (old), or "<var>%xspf</var>" (modern), and "<var>%srv</var>" (for direct
    streaming URLs). 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 pseudo 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>
︙
157
158
159
160
161
162
163












164

165
166
167
168
169
170
171
172
173
174
175
176
177














178
179
180
181
182
183

184
185
186





187
188
189
190
191


192
193
194
195

196
197
198
199
200

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209

210
211


212
213
214
215
216
217
218
219


220
221
222
223
224

225
226
227
228
229
230








+
+
+
+
+
+
+
+
+
+
+
+
-
+













+
+
+
+
+
+
+
+
+
+
+
+
+
+





-
+

-
-
+
+
+
+
+



-
-
+
+



-
+







  <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. In recent versions streamtuner2 will create a <file>/tmp/streamtuner2</file> 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>
    </item>
    <item>
      <title>Reuse .m3u/.pls files</title>
      <p>When converting online station playlists, streamtuner2 creates temporary files like
      <var>shoutcast.11539398391891.m3u</var> for your audio player. It'll keep those
      files around until you quit streamtuner2. That speeds up switching between and reconnecting to 
      a previous station. It's in particular necessary when you use <key>⏭</key> or <key>⏪</key>
      directly in your player. For <var>%pls</var> references your player typically usues the online-only
      playlist files anyway. If you disable this option, then converted pls/m3u/xspf files get recreated
      for this. Leave this to the default /tmp else.</p>
      repeatedly.</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>
    <item>
      <title>Disable threading</title>
      <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 <cmd>--nt</cmd> to enable this workaround.</p>
    </item>
 </terms>

</section>

<section id="plugins">
    <title>Plugin and Channel settings</title>
    <title>Channel and feature plugins and 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>The tabs <key>Channels</key> lists all available directory services.
    While the <key>Features</key> group provides internal or menu enhancements.
    Disabling or enabling a plugin however requires a restart of Streamtuner2
    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>
    <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>

    <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>
    *.py files. These are somewhat readable even to non-programmers, and sometimes contain more information.</p></note>
</section>



</page>