Most radio stations are listed with a homepage URL. Use the
Some homepage links are guessed, because for example Shoutcast doesn't list them anymore. + And if you play a station without homepage URL, it automatically gets googled (but will not + be displayed until you reselect the category.) +
+ +You can also open channel homepages. Either from the
Simply double click a station to start it with your audio player.
+ +In streamtuner2 you can configure different audio players for different audio + formats. In the 'Apps' section of the settings dialog, there is one application associated + with each audio file (MIME) type. Per default this is audacious, but you can certainly use + any other application.
+ +Note however, that some audio players will start twice and won't + allow easy station switching. In these circumstance it might be sensible to write + a wrapper script, or configure special commandline arguments to your favoured audio + player.
It's also possible to save a station entry as .m3u or .pls file, and load this manually + in your player. You might even want to collect such .m3u files for archival / backup + purposes.
+ + +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.
+ +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.
+ +You can influence all these behaviours with -arguments to the streamripper program. + Please refer to the manpage of streamripper. The options are too various to list here. + You can set default arguments (e.g. another default save directory) in the 'Apps' section of + the streamtuner2 configuration dialog.
+ + +You can export the currently selected stream using
But you can also save in .pls + or .xspf or .asx or .smil format. Note that the lower right dropdown + has no effect, you must edit the filename field.
+ + +It's easy to lose the overview when you browse through the various channel tabs, genres + and internet radio stations. Therefore streamtuner2 allows to create bookmarks. This way + you can collect favoured streams in a single place.
+ +Just right click a station you want to bookmark, and choose bookmark in the context + menu. Alternatively you can use the Streams entry in the application menu. Once bookmarked + you can see the station entry in the (!) "bookmarks" tab, under "favourite". That's where + they all go.
+ +Entries can be removed from the bookmark list again. Use the edit menu for that.
+ +Bookmarked stations are shown with a star in all other channel tabs. If you delete the + entry there, it won't remove it from the real bookmarks list.
+The bookmarks tab can display other categories besides "favourite". For example the + search feature creates a "search", while the "timer" and "links" plugins also display + lists here.
+I-R.org.uk is a good alternative to Shoutcast. It also lacks channel homepage in most + cases, but is a likewise encyclopedical directory. Genres are similiar to Shoutcast.
+ +Note that this plugin uses its own setting for how many links to retrieve. Instead + of stream numbers, it only counts pages. This is a lazyness related bug.
Jamendo is a Creative Comments licensing oriented music distributor. It hosts audio + files for individual musicians and artists. Tracks and albums can thus be downloaded + free of charge. Yeah, imagine that.
+ +The streamtuner2 plugin for Jamendo is pretty limited at the moment. It just provides + a quick overview over top artists and most listened albums from each genre. To browse + the whole collections, better go to the Jamendo homepage or use Rhythmbox.
+ +MyOggRadio is an open + source internet radio directory project. Since it provides its station list as + JSON it is very well supported.
+ +Because the directory is currently still rather small, streamtuner2 provides the
+ option to share radion station links. Use the
The personal section is empty, unless you specify an user account in the settings + and actually bookmarks stations on the MyOggRadio web site. Shared entries are not + automatically in the MOR favorite list.
+ + +If you want to upload station infos to MyOggRadio, you need an account there. Registration + is free and doesn't require personal information nor email address. Specify username and + password separated with a : colon in this field.
+When uploading stations, the streaming URL can be converted into RAW format. You + can however leave it as .PLS link file.
+SHOUTcast is the name of a MP3 streaming server software. It automatically collects all + station lists on shoutcast.com. +
+ +Station entries usually provide current playing information.
Stream links are plain PLS files.
Genres are subcategorized, so the main groups in the category + list must often be expanded to see the interesting entries.
Uses an XML parser to extract station data from within HTML <tags> of the shoutcast.com site. This is + slower, but often more reliable than regular expressions, which look for plain text markers.
+Prints verbose messages to the console. This option is used while developing extensions for Streamtuner2.
+Xiph.org is a non-profit organization, which develops and promotes the OGG audio format. + It also hosts a list of ICEcast streaming stations (ICEcast is the non-commercial pendant + to the SHOUTcast server.)
+ +This channel is especially easy to read by Streamtuner2, because the source data is already + provided as <XML> file. However, it lacks some essential informaitons like station + homepages and listener numbers.
+ +Xiph also uses the .xspf format, instead of .pls stream links
+ + +The bitrate of an audio stream determines the music quality. Many Xiph streams have simple + and low quality microphone sources. To filter these out, and only leave high quality music + stations, you can therefore set this option. OGG starts to sound good with 128 kbit/s (whereas + MP3 often needs 192 at least).
+The tabs in the main window represent the music directory channels. Each lists + categories and streams from a specific radio directory.
+ +If you first select a channel tab, the categories should appear or be loading. + Otherwise:
+ +Select a channel tab
Choose
Pick a category/genre from the overview, left.
Individual channels provide different music/radio information. The table
+ views are however identical in each tab. You could modify the datamap[]
+ in the plugin files, if you want to adapt this.
You can dobule click the channel tab to view the website of a directory services.
+ Alternatively there is an entry in the
Opens a webbrowser with the current channels website.
+Updates the current category and displays fresh station lists.
+Starts assembling favicons for the current list of stations in the background. + To actually display the freshly loaded favicons, reselect the current category.
+Updates the genre list in the left category pane. + For most channels the category list is already complete, but it might + change over time. So this option often only is used for initializing streamtuner2 + channels when the list is empty.
+The channel menu also contains a list of available channels. Select an entry to switch + into that tab.
+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 + other applications.
+ +Open a terminal and call streamtuner2 help to get an overview over
+ available commands.
This command looks through all channel plugins, and finds a station containing the + mentioned title. In the shell you must put the station title in quotes, if it contains + e.g. spaces. You can optionally specify a channelname before the station title.
+Just looks up the streaming URL for a given station. If no channel name is given, + ST2 searches through all available channel plugins again.
+Prints available station data as JSON
+Loads fresh data from the specified channel service, and prints out JSON data for + the whole category. Note that the category name must have the excact case.
+Fetches the current list of available categories/genres for a channel service.
+Specifying a channel name is often optional. If you add one, it should be all-lowercase. + You can also give a list, like "shoutcast,xiph" which would be searched then.
+ +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.
+ +| Audacious | audacious %m3u | audio |
| XMMS2 | xmms2 %m3u | audio |
| Amarok | amarok -l %pls | audio |
| Exaile | exaile %m3u | audio |
| Amarok | amarok -l %pls | audio |
| mplayer | mplayer %srv | console |
| VLC | vlc %u | video/* |
| Totem | totem %u | video/* |
| Media Player | mplayer2.exe %pls | Win32 |
Some audio players open a second instance when you actually want to switch radios.
+ In this case it's a common workaround to write pkill vlc ; vlc %u instead.
+ This ends the previous player and starts it anew.
Some applications, like Rhythmbox or Banshee, are pure GUI applications and cannot + be invoked with a play URL by other apps. This makes them unsuitable for use with + streamtuner2.
+ +Any listed application can be invoked with a different kind of URL or filename.be invoked with a play URL by other apps. + Which to use often depends on the application.
+| Placeholder | Alternatives | URL/Filename type |
| %m3u | %f %g %m | Provides a local .m3u file for the streaming station |
| %pls | %url %u %r | Either a remote .pls resource, or a local .pls file (if converted) |
| %srv | %d %s | Direct link to first streaming address, e.g. http://72.5.9.33:7500 |
You sould preferrably use the long forms. Most audio players like %m3u most, while + streamripper needs %srv for recording.
+There are many options in streamtuner2. You can find the settings dialog in the edit menu, + preferences (last entry).
+ +Lists audio formats and the applications which shall be used for playing.
+Influences the display of all stream/station lists.
+Filesystem and environment settings. Boring.
+Every channel tab can have specific options. These are configured here. Also you can disable channels you don't need.
+MIME types are elaborate identifiers for file types. audio/mp3 for example represents MP3 files, and audio/ogg + means just OGG.
+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, but you might have to look it up.
+Behind the application program name is a placeholder. If the audio player is invoked, this placeholder + gets replaces with an URL (a http://..-Link) of the selected radio stream.
+It's introduced by percent sign, and followed by letters. %m3u for example generates a .m3u file. Most + audio players understand that. Otherwise try %pls, which might even be faster because streamtuner2 doesn't + have to download and preprocess it. %srv instead gives a direct stream link.
+The entry for */* is a catch-all. If the audio format of a radio station isn't know, this application + gets called.
+The last entry in the 'Apps' section specifies streamripper. It is used for recording stations. You + might want to add some commandline -arguments here.
+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.
+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.
+"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.
+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 just have to try it.
+Remembering window states makes streamtuner2 not forget 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.
+There are just a few options here, and some are hard-wired. Usually you don't want to change them.
+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.
+Each channel plugin can bring its own list of configuration settings. These are collected here.
+The heading for each plugin is actually a button, which allows disabling the plugin. Alas the state + cannot be easily discerned with all themes.
+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.
+Streamtuner2 is written in Python, a rather easy programming language. And it's also rather simple + to write a new channel plugin.
+ +The basic layout of every channel plugin is as follows:
+ +
+
+from channels import *
+
+class myplugin (ChannelPlugin):
+
+ title = "MyNewChannel"
+ module = "myplugin"
+ homepage = "http://www.mymusicstation.com/"
+ categories = []
+
+
+
+ def update_categories(self):
+
+ self.categories = []
+
+
+
+ def update_streams(self, cat, force=0):
+
+ entries = []
+
+ # ...
+ # get it from somewhere
+ # ...
+
+ return entries
+
+
There are some self-explanatory description fields, and two important methods. Sometimes you + don't need categories even. The update_streams() function often downloads a website, parses it + with regular expressions or PyQuery / DOM methods, and packs into into a result list.
+ +Here entries is a list of dictionaries, with standardized entry names like "title" and "playing" + for the description, and "homepage" for a browsable link, and most importantly "url" for the + actual streaming link. Often you want to add a "genre" and "format" and "bitrate" info. But this depends + on your plugins data source, really.
+ + +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 + configured to alternate in any other channel.
+ +This is useful if you don't want to keep the streamtuner2 window in the foreground + all the time, but still want to switch radios easily.
+ +Go into settings
| keyspec: | corresponds to: |
| F9 | Responds to only |
| <Meta>R | often the 'Windows'-key and R |
| <Ctrl>N | Control and |
| <Shift>F1 | Shift and F1 |
| <Alt>SPACE | Use Alt and |
| XF86Forward | Uses a "forward" function key. (default) |
To define another channel as source, enter its module name in the according field. Also + add a category separated by : colon here.
+ +If the configured keyboard shortcut conflicts with another application, + it won't work. And if you choose it too generic, you won't be able to type longer + documents. Also found out: key names are case sensitive.
Each tab in the main window is a "channel". It represents one + music directory service.
+"stream" is a technical term which means continuosly flowing + data. MP3 radio music for example is streamed, because it's not + just a time-limited audio file, but unending (unless you stop + the player or paying your ISP).
+In streamtuner2 we also use the terms "stream" and radio "station" interchangably.
+Music genres are represented as "categories" in the left + pane. Every channel groups its music stations into some + structure.
+URL stands for "Uniform Resource Locator" and simply means + hyperlinks and web addresses like http://www.example.org/. + There is also the hipster term "URI", which is technically more + general (but superseeded by "IRI" and "IRL" anyway). In + streamtuner2 the audio streaming link often is an URL, as is the + radio station homepage of course.
+Plays music. Sometimes interrupted by advertisements. +
+Favicons are small symbols for websites. Every website has one. + Or should have. As it makes it easier to associate content with + homepage addresses. (ST2 downloads favicons either per menu command + or automatically for the current station once you hit play.) +
+Radio lists are kept in "cache" files for efficiency reasons. + To not redownload stream information on every category or channel + flip, streamtuner2 saves this data. This avoids time consuming + server requests. +
+Python is a programming language. It provides extensive constructs and + many functions, yet is easy to learn. See python.org and Google.
+MP3 (MPEG Layer 3) is an audio file format, part of the wider MPEG (Motion Picture + Expert Group) video format. It's the most widespread format in use today, + however doesn't provide the highest audio quality..
+OGG is a multimedia file format. Vorbis is an audio compression format. + OGG Vorbis was developed as alternative to MP3. It's often of higher + quality at lower file sizes, and isn't encumbered by US software patents.
+For classification of web and email content, two-factor descriptions like + "audio/ogg" are advised. These are called Multipurpose Internet Mail Extension + types, and are used on the web in lieu of file extensions (which URL resources don't have). + Note that ST2 uses the MP3 type wrong; it's officially audio/mpeg, and not audio/mp3 as shown in the settings window.
+Audio streams are compressed with exactness loss. This can be heard + at lower "bitrates". For MP3 files any music with less than 100 kbit/s + starts to hiss, while OGG Vorbis still sounds okay at a datarate of + for example 64 kbit/s. So while bitrate basically means file size per duration, + it's commonly used as quality indicator.
+Besides audio formats MP3 and OGG, there are also station/streaming link files. + These are often downloaded from the directory servers, before your music player gets activated.
+JSON is a data representation format derived from Javascript (the browser embedded + programming language for websites). Streamtuner2 uses it to store it's configuration + and radio station data files.
+The MIME type of these files is application/json and they often look like:
+ +
+[
+ {
+ "title": "Station title..",
+ "url": "http://1.2.3.4:8000/",
+ "homepage": "http://radio.org/",
+ },
+ { "title": "second" }
+]
+
M3U files also contain playlists, like .pls files. But they are often used by locally installed audio players.
+The MIME type of these files is audio/x-mpegurl and they often look like:
+ +
+#M3U
+http://123.45.67.189:8222/
+http://123.45.67.222:7555/
+
Playlist files often have the extension .pls
+It's the primary station stream link format of SHOUTcast.
+The MIME type of these files is audio/x-scpls and they often look like:
+
+[playlist]
+numberofentries=1
+File1=http://123.45.67.189:8222
+Title1=(#1 - 555/2000) radio station Xyz - top 100 - all the hitzez
+Length1=-1
+
Streamtuner2 shows internet radio stations for easy browsing, playing, recording.
+ +Streamtuner2 is a simple browser for internet radios. It aquires its radio lists + from various directory services. These are represented as "channel" tabs in the main + window. Below are the category/genre lists (left) and the stations for a genre (right).
+ +Select a channel tab, like Shoutcast.
Click one of the genres in the left pane. For example Classic.
Now the right pane loads a radio list.
Double click one of the radio streams or use the
Note that some categories can and should be exanded. In a few plugins (modarchive), + the expandable genre/category brings up no station list on its own, while in Shoutcast + and most others it's a valid genre in itself.
+Some radio stations cannot be played, because they just have a homepage. (That's the + case for all listings in the Google Stations channel.)
+Double clicking an entry row in the radio list starts your audio player. But there are
+ other functions available. Either go to the
| Play | Starts the radio in a configured audio player |
| Record | Opens a terminal window and streamripper, which cuts the radio broadcast into individual mp3 songs. |
| Bookmarks | Copy radio entry over into the |
| Homepage | Most radio stations have a homepage. Open this in a web browser. |
| Saving | A radio entry can be exported as .m3u or .pls file. |
| Extensions | Some plugins add other features in this submenu. |
| Editing | This command is in the |
| Searching | You can get a radio list according to search criteria. |
Play, Record and Homepage also have buttons in the toolbar.
+After some time, stream informations become obsolete. Therefore you should regularily
+ refresh the lists. The
You should only select radio stations and genres that you like.
Station information can get stale. Especially Shoutcast invalidates old information + frequently. Therefore you have to [reload] the lists. There is an action button below + the menu bar for this. It retrieves the current data from the directory service.
+ +Favicons aren't loaded automatically. There is a menu entry in Channels for that, which + works in the background and doesn't display the new icons automatically either. Simply + reselect the category/genre in the left pane. Or again, use the station reload button.
+ + +There are two search functions. The quick search field is in the toolbar, and allows
+ to highlight search terms in the current station list. The cache search is available
+ through the
You can get to the search dialog via
Above you can check which channel plugins to inspect for the search term. Using this + allows to limit the search to specific radio station directories, but usually you want + to search them all.
+ +Below the search phrase text box, you can specifiy which station fields to look + into. Often you just want to search the titles of radio stations. But you can also + have the search occour in the description/playing fields. Alternatively you could + just search the homepage links.
+Lastly, there are three search methods. You mostly want to use the
The
Use the button
Just enter text into the quick search box. Streamtuner2 will instantly highlight + any matches in the current stations view. If you switch tabs, just click the glass icon + to reapply the highlighting.
+Radio stations are listed in the right pane. Usually they have a title and a + description. The description is often the last played song. (This isn't updated + automatically to conserve bandwidth and because live information is seldomly available.)
+ +You can double click a station line to get it to play. Alternatively there are the + play and record buttons in the menubar. You can also invoke a stations homepage, if it + has one.
+ + +Additionally most actions are available in a context menu. Right click + a station entry to display it.
+ +Reshuffling of station entries in the list is possible by dragging them. But + this is only a visual effect and will confuse the internal ordering of entries. Don't + do it.
You can always click the current category in the left list, to have the current + station list redisplayed. Which is useful after updating favicons, or accidental + dragging of entries.
+Python 2.5
PyGtk
Gtk+ 2.12
Python-LXML
Python-PyQuery
Audacious
Corresponds to the XDG_CONFIG_HOME setting. All ST2 configuration settings + are contained within here and are in JSON format.
+General runtime options, plugin settings, and configured audio players.
+Saved window sizes, list widths.
+Last category in each channel tab.
+Is a separate cahce file for your bookmarked/favourite radio stations.
+JSON files for stream lists in each channel.
+Holds downloaded favicons for station homepages.
+Is the main binary.
+Contains the individual ST2 python modules, and plugins in channels/. Also packages in pyquery/, but which is only used if the according modules aren't installed by the distribution.
+Contains the README, and Mallard/gnome-help/yelp files under help/.
+There is no licensing requirement with this application. All code can be copied, modified + and distributed unrestrictively.
+You can programm play/recording events with the timer plugin. Simply select a station
+ and choose
Note that streamtuner2 must be running for the programmed timer events to work. + (In a future version there might be the option to have it handled by the system cron + daemon.)
The time and date specificators follow a simple scheme. It's always one or more day names + followed by a clock range, and finally the action.
+For example "Mon,Tue,Wed" will make the event occour on the first
+ three days of each week, while just "Fri" would limit it to Fridays.
A clock range of "18:00-20:00"
+ would start the event at 18 o'clock and last it two hours. Note that for "play" events, the end
+ time is irrelevant, since streamtuner2 can't kill your audio player anyway.
The end time is only important, if you replace "play" with the word "record"
+ in the timer event string. This runs streamripper instead and limits the recording time.
You can remove entries from the "timer" list again. Use the normal
However, such changes don't take effect until you restart streamtuner2. The timer + events are only scheduled when adding a new event, or on starting streamtuner2.