shoutcast-search

shoutcast-search searches the shoutcast.com radio stations from your command line. It is developed and tested on Linux, but since it is written in Python it may run, or at least should be easily portable, to other operating systems.

Distribution specific links:

Why shoutcast-search?

Automatic station selection

In default mode, shoutcast-search prints the URLs of the matching radio station, with one URL per line. These lines can be fed to a media player which will start playing the selected tracks. To play a random Top 500 station in VLC for example:

$ shoutcast-search -n 1 -r | xargs vlc &

Manual station selection

shoutcast-search can also be run in verbose mode: shoutcast-search -v. This is useful in two ways.

An example of verbose output:

  $ shoutcast-search --verbose --sort=rn2l --genre=ambient
  Search summary
  ------------------------------
  Keywords:
    Genres: ambient
   Playing:
  Stations:
   Bitrate:
 Listeners:
      Type:
     Order: by sorters
    Sorter: random order | top 2 | listeners desc
     Limit: 2
    Format: %s [%bkbps %t]\\n\\t%u\\n\\t%g, %l listeners\\n\\tNow playing: %p\\n
  	      
 Bluemars - Music for the Space Traveler [128kbps audio/mpeg]
         http://yp.shoutcast.com/sbin/tunein-station.pls?id=619161
         Ambient, 139 listeners
         Now playing: HIA and Biosphere - Midpoint
   
 X-Pulse 24/7 Ambient Radio [48kbps audio/mpeg]
         http://yp.shoutcast.com/sbin/tunein-station.pls?id=255046
         Ambient, 0 listeners
         Now playing: Zero One - Affirmative
 
 2 station(s) found.

The information for each station is listed below. Copy/paste or type the URL into your shoutcast-enabled music player to play the stream.

       <station name> [<bitrate> <MIME type>]
               <URL>
               <genre>, <nr> listeners
               Now playing: <current track>

Search criteria

You can perform free-text searches on three pieces of information

The stations publish this information and they usually match pretty well. You can search for several criteria at once. All criteria must match for a station to be listed. For example searching shoutcast-search -g synth -g pop -p "depeche mode" lists all stations that have both the words "rock" and "pop" in their genre and is currently playing "depeche mode".

If you are searching for multi-word phrases, they can be enclosed in quotes. Searching for "depeche mode" requires the full string, including the single space, to be present. depeche mode requires depeche and mode to appear, the order does however not matter. Criteria are case-insensive, "Depeche MODE" and "depeche mode" give the same results.

You can also search for words or phrases without specifying which element to search. shoutcast-search metallica searches for stations with the word metallica in their genre, current song or station name. Any phrase that is not specified with an option, e.g. -p, will be used as a free text search. shoutcast-search -g rock metallica finds all stations with rock as their genre and metallica in any of genre, current song or station name. Use verbose mode to get your search right if you need to..

If you don't provide any criteria, shoutcast-search returns the current Top 500 stations.

Note: due to caching at shoutcast.com, the currently played song per station is a bit delayed an not always correct.

Filters

soutcast-search can filter stations based on quality, number of listeners and codec required.

The bitrate and number of listeners filters require an expression to compare with. The form is [=><]N where N is a positive integer. ">128" means more than 128, "=128" means exactly 128 and "<128" means less than 128. "Equals" is assumed if no operator is given, i.e. "128" is identical to "=128".

Note: you probably need to enclose the operation in quotes, depending on your shell.

-b filter stations based on their bitrate in kbps. -b ">127" returns stations with 128 kbps or more bitrate.

-l filter stations based on how many listeners they currently have. More listeners usually mean better musical quality, even though it varies depending on genre. -l ">100" returns stations with more than a hundred listeners.

Filter stations based on which codec is required for playback. Valid options are -t mpeg for MP3 or -t aacp for aacPlus. By default, both codecs are included.

Sorting

If you want more control over how the list is sorted, you can use the --sort option. You specify how you want the list sorted by entering letters and control characters in the proper order. Specifying sorters void the -r option.

Sorting is performed in written order, for example ln20r sorts the retrieved list by number of listeners, trunkates it to twenty stations and then randomizes it, giving the top twenty stations randomly sorted. ^ is used to set sort order to ascending for l and b. The default sort order is reset to descending for each new sorter.

The available sorting parameters are:

Format

You can specify how shoutcast-search prints the information for each matching stations using the -f option. The format is specified using a combination of free text and codes that are replaced with the applicable station information. For example, --format="Station name: %s" prints Station Name: <name> for each station found. %u is the default format.

The following codes are available:

Options

By default, shoutcast-search returns the found stations ordered by number of listeners. You can tell shoutcast-search to randomize the order by providing the -r option. This option is not applicable if --sort is specified.

You can tell also set a maximum number of stations to be listed by using the -n option. -n 5 returns maximum five stations. Often, it is good to specify -n 1 when piping the output to an audio player.

Order of evaluation

shoutcast-search first matches the stations against the criteria; all criteria must match. Next, the results are filtered, again all parameters must match for a station to be listed. The remaining stations are sorted, or randomized based on options, and finally the number of results are limited, if applicable.

Examples

$ shoutcast-search -n 1
$ shoutcast-search -n 1 -r -l ">50" -b ">127" -g chill
$ shoutcast-search -g rock --sort=ln5b
$ shoutcast-search -n 50 -f "%l %s"

Automation

I've have a function in my .bashrc to quickly search and start a station with mpg123:


radio() {
	killall mpg123; shoutcast-search -n 1 -t mpeg -b ">63" --sort=ln10r $* | xargs mpg123 -q -@ &
}

This function selects one random station out of the top ten most listened to playing mpeg at 64+ kbps. It also takes arguments to set new options, or change the ones set in the script, from the command line like below.

$ radio chill

Something similar can easily be put in a shell script and connected to a media button on the keyboard.

Media players

Check your audio players documentation on how to play shoutcast streams. Here follow a few examples.

$ shoutcast-search [...] | xargs vlc --one-instance &
$ killall mplayer; shoutcast-search [...] | xargs mplayer &
$ killall mpg123; shoutcast-search -t mpeg [...] | xargs mpg123 -q -@ &

More information

For a complete reference, see the man-page (man shoutcast-search).

Written by Henrik Hallberg (halhen@k2h.se). Please send me an e-mail if you find bugs, have ideas for new features or just to let me know you use the application. I'd be happy to hear from you.