

SHOUTCAST-SEARCH(1)                                        SHOUTCAST-SEARCH(1)


NNAAMMEE
       shoutcast-search - search shoutcast.com radio stations

SSYYNNOOPPSSIISS
       sshhoouuttccaasstt--sseeaarrcchh [OPTION]... [CRITERIUM]... [FILTER]... [KEYWORD]...

DDEESSCCRRIIPPTTIIOONN
       sshhoouuttccaasstt--sseeaarrcchh  searches  the  shoutcast.com radio stations. CRITERIA
       are used to search for station names, genres or currently played songs.
       FILTERS can be used to limit searches, for example by number of current
       listeners. Finally, KEYWORDS are used to search  freely  among  station
       names, genres and current songs. All parameters must match for stations
       to be listed. When no CRITERIA or  KEYWORDS  are  supplied,  shoutcast-
       search returns the current "Top 500" stations.

       sshhoouuttccaasstt--sseeaarrcchh uses an API provided by shoutcast.com that may only be
       used for non-commercial purposes. See the URL in SEE ALSO for API docu‐
       mentation and rules.

OOPPTTIIOONNSS
       ----vveerrssiioonn
              Show program's version number and exit.

       --hh,, ----hheellpp
              Show program's help message and exit.

       ----lliisstt--ggeennrreess
              List available genres from shoutcast.com and exit.

       --nn LLIIMMIITT,, ----lliimmiitt==LLIIMMIITT
              Set maximum number of stations to be listed.

       --rr,, ----rraannddoomm
              Sort stations randomly instead of by number of listeners

       --vv,, ----vveerrbboossee
              Verbose output, useful for getting search right.


FFOORRMMAATT
       Specifies  what  information  that should be printed about the matching
       stations. You can specify mix free text with information about the sta‐
       tion. To inserf information about a station, use the codes below.

       --ff  FFOORRMMAATT,,  ----ffoorrmmaatt==FFOORRMMAATT String describing the format for the found
       stations.

       Codes

       %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

CCRRIITTEERRIIAA
       Used to create detailed searches, for example to  search  for  stations
       with  specific  names  or artists being played. You can supply multiple
       CRITERIA of the same type, for example

           $ shoutcast-search -g Rock -g Pop

       to find stations with both "Rock" and "Pop" in the genre. This is  dif‐
       ferent from

           $ shoutcast-search -g "Rock Pop"

       where the program searches for the exact string "Rock Pop".

       --gg GGEENNRREE,, ----ggeennrree==GGEENNRREE
              Search  for  stations with the word/phrase GENRE in their listed
              genre.

       --pp SSOONNGG,, ----ppllaayyiinngg==SSOONNGG
              Search for stations with the word/phrase SONG in their currently
              played  track.  Note:  this parameter is not very precise due to
              caching in the shoutcast.com web service.

       --ss SSTTAATTIIOONN,, ----ssttaattiioonn==SSTTAATTIIOONN
              Search for stations with the word/phrase STATION in their name.

FFIILLTTEERRSS
       Filter the search results. These can NOT be used alone, you  can't  for
       example  search  for  all stations with no listeners. If no CRITERIA or
       KEYWORDS are given, the "Top 500" stations are used.

       The --bitrate and --listeners options take mathematical expressions  in
       the  form  [=><]N where N is a positive integer. ">128" means more than
       128, "=128" means exactly 128 and "<128" means less than  128.  "="  is
       assumed  if  no  operator  is given, i.e. "128" is identical to "=128".
       Note: you probably need to enclose the expression in quotes,  depending
       on your shell.

       --bb BBIITTRRAATTEE,, ----bbiittrraattee==BBIITTRRAATTEE
              Filter  stations  matching with the bitrate in kbps matching the
              BITRATE expression (see above for format).

       --ll LLIISSTTEENNEERRSS,, ----lliisstteenneerrss==LLIISSTTEENNEERRSS
              Filter stations with the number of  current  listeners  matching
              the LISTENERS expression (see above for format).

       --tt CCOODDEECC,, ----ttyyppee==CCOODDEECC
              Filter  stations  based on the codec required. Available options
              are "mpeg" for MP3 or "aacp" for aacPlus.

KKEEYYWWOORRDDSS
       In addition to CRITERIA, you can provide KEYWORDS when you  don't  care
       where  a  word  or  phrase appear. KEYWORDS are matched against station
       names, genres and current songs. Separate KEYWORDS with spaces, enclose
       multiple word KEYWORDS in quotes, for example:

           $ shoutcast-search "Depeche Mode" somebody

SSOORRTTEERRSS
       Sorting  and  pruning of the list is performed by specifying the --sort
       option. 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 random stations  matching
       the search.

       ^ reverses order for the next variable. Sort order is reset to descend‐
       ing 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.

EEXXAAMMPPLLEESS
       Normal  output  is  one  URL  per line pointing to a matching shoutcast
       stream. This can be used to start music  players  with  the  applicable
       stations  or  to  create playlists. For example, start mplayer with the
       most popular stream currently playing a Depeche Mode song:

         $ shoutcast-search -n 1 -s "Depeche Mode" | xargs mplayer

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

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

       Examples of SORTERS:

       "^b": sort by bitrate ascending.

       "ln10r": sort by bitrate descending, truncate the list to ten stations,
       randomize order. This is appropriate if you want to pick a random popu‐
       lar station.

VVEERRBBOOSSEE MMOODDEE
       shoutcast-search  can also be used in --verbose mode. This is useful to
       verify that you have provided the parameters  correctly.  Verbose  mode
       also  prints  more  information  for  each  station,  needed for manual
       searches. For example, searching for two random stations playing  ambi‐
       ent music:

          $ shoutcast-search --verbose --sort=rn2l --genre=ambient

       prints

          Search summary
          ------------------------------
           Keywords:
             Genres: ambient
            Playing:
           Stations:
            Bitrate:
          Listeners:
               Type:
              Order: by sorters
             Sorter: random order | top 2 | listeners desc
              Limit: 2

          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>

EEXXIITT SSTTAATTUUSS
       00      Successful

       11      Network error

       22      Argument error

       33      Other error

       44      No matching results found

AAUUTTHHOORR
       Written by Henrik Hallberg (halhen@k2h.se)

RREEPPOORRTTIINNGG BBUUGGSS
       Please report bugs to halhen@k2h.se

SSEEEE AALLSSOO
       http://forums.winamp.com/showthread.php?threadid=295638
       http://www.shoutcast.com http://code.k2h.se

LLIICCEENNSSEE
       Copyright (c) 2009 by Henrik Hallberg (halhen@k2h.se)

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published  by  the
       Free  Software Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it  will  be  useful,  but
       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
       Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


                             shoutcast-search-0.3          SHOUTCAST-SEARCH(1)