Index: help/html/bookmarks.html ================================================================== --- help/html/bookmarks.html +++ help/html/bookmarks.html @@ -17,33 +17,37 @@

Bookmarks

-

It's easy to lose oversight when switching across channel tabs, - genres and internet radio stations. Therefore streamtuner2 allows - to bookmark stations to 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 go.

+

Streamtuner2 allows to bookmark favoured streams/stations. + Which is what the bookmarks tab is for, of course.

+

Use the right click a stations context menu ▸ bookmark + or F8.

+

Once bookmarked the station is listed under + bookmarks ▸ favourite. + Additionally every appearance of the station in channel tabs gets a ★ + star icon.

Editing

-

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.

+

Entries can be removed from the bookmark list again. Use + Edit ▸ Delete or the DEL + key for that.

+

You can also manually adapt an entry via Station ▸ Edit or F3. +

Subcategories

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.

-

However the favourite list itself can not yet be categorized further.

+

However the favourite list itself can not yet be categorized + further.

Searching — Quicksearch field and Ctrl+F compound search window.
Timer — Programming recurring play and recording events.
Index: help/html/channels.html ================================================================== --- help/html/channels.html +++ help/html/channels.html @@ -12,23 +12,24 @@

Channels

The tabs in the main window represent the music directory - channels/services. Each lists categories and streams from a - specific radio directory/website.

+ channels/services. Each lists categories/genres and their associated radios/streams.

+

The notebook tabs can also be repositioned with + Edit ▸ Channel tab position ▸ Left.

If you first select a channel tab, the categories should appear or be loading. Otherwise:

  1. Select a channel tab

  2. Choose Channel ▸ Reload categories...

  3. Pick a category/genre from the overview, left.

Individual channels provide different music/radio information. The table - views are mostly identical in each tab. (You could modify the datamap[] - in the plugin files if you wanted to adapt this.)

+ views are mostly identical in each tab. Some views may rename columns, or remove + them alltogether.

Available channels

Bookmarks — Collect favourites via bookmark function, entry editing and deleting.
@@ -49,12 +50,12 @@

Channel service homepage

You can dobule click the channel tab to visit the channel/directory homepage. Alternatively there is an entry in the Channel menu.

-
-

Channel menu options

+
+

Channel menu actions

Homepage of directory service

Opens a webbrowser with the current channels website.

Reload
@@ -63,11 +64,11 @@

Starts assembling favicons for the current list of stations in the background. To actually display the freshly loaded favicons, reselect the current category.

Reload category tree

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 + change over time. So this option is often only 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.

Index: help/html/cli.html ================================================================== --- help/html/cli.html +++ help/html/cli.html @@ -5,12 +5,16 @@ CLI (command line interface)
-
+

CLI (command line interface)

Streamtuner2 is a graphical tool. But it also has a limited commandline interface, @@ -37,21 +41,24 @@

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.

-

GUI mode: There are also --gtk3 and --gtk2 command line options. Usually the right toolkit - is picked depending on Python version. But you can manually override this.

+
+

GUI options

+

There are also --gtk3 and --gtk2 command line options. Usually the right toolkit + is picked depending on Python version. But you can manually override this.

+
Index: help/html/config_apps.html ================================================================== --- help/html/config_apps.html +++ help/html/config_apps.html @@ -12,11 +12,11 @@

Audio players

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

@@ -49,16 +49,16 @@ - + - + @@ -71,11 +71,11 @@ works better. (And sometimes not.)

Some applications, like Rhythmbox or Banshee, are primarily audio browsers, not players, and cannot be invoked with a play URL by other apps. This makes them less suitable for use with streamtuner2.

-
+

URL placeholders

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.

@@ -105,16 +105,22 @@ %m3u most, while streamripper needs %srv for recording.

Index: help/html/configuration.html ================================================================== --- help/html/configuration.html +++ help/html/configuration.html @@ -11,84 +11,173 @@ ♪ Streamtuner2  › Configuration »

Settings dialog

-

There are various options for streamtuner2. - You can find the settings dialog in the edit menu as "Preferences" (last entry). -

+

+There are various options for streamtuner2, available under Edit ▸ Preferences or via F12. +

It's separated into three main areas.

Player

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.

+ It's a file type to application table. Double click an entry for editing.

Options

Influences the display of all stream/station lists, and contains some system settings.

Channel Plugins

Every channel tab can have specific options. These are configured here. - Also you can disable channels you don't need.

+ Also you can disable channels you don't need.

Player application settings

-

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.

-

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.

-

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.

-

Catch-all entries like */* or a generic audio/* entry allow to configure a default player. -

-

Recording

+

MIME types are categorzied identifiers for file types. Audio/mpeg for example represents MP3 files, + and audio/ogg means just OGG. And the player setting dialog simply associates an audio type with a + playback application:

+

Audacious

console

VLC

vlc %u

video/*

video

Totem

totem %u

video/*

video

Media Player

mplayer2.exe %pls

Win32
+ + + + + + + + + + + + + + + + + + + + + + + + +

Format

Application

audio/mpeg

audacious

audio/ogg

audacious

audio/*

vlc --one-instance

video/*

totem

video/youtube

vlc %srv

+

Application names are always lowercase binary names. Double click an entry to edit it.

+

After the application name, you can use a placeholder like "%pls" (default), + or "%m3u" and "%src". See placeholders.

+

Catch-all entries like */* or a generic audio/* entry allow to configure a default player. + While video/youtube is specific to the Youtube channel. And url/http a psdeudo MIME type + to configure a web browser (for station homepages).

+
Audio players — Common applications to use as players.
+
+
+
+

Recording Apps

+

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

-
-
Audio players — Common applications to use as players.
-
Recording — Save radio songs as MP3 files via streamripper.
-
+ Here streamripper is preconfigured for audio streams, and youtube-dl for Youtube videos for instance.

+
+ + + + + + + + +

audio/*

xterm -e streamripper %srv

video/youtube

xterm -e "youtube-dl %srv"

+

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

+
Recording — Save radio songs as MP3 files via streamripper.

Display/GUI options

-

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'll have to try.

-

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.

-

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.

+
+

Display settings

+
+
Display favicons
+

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.

+
Load favicons
+

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 Channel ▸ Update favicons... to update all + station icons at once.

+
Show bookmark star
+

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.

+
Gtk+ theme
+

Be careful. While Gtk allows to select a different theme per application, not all themes + work right away. Switching the theme might hang streamtuner2. Just restart if that happens.

+
Save window states
+

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 Edit ▸ Save States.

+
+
+
+

Station loading

+
+
Prefer HTML traversing (PyQuery) over regex
+

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 more reliable. As fallback streamtuner2 plugins + often use a regex to match text. Occassionally the regex method is actually more reliable, + because directory services often use frightful unstructured HTML. If available, both methods + are tried. You can influence the order with this setting.

+
[250] Limit stream number
+

Constraints the length of station lists per category. + 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
+

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

+
Update favouries from freshened URLs
+

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.

+
google station homepages
+

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

+
+
+
+

System

+
+
Temporary files
+

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.

+
Config directory
+

Is where streamtuner2 keeps its settings.json and channel caches, favicons, etc. + You can't set this in the config dialog. This is just for display. Set the XDG_CONFIG_HOME + environment variable to adapt.

+
Enable debug messages
+

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.

+
+

Plugin and Channel settings

-

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

-

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

-

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.

+

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.

+

Each channel plugin may come with its own set of addition configuration settings + below.

+

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.

Internet-Radio.com — Large radio directory from the UK.
MyOggRadio — Open source stream directory.
Shoutcast — One of the bigger radio station lists.
SurfMusic — International radio listings.
Index: help/html/global_key.html ================================================================== --- help/html/global_key.html +++ help/html/global_key.html @@ -5,21 +5,25 @@ Global_key
-
+

Global_key

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.

+

This is useful if you don't want to keep streamtuner2 atop your + desktop all the time, but still want to switch radios easily.

Go into settings F12 for plugins to define a keyboard shortcut:

@@ -57,14 +61,14 @@
Index: help/html/glossary.html ================================================================== --- help/html/glossary.html +++ help/html/glossary.html @@ -5,16 +5,16 @@ Glossary
-
+

Glossary

-
+
+
Channel

Each tab in the main window is a "channel". It represents one music directory service.

Stream
@@ -28,16 +28,15 @@

Music genres are represented as "categories" in the left pane. Every channel groups its music stations into some structure.

URL

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. (ISBN or - Mailto URIs don't make much sense for either.)

+ and simply refers to something retrievable hyperlinks or web addresses like + http://www.example.org/. Radio stations/streams are stored as URLs internally. + The more generic hipster term "URI" (long superseded by "IRI" anyway) + makes less sense in this context, because ISBN: or MailTo: references aren't + overly useful for such purposes.

Radio

Plays music. Sometimes interrupted by advertisements.

Favicons

Favicons are small symbols for @@ -71,11 +70,13 @@

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 e.g. 64 kbit per second. So while bitrate basically means file size per duration, it's commonly used as quality indicator.

-
+
+
Additional features
+

Filetypes

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.

@@ -84,18 +85,11 @@
.PLS files — Playlist file format.
JSON files — JavaScript Object Notation is a common data exchange format.
-
Index: help/html/index.html ================================================================== --- help/html/index.html +++ help/html/index.html @@ -60,36 +60,58 @@

Configuration

-
+
+
Settings dialog — F12 brings up the options window with the Player, Display, System and Plugin sections.
-
+
+ +
-
-

Advanced topics

-
+
+
Index: help/html/introduction.html ================================================================== --- help/html/introduction.html +++ help/html/introduction.html @@ -37,19 +37,19 @@

Double clicking an entry row in the radio list starts your audio player. But there are other functions available. Either go to the  ▸ Station menu, or access the context menu with a right click.

keyspec

corresponds to
- + - + - + Index: help/html/jamendo.html ================================================================== --- help/html/jamendo.html +++ help/html/jamendo.html @@ -16,19 +16,41 @@

Jamendo

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.

+files for individual musicians and artists. Tracks and albums can thus be downloaded +free of charge. Yeah, imagine that.

The new Jamendo v3.0 is now utilized. It allows to list albums, - playlists, and individual tracks by genre. The radio list is static - (they're looping over randomized songs from each genre.)

+playlists, and individual tracks by genre. The radio list is static +(they're looping over randomized songs from each genre.)

Instead of favicons, streamtuner2 can fetch album or track - covers. Thus the images are a bit larger, and retrieving them all - via Channel > Load favicons... takes a while longer.

+covers. Thus the images are a bit larger, and retrieving them all +via Channel ▸ Load favicons... +takes a while longer.

+
+

Config options

+
+

System

+
+
Streaming format
+

You can switch between MP3 and Ogg Vorbis audio streams for Jamendo. + It's not honored by the radio section, but albums and tracks should be + received as Ogg when configured so.

+
Preview image sizes
+

Album covers are downloaded in lieu of favicons. They're available + in different sizes. Use 25px if you want just favicon-sized icons.

+
Result length
+
+

Currently only 1 page (of 200 entries each) of album/track lists are + fetched.

+

Setting a higher value may not work.

+
+
+
+

Play

Play

Starts the radio in a configured audio player

Record

Record

Opens a terminal window and streamripper, which cuts the radio broadcast into individual mp3 songs.

Bookmarks

Bookmarks

Copy radio entry over into the bookmarks channel.

Homepage

Most radio stations have a homepage. Open this in a web browser.

+ + + + + + + + +

Format

Application

audio/*

xterm -e streamripper %srv

+

To configure a default download directory, use the -d option to streamripper. +For example xterm -e "streamripper -d /media/music/" 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.

+
+
+
+

fIcy/fPls

+
+

As alternative to streamripper, check out fIcy/fPls +for recording ICEcast/SHOUTcast streaming servers.

+

It can be configured with xterm -e "fPls %srv" simply.

+
+
+
+

Youtube-DL

+

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

+
+
+

Wget for MOD files

+

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 +table. There create a new recording MIME type audio/mod+zip with +a command like xterm -e wget %srv. Copy it alike for +audio/it+zip and audio/xm+zip to cover the most common +file types. Using curl would also work of course.

+
Index: help/html/reloading.html ================================================================== --- help/html/reloading.html +++ help/html/reloading.html @@ -12,11 +12,11 @@

Reloading

Station information can get stale. Especially Shoutcast invalidates old information - frequently. Therefore you have to [Reload] the lists. There is an action button below + 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.

Index: help/html/saving.html ================================================================== --- help/html/saving.html +++ help/html/saving.html @@ -16,17 +16,20 @@

Saving

You can export the currently selected stream using - Station ▸ Save. A file dialog - opens, where you can adapt the title. The extension of the filename - decides on the saved link format. Per default a .m3u file is - created, because most audio players understand this format.

-

But you can also save in .pls or .xspf or .asx or .smil format. - Note that the lower right dropdown has no effect. You have to edit the - filename field.

+ Station ▸ Save or + F2. A file dialog opens, where you can adapt the title. +

+

The extension of the filename decides on the saved link format. Per + default a .m3u file is created, because that's what most audio players + understand.

+

But you can also save in .pls or .xspf + or .asx or .smil format. Note that the + lower right dropdown has no effect. You have to edit the extension + into the filename field.