Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time




shoutcast-search searches the 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?

  • More powerful searches than at
  • Handy - only a terminal window away.
  • Automation.

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.

  • To adjust the search
    Getting the search can be a little tricky. shoutcast-search prints debug information about the search to help you get it right.

  • To manually choose between the stations.
    In verbose mode, the stations are listed with more information. This allows you to browse the hits and manually copy the URL for whatever station you want to listen to.

An example of verbose output:

 $ shoutcast-search --verbose --sort=rn2l --genre=ambient
 Search summary
   Genres: ambient
    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]
        Ambient, 139 listeners
        Now playing: HIA and Biosphere - Midpoint
X-Pulse 24/7 Ambient Radio [48kbps audio/mpeg]
        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>]
              <genre>, <nr> listeners
              Now playing: <current track>

Search criteria

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

  • Genre (-g)
  • Song (-p)
  • Station (-s)

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 "synth" 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 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, the currently played song per station is a bit delayed an not always correct.


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.


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:

  • ^ reverses order for the next variable. Sort order is reset to descending for each variable.
  • b sorts by bitrate.
  • l sorts by number of listeners.
  • r randomizes list.
  • n truncates the list with the number of elements that is given, for example n10.


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:

  • %u - URL to the stream
  • %g - stations genre
  • %p - currently played song
  • %s - station name
  • %b - bitrate in kbps
  • %l - number of listeners
  • %t - MIME string describing codec
  • %% - percent sign where the following character is one of the above
  • \n - newline
  • \t - tab


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.


  • Find the most listened to station:

    $ shoutcast-search -n 1

  • Find a random station with decent musical and technical quality playing chill:

    $ shoutcast-search -n 1 -r -l ">50" -b ">127" -g chill

  • Get the five most listened to rock radio stations sorted by bitrate:

    $ shoutcast-search -g rock --sort=ln5b

  • List the number of listeners and station name of the 50 most listened to stations:

    $ shoutcast-search -n 50 -f "%l %s"


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

The URL returned points to a .pls-file. This is basically a playlist file pointing to the actual audio stream (of which there usually are several per station, supposedly for load balancing). Some music players accept the .pls files, while other need to be pointed to the stream itself.

Below is a script to extract a random stream from the pls-file, and play it in MOC.

URL=$(shoutcast-search [...] -n 1 | xargs curl -s | grep File | sort -R | head -n 1 | cut -d = -f 2)
if [ ! -z $URL ]; then
    mocp -c -a $URL -p

Check your audio players documentation on how to play shoutcast streams.

More information

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

Written by Henrik Hallberg ( 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.