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

⌈⌋ ⎇ branch:  streamtuner2


Check-in [803cb52d3f]

Overview
Comment:Explain audio player configuration with more examples, detail options for streamripper recording.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 803cb52d3ff63bb7eddd5c45c1fc444a7d49f753
User & Date: mario on 2015-03-26 18:51:59
Other Links: manifest | tags
Context
2015-03-26
20:59
Update configuration dialog help pages. check-in: 96814a40b4 user: mario tags: trunk
18:51
Explain audio player configuration with more examples, detail options for streamripper recording. check-in: 803cb52d3f user: mario tags: trunk
2015-03-25
21:54
Exception for json decoding from SHOUTcast. (Doesn't work with older requests library.) check-in: a6b5fc3cc9 user: mario tags: trunk
Changes

Modified help/action_recording.page from [9b1adbd620] to [2662913d47].

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

19
20


21




22

23


24
25

26
27
28
29












30
31
32
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="recording">

<info>
	<link type="guide" xref="streams#actions"/>
	<link type="guide" xref="configuration#apps"/>
	<link type="guide" xref="index#functions"/>
	<desc>Save radio songs as MP3 files via streamripper.</desc>
</info>

	<title>Recording</title>

	<p>Most stations that stream MP3 or OGG music can be recorded. This is accomplished by
        the commandline tool "streamripper". If you select a station a press the [record] button,
        a console window should appear. Within that streamripper outputs its current activity.</p>

        <p>Per default recorded streams are written into the current directory. Often this is your

        home directory. And streamripper automatically creates a directory with the recorded
        radio station title as name. Within that directory the individual music titles are split


        into separate .mp3 files.</p>






        <p>You can influence all these behaviours with -arguments to the streamripper program.


        Please refer to the manpage of streamripper. The options are too broad to list here.
        You can set default arguments (e.g. another default save directory) in the Config &gt; Apps

        dialog.</p>

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














</page>






|




|

|
|
|

|
>
|
|
>
>
|
>
>
>
>

>
|
>
>
|
|
>
|

|
|
>
>
>
>
>
>
>
>
>
>
>
>



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="recording">

<info>
	<link type="guide" xref="streams#actions"/>
	<link type="guide" xref="configuration#recording"/>
	<link type="guide" xref="index#functions"/>
	<desc>Save radio songs as MP3 files via streamripper.</desc>
</info>

<title>Recording</title>

<p>Most stations that stream MP3 or OGG music can be recorded. This is accomplished through
the commandline tool "streamripper". If you select a station a press the [record] button,
a console window should appear, where streamripper shows its progress.</p>


<section>
<title>Streamripper</title>

<p>The <cmd>xterm -e</cmd> prefix brings up the terminal popup, to follow streamrippers
progress. Remove that for silent downloads.</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/*</var></p></td>  <td><p><cmd>xterm -e streamripper %srv</cmd></p></td></tr>
</table>

<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
instead of your home directory (or the current working directory).</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>
</section>


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

<p>The recording settings have a specific entry for "video/youtube" URLs. To configure a specific 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>


</page>

Modified help/cli.page from [ca261558e1] to [b1f0422cfc].

1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="cli">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Console interface, exporting data.</desc>
</info>

	<title>CLI (command line interface)</title>

	<p>Streamtuner2 is a graphical tool. But it also has a limited commandline interface,
	which can be used to query station information. This is useful for interfacing with





|







1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="cli">

<info>
	<link type="guide" xref="index#extra"/>
        <desc>Console interface, exporting data.</desc>
</info>

	<title>CLI (command line interface)</title>

	<p>Streamtuner2 is a graphical tool. But it also has a limited commandline interface,
	which can be used to query station information. This is useful for interfacing with

Modified help/config_apps.page from [a18f7b786a] to [d350332b6e].

1
2
3
4
5
6

7
8
9
10
11
12
13
14
15
16
17
18
19
20
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="config_apps">

<info>
	<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
	configure 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>

	<table shade="rows" rules="rows cols">
		<tr><td><p><app>Audacious</app></p></td>     <td><p><cmd>audacious %m3u</cmd></p></td>  <td><p>audio</p></td></tr>
		<tr><td><p><app>XMMS2</app></p></td>         <td><p><cmd>xmms2 %m3u</cmd></p></td>      <td><p>audio</p></td></tr>
		<tr><td><p><app>Amarok</app></p></td>        <td><p><cmd>amarok -l %pls</cmd></p></td>  <td><p>audio</p></td></tr>






>






|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="config_apps">

<info>
	<link type="guide" xref="configuration#apps"/>
	<link type="guide" xref="index#configuration"/>
	<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>

	<table shade="rows" rules="rows cols">
		<tr><td><p><app>Audacious</app></p></td>     <td><p><cmd>audacious %m3u</cmd></p></td>  <td><p>audio</p></td></tr>
		<tr><td><p><app>XMMS2</app></p></td>         <td><p><cmd>xmms2 %m3u</cmd></p></td>      <td><p>audio</p></td></tr>
		<tr><td><p><app>Amarok</app></p></td>        <td><p><cmd>amarok -l %pls</cmd></p></td>  <td><p>audio</p></td></tr>

Modified help/configuration.page from [18a817d188] to [8b69bffa16].


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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

83
84
85
86
87
88
89
90

<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	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.
        You can find the settings dialog in the edit menu as "Preferences" (last entry).
        </p>

        <terms>
          <title>It's separated into three main areas.</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 elaborate identifiers for file types; audio/mp3 for example represents MP3 files, and audio/ogg

		means just OGG.</p>
		<p>The text entry fields can hold the application name of an audio player. Often the application name
		is just a lower case version of the program title.</p>

		<p>Behind application names a placeholder can be used. On invocation such placeholders






		get replaced with an URL (a http://..-Link) or filename for the selected radio stream.</p>

		<p>Placeholders are introduced by a percent sign, and followed by letters. %m3u for example generates a .m3u file,



                which most audio players understand. Otherwise try %pls, which might even be faster because streamtuner2 doesn't
		have to download and preprocess it. Alternatively %srv instead gives a direct stream link.</p>
		<p>Catch-all entries like */* or a generic audio/* entry allow to configure a default player.


		</p>



		<p><title>Recording</title></p>

		<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.






                To define a target directory, you can 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>

		<p>Most options here a self-explanatory. 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>

		<p>The number of stations setting 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 much scroll text appears in the stream lists.</p>

		<p>"Retain deleted stations" keeps old entries, when you reload a category/genre. Shoutcast often
		forgets stations or throws them out. If you keep this option enabled, these entries are kept in
		streamtuner2. Browse down in the stations list to still see them.</p>

		<p>It's possible to select a Gtk+ theme. But not all themes work with all Gtk display engines, and
		not all themes work with streamtuner2. You'll have to try.</p>

		<p>Remembering window states allows streamtuner2 to reconstruct which channel and category was last
		selected. You can however disable this option, and instead manually save the window states/layout
		in the edit menu, if you want.</p>

		<p>Setting another temporary directory might be useful, if you want to keep the temporary .m3u cache
		files. They are created whenever you hit play. For archival or speed-up porposes you might want to keep
		them elsewhere. They don't take a lot of space.</p>
	</section>

	<section id="plugins">
		<title>Plugin and Channel settings</title>

		<p>Each channel plugin can bring its own list of configuration settings. These are collected here.</p>

		<p>The heading for each plugin allows to enable or disable it. To apply changed states you need to restart
                streamtuner2 however.</p>

		<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>
	</section>
	
	
	
</page>
>
|
|
|


|
|


|

|
|
|

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|


|
>
|
|
>
|
|
|
>
|
>
>
>
>
>
>
|
>
|
>
>
>
|
<
|
>
>
|
>
>
>
|
>
|
|
>
>
>
>
>
>
|
|
|
|


|
|
>
|
|
|
>
|
|
|
>
|
|
|
>
|
|
>
|
|
|
>
|
|
|
|

|
|
>
|
>
|
|
>
|
|
|
|
|
|
|

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
<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.
You can find the settings dialog in the edit menu as "Preferences" (last entry).
</p>

<terms>
  <title>It's separated into three main areas.</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 always lowercase binary names. Double click an entry to edit it.</p>

    <p>After the application name, you can use a placeholder like "<var>%pls</var>" (which is the default,
    and returns a direct URL often) or "<var>%m3u</var>" (where streamtuner creates local MP3 playlist file first)
    and "<var>%src</var>" (a direct streaming server link, e.g. for VLC).</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>

</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 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>

    <p>Most options here a self-explanatory. 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>

    <p>The number of stations setting 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 much scroll text appears in the stream lists.</p>

    <p>"Retain deleted stations" keeps old entries, when you reload a category/genre. Shoutcast often
    forgets stations or throws them out. If you keep this option enabled, these entries are kept in
    streamtuner2. Browse down in the stations list to still see them.</p>

    <p>It's possible to select a Gtk+ theme. But not all themes work with all Gtk display engines, and
    not all themes work with streamtuner2. You'll have to try.</p>

    <p>Remembering window states allows streamtuner2 to reconstruct which channel and category was last
    selected. You can however disable this option, and instead manually save the window states/layout
    in the edit menu, if you want.</p>

    <p>Setting another temporary directory might be useful, if you want to keep the temporary .m3u cache
    files. They are created whenever you hit play. For archival or speed-up porposes you might want to keep
    them elsewhere. They don't take a lot of space.</p>
</section>

<section id="plugins">
    <title>Plugin and Channel settings</title>

    <p>Each channel plugin can bring its own list of configuration settings. These are collected here.</p>

    <p>The heading for each plugin allows to enable or disable it. To apply changed states you need to restart
    streamtuner2 however.</p>

    <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>
</section>



</page>

Modified help/global_key.page from [4d55acbd37] to [2c1d73522f].

1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="topic"
	id="global_key">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Global keyboard shortcut for radio switching.</desc>
</info>

	<title>Global_key</title>

	<p>Using the global_key extension you can define a keyboard shortcut for switching within
	a list of favourite radio stations. Per default it uses your bookmarks list, but it can be





|







1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="topic"
	id="global_key">

<info>
	<link type="guide" xref="index#extra"/>
        <desc>Global keyboard shortcut for radio switching.</desc>
</info>

	<title>Global_key</title>

	<p>Using the global_key extension you can define a keyboard shortcut for switching within
	a list of favourite radio stations. Per default it uses your bookmarks list, but it can be

Modified help/glossary.page from [cc5e00e6f2] to [c0edfeac9e].

1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="glossary">

<info>
	<link type="guide" xref="index#advanced"/>
	<desc>Technical and streamtuner2 specific terminology and jargon.</desc>
</info>

	<title>Glossary</title>








|







1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="glossary">

<info>
	<link type="guide" xref="index#extra"/>
	<desc>Technical and streamtuner2 specific terminology and jargon.</desc>
</info>

	<title>Glossary</title>



Modified help/index.page from [0b2b951ce2] to [d36cba89d4].

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
            <title>Functions</title>
    	</section>

	<section id="configuration" style="2column">
            <title>Configuration</title>
    	</section>

	<section id="advanced" style="2column">
            <title>Advanced topics</title>
    	</section>

	<section id="footer">
	<p>You can get additional help from the online forum. See help menu for the link.</p>

	<p>Update status: This documentation is based on available functions in streamtuner2
	version 2.1.4 of February 2015. It's still incomplete however.</p>
	</section>

</page>







|
|










23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
            <title>Functions</title>
    	</section>

	<section id="configuration" style="2column">
            <title>Configuration</title>
    	</section>

	<section id="extra" style="2column">
            <title>Additional features</title>
    	</section>

	<section id="footer">
	<p>You can get additional help from the online forum. See help menu for the link.</p>

	<p>Update status: This documentation is based on available functions in streamtuner2
	version 2.1.4 of February 2015. It's still incomplete however.</p>
	</section>

</page>

Modified help/technical.page from [919176a596] to [3e15edff15].

1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="technical">

<info>
	<link type="guide" xref="index#advanced"/>
        <desc>Filenames, Directories, Dependencies</desc>
</info>

	<title>Technical information</title>


	<section id="dependecies">





|







1
2
3
4
5
6
7
8
9
10
11
12
13
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="technical">

<info>
	<link type="guide" xref="index#extra"/>
        <desc>Filenames, Directories, Dependencies</desc>
</info>

	<title>Technical information</title>


	<section id="dependecies">

Modified help/timer.page from [66108fe42c] to [1dabdeeb42].

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="timer">

<info>
	<link type="guide" xref="bookmarks#other"/>
	<link type="guide" xref="index#advanced"/>
        <desc>Programming recurring play and recording events.</desc>
</info>

	<title>Timer</title>

	<p>You can programm play/recording events with the timer plugin. Simply select a station
	and choose <guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Add timer...</gui></guiseq>.






|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
<page	xmlns="http://projectmallard.org/1.0/"
	type="guide"
	id="timer">

<info>
	<link type="guide" xref="bookmarks#other"/>
	<link type="guide" xref="index#extra"/>
        <desc>Programming recurring play and recording events.</desc>
</info>

	<title>Timer</title>

	<p>You can programm play/recording events with the timer plugin. Simply select a station
	and choose <guiseq><gui>Station</gui> <gui>Extensions</gui> <gui>Add timer...</gui></guiseq>.