The Shoutcast Protocol

The Shoutcast Protocol

I found there to be a lack of documentation about the ShoutCast protocol, but it turns out to be fairly simple. Here is what I have found by searching the Internet, and by experimentation.

ShoutCast runs on HTTP. To receive ShoutCast, simply do a GET from the server. You can in fact do this directly in your web browser. For example, if I point my browser at the club977 server I get this:

icy-notice1:<BR>This stream requires <a href="http://www.winamp.com/">Winamp</a><BR>
icy-notice2:SHOUTcast Distributed Network Audio Server/Linux v1.9.2<BR>
icy-name:CLUB 977 The 80s Channel (MP3 Pro LOW BANDWIDTH)
icy-genre:80s Pop Rock
icy-url:http://www.club977.com
Content-Type:audio/mpeg
icy-pub:1
icy-br:24

¡ ªÕçî-bå_oå÷($??G

You will have to hit the stop button on your browser or it'll keep receiving data. The odd characters at the end are the start of the MP3 data. If you save the downloaded file as an MP3, you will be able to play it in your MP3 player.

ShoutCast Tags

The first block of data are useful tags that tell us about the stream we are receiving.

icy-notice

A general information tag. I don't know if there is a limit on how many of these there are, or if there have to be any. I am ignoring these tags.

icy-name

This gives us the name of the channel we are receiving. In this example, it's CLUB977. I don't know if there is a limit on the length of this name.

icy-genre

As you might expect, this tag gives us the genre.

icy-url

Tells us the URL for the stations web site.

Content-Type

Not sure why this is here. I think that a ShoutCast stream must be MP3.

icy-pub

Indicates if the stream is public (1) or private (0).

icy-br

This final tag tells us what the stream bit rate is in kb/s

Song Information

You will have noticed that there is no information about the currently playing track. In order to get this information, we must request it in our GET request, like this GET / HTTP/1.0/r/nIcy-MetaData:1/r/n/r/n. The data that is received will now contain song information.

The first difference in the received stream is in the tags. There is an extra one:

This tells us where the song information will be. In this example, we are told that the data will be presented every 8000 bytes. That's MP3 data bytes we are talking about, so we should ignore the header information, and the song information when working out where the song data is.

The first byte of the song information is the length of the information block. This number must be multiplied by 16 to get the length in bytes, and it includes itself. The remaining space is used by tags, the only two I've found so far are as follows:

This gives us the URL of the stream, not too sure why because we know that already. We also get the name of the artist and the title of the track. I don't know if there is a set format for these, but the ones I've seen so far are all <Artist>,<Title>.

That's it, as far as I know. Fairly simple. There are a number of bits I'm not sure about, but don't seem to be that important. If you know what these are then please let me know, and I will add that information to this page.