ShoutCast metadata protocol
Client side
When listening to a ShoutCast (or compatible) server, a client
can request to have metadata (information about the music) included
in the stream. Since ShoutCast is a popular format, support for
this kind of metadata has been built into many different clients.
Even though it's not a ShoutCast server, Ample can still use this
feature to send metadata to its clients about the songs currently
playing.
A client informs the server that it's willing to accept ShoutCast
type metadata by including the following header in its
HTTP request:
Icy-MetaData: 1
Server side
Since Ample is such a well-behaved server ;-), it does a
case-unsensitive match for "icy-metadata:" and
then makes sure that the integer that follows is positive.
The server then indicates that it has understood the clients
request for metadata and that it's going to send metadata by
doing two things: first it changes the first reply header
("HTTP/1.1 200 OK" or similar) to "ICY 200 OK",
second, it must include an "icy-metaint" header in its
HTTP reply:
ICY 200 OK
icy-metaint:16000
Some notes
The number "16000" is just an example and I will soon
explain how it is used. This line is the only one that is
mandatory as far as I know, but other ones (that I know of) will be
explained later.
The integer is an interval (in bytes) that specifies how often
metadata updates will be sent to the client. In this example,
16000 bytes of music data would be sent first, then metadata
(format will follow soon), then another 16000 bytes of music data
etc. etc.
It may seem like there will be a lot of overhead if a line like
"ZZ Top-Rough boy" (16 bytes) would be sent every 16000
bytes but that's 1/1000 of the total traffic. Also, (almost)
no data is sent when the song title hasn't changed from the last time
metadata was sent which makes the ratio in our example even lower.
Metadata message format
A metadata message starts with one byte that specifies the length,
then the message itself and last one or more NULL bytes that pad
the rest of the message and indicate the end of it.
An illustration is always nice:
- Length - One byte, the value of this byte * 16 is the length of
the rest of the message. If the title hasn't changed since the
last metadata message, this should be zero and the only
byte in the message.
- Message - Usually the title of the song currently playing,
encoded in ASCII.
- Padding - At least one zero byte must end the message and there
must be enough zeros to make the part after the length byte a
multiple of 16. Thus a message of 15 bytes would have 1 zero byte
following it and a message of 16 bytes would have 16 zero bytes
following it.
Let's add an example, if we wanted to send the song title
"U2 - One" to the client we would add the following
data to the stream:
Hex: 0x01 0x55 0x32 0x20 0x2D 0x20 0x4F 0x6E 0x65 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
ASCII: N/A U 2 SPC - SPC O n e NUL NUL NUL NUL NUL NUL NUL NUL
Other HTTP reply headers
These are other headers that can (optionally) be included with
the HTTP reply
- icy-notice1 - An informational message.
- icy-notice2 - Another informational message, probably
"icy-notice3", "icy-notice4" etc. can
also be used.
- icy-name - The name of the stream that the server is sending,
this is usually displayed along with the current song title in
clients.
- icy-genre - The genre of the music served.
- icy-url - An URL associated with the stream, usually the
homepage of the "webradio" or similar.
- icy-pub - Not sure, believe it indicates if the stream is public
or private
- icy-br - BitRate, seems mostly informational as most clients
encountered seem to support VBR (Variable BitRate).
Let's finish of with a complete example of a server reply:
ICY 200 OK
icy-notice1:This stream is served using Ample/0.5.4
icy-notice2:AMPLE - An MP3 LEnder - http://ample.sf.net/
icy-name:Ample
icy-genre:Mixed
icy-url:http://ample.sf.net/
icy-pub:1
icy-metaint:16000
icy-br:128
