SHOUTcast Broadcaster

From Winamp Developer Wiki
Revision as of 03:32, 30 November 2010 by Culix (Talk | contribs)

Jump to: navigation, search

Wiki Main | Skin Developer | Visual Developer | Plug-in Developer | Online Service Developer | SHOUTcast Tools & Services | Articles Page | FAQ | Glossary

SHOUTcast Server and YP Documentation

SHOUTcast YP1.0 Protocol


The YP protocol provides a way for shoutcast servers and relays to register themselves so they are searchable on the web page and directory. The API is a collection of HTTP GET requests, which provide the necessary functionality.



Adds a new server to the database. Servers should make this call when they start up.


  • v version. Should be set to one.
  • br bitrate. Bitrate in kbs
  • p IP port for client connections
  • m maximum client connections
  • r This parameter is only provided if this server is relaying another server. If so, the value is <addr>:<port> of the relayed server.
  • t Name or title of stream
  • g Station genre
  • url URL of broadcaster
  • content Mime-type for content (audio/mpeg or audio/aacp)
  • irc IRC address of broadcaster
  • icq ICQ address of broadcaster
  • aim AIM id of broadcaster
  • sid Stream id if relevant

An HTTP response of 200 indicates the possibility of success. Further information is available in the response headers.

  • icy-response Will have the value 'ack' if successful, otherwise it will contain an error message.
  • icy-id ID assigned to the server. Value should be checked for zero, which is invalid.
  • icy-error Extended error information.
  • icy-tchfrq Touch frequency in minutes. The server should call the YP function tchsrv at this interval.


Removes a server from the database. Servers should make this call when they shut down.


  • id ID provided in response to addsrv function
  • p IP port for client connections

An HTTP response of 200 indicates the possibility of success. Further information is available in the response headers.

  • icy-response Will have the value 'ack' if successful, otherwise it will contain an error message
  • icy-error Extended error information


Periodic "touch" function that updates various information about the server. This function should be called at an interval as indicated by the icy-tchfrq response field to addsrv


  • id Server ID as provided by the addsrv function
  • p IP port for client connections
  • li Number of listeners currently connected.
  • alt Average user listen time in seconds
  • ct Current song title
  • cm Number of clients connected more than 5 minutes since last tchsrv
  • ht Number of client connects since last tchsrv

An HTTP response of 200 indicates the possibility of success. Further information is available in the response headers.

  • icy-response Will have the value 'ack' if succesful, otherwise it will contain an error message.
  • icy-error Extended error information.
  • icy-tchfrq New touch frequency
  • icy-backup If the server becomes full, clients should be redirected here.

YP1 Error List

  1. Unable to check stream connection - Cannot see your station/computer (URL: "+streamUrl+") from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
  2. If we find ‘Location:’ string in the stream content - Terms of Service violator. You are being reported.
  3. If we find ‘SlamCast’ string in the stream content - Incompatible protocol.
  4. If we find ‘HTTP/1.0 401 Unauthorized’ string in the stream content - Streams requiring authorization are not public and cannot list here.
  5. If we found ‘ICY 400 Server Full’ or ‘HTTP/1.0 400 Server Full’ string in the stream content - Cannot verify server since all listener slots are full. Please wait.
  6. If we found ‘icecast’ string in the stream content - Icecast too easy to hack YP, use SHOUTcast instead.
  7. IP ban - This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service.
  8. If website contains ‘hTtP’ - We no longer list stations utilizing the auto-popup url option
  9. Improper version - Upgrade to SHOUTcast 1.8 or newer.
  10. No station name validation - Please give your station a name (in the dsp plugin YP tab).
  11. No Genre - Please identify this station's genre (in the dsp plugin YP tab).
  12. Capacity 0 - You must have at least 1 maxuser.
  13. Improper bitrate - Invalid bitrate.
  14. Port cannot be zero.
  15. If station name contains either ‘mp3pro’ or ‘mp3 pro’ - Mp3pro format must be nsv-encapsulated to list here.
  16. Content type - We do not currently list servers not streaming AAC+, MP3, or NSV.
  17. Video streams must be at least 64kbps to list here.
  18. If bitrate > 1024 - Bitrate too large.
  19. If bitrate < 8 - Bitrate too small.
  20. touch host, id, port, listeners, alt validation error – 3
  21. listeners > 5000, host not set in the request – 99
  22. if touch filed to update DB – 100 if update count is 0, else 100 + count of updated records.
  23. If primary is not public or relay could not register for some reason - Relay url could not register. Try by making primary source public or wait till primary registers.

SHOUTcast / Ultravox 2.1 Protocol


The SHOUTcast / Ultravox Protocol is an application level streaming protocol that encapsulates stream data in order to abstract the underlying data encoding. The protocol defines the structure of the encapsulation as well as the series of handshakes necessary for setting up a streaming session. It describes the handshaking necessary between the broadcaster and the distribution point as well as the handshaking necessary between the listener and the distribution point. At this time the protocol is not codec dependent, nor is it transport dependent. The protocol is designed with network performance, compatibility, and simplicity in mind.

At a high level, the broadcaster opens a connection to the distribution point. It provides authentication information and stream details to the distribution point. The distribution point parses the provided information, authenticates the user and then either sets up for streaming the broadcast feed, or denies the broadcaster access. Similarly, a listener may connect to the distribution point, provide authentication information, and request a particular stream. The distribution point will either allow or deny the listener and if allowed will start sending stream data to the listener from it’s internal stream buffer. Recommendations for features of the distribution point buffering scheme and connection handling are also mentioned here, but are an implementation detail and the protocol may lend itself for better solutions based on the streaming architecture.

Ultravox Messages

The mechanism by which Ultravox is able to abstract the underlying stream encoding is encapsulation within a simple message structure. Once a broadcaster or listener is connected to the distribution point, Ultravox messages will be the sole communication mechanism.

The basic Ultravox message format is:

0 1 2 3 4 5 0101 1010 AAAA BBBB CCCC DDDD DDDD DDDD EEEE EEEE EEEE EEEE F…………...F 0000 0000 Sync Res QoS Class Type PayLoad Length Payload 0x00

[Sync byte5A][reserved/QoS][4 bit msg class][12 bit msg type][16 bit msg length][N byte payload][0x00 byte]

Note: All values of the message are network byte order.

Sync Byte (0x5A)

The sync byte is used to distinguish the beginning of an ultravox message. It allows the listener to seek to a potential valid frame if data gets corrupted between the distribution point and the listener.

Reserved (A) QoS (B)

QoS information may be passed in the low 4 bits of the reserve byte. The QoS is a four bit value whose high bit specifies whether this packet has to be delivered (useful for UDP). The other 3 bits are the relative priority for send queue. The high 4 bits are currently unused.

Message Class (C)

The message class is used in combination with the message type to uniquely identify an Ultravox message. The reason for separating the unique identifier into two units is for performance reasons. The message classes are defined so that the distribution point can look at the message class and decide whether it needs to examine the payload. Examining the payload requires extra parsing on the part of the distribution point and so will affect the performance when we talk about heavy load. The message classes are defined as:
class description
0x0 Operations Not Defined
0x1 Broadcaster BroadcasterDistribution point
0x2 Listener Distribution pointListener
0x3 Cacheable Metadata BroadcasterListener via distribution point
0x4 Cacheable Metadata BroadcasterListener via distribution point
0x5 Pass-through Metadata BroadcasterListener via distribution point
0x6 Pass-through Metadata BroadcasterListener via distribution point
0x7 Data Encoded data (ex: 0x7000 is MP3)
0x8 Data Encoded data (ex: 0x8003 is aac/aacplus, 0x8001 is ogg vorbis, 0x7777 is nsv)

Message Type (D)

The message type is 12 bits in the message header that specify the type of data encapsulated in the message. See Table 1 for details on specific message types.

Message Length (E)

The message length is the fifth and the sixth byte of the message header. It specifies the length of the payload following the message header.

Note: The message length does not include the trailer 0x00 byte.

Payload (F)

The payload contains the data for each message. The payload size is not restricted by the protocol. However, the protocol specifies how a broadcaster, distribution point, and listener need to negotiate and report the maximum size message that will be sent in a single datastream. Some implementations may require that the messages stay under MTU, in which case the distribution point could enforce this during max-payload-size negotiation.

Trailing 0x00

The trailing 0x00 in the payload is used by the listener to determine if a message is malformed. See the Stream Syncing section to learn about how a client finds their place in the datastream if corrupted messages are encountered.

Broadcast Messages

The broadcast protocol describes the message requests from the broadcaster to the distribution point and responses by the distribution point. The messages are used to authenticate the broadcaster, deliver details about the stream to be broadcasted, manage the stream, and terminate the stream. For most requests made by a broadcaster, the distribution point normally sends the same message class and type back to the broadcaster as a response, indicating success or failure of the request in the encapsulated payload.

The message types shown below require a payload formatted according to the following criteria:

  1. The existence of payload data is indicated by a message length > 0
  2. All payloads for broadcaster messages are ASCIIZ strings (i.e., ASCII-encoded and terminated by a ‘\0’).
  3. Parameters within the payload are separated by a single colon (“:”) character

Broadcast messages are defined as:

Class Type Description Required? Payload? Response? 0x1 0x000 N/D N/A N/A N/A 0x1 0x001 Authenticate Broadcast Yes Yes Yes 0x1 0x002 Setup Broadcast Yes Yes Yes 0x1 0x003 Negotiate Buffer Size Yes Yes Yes 0x1 0x004 Standby Yes No Yes 0x1 0x005 Terminate No No No 0x1 0x006 Flush Cached Metadata No No No 0x1 0x007 Require Listener Auth No Yes Yes 0x1 0x008 Negotiate Max Payload Size Yes Yes Yes 0x1 0x009 Request Cipher Yes No Yes 0x1 0x040 Stream mime type Yes Yes Yes 0x1 0x050 File transfer begin No Yes Yes 0x1 0x051 File transfer data No Yes Yes 0x1 0x100 Configure ICY-NAME No Yes Yes 0x1 0x101 Configure ICYGENRE No Yes Yes 0x1 0x102 Configure ICYURL No Yes Yes 0x1 0x103 Configure ICYPUB No Yes Yes

There are six major phases of broadcaster communication with the distribution point:

  1. Cipher key exchange
  2. Connect/Authentication
  3. Stream Configuration
  4. Intro/backup file transfer
  5. Standby/Data transfer
  6. Broadcast termination


1. How do I use the on-demand content features of the DNAS?
Answer: The DNAS installs with a folder called content/. Place any MP3 files inside this directory, and they're ready to be streamed on-demand. The server will even automatically generate a playlist for any individual item of content so you can have browsers automatically pass the content off to a player without having to make playlists yourself.
Example: Your server has a file called song.mp3 in the content/ folder. Your SHOUTcast Radio DNAS is running on port 8000 at
You can listen to my song <A HREF= "">here</A>
NOTE: The file song.pls DOES NOT EXIST in your content directory! If a file with the same name exists with the .mp3 extension, the DNAS will automatically generate the .pls file.
NOTE: Subdirectories DO NOT work for the content section, to help prevent malicious users from tramping around your filesystem.
2. Why does the SHOUTcast Radio directory think I'm at a different IP than I really am?
Answer: The SHOUTcast Radio directory used to run on the honor system. That was, it took you at your word on what IP you were broadcasting at. Since about twenty billion people abused that to send people to not-so-friendly sites, now the directory forces the listed IP to the same IP that sends it the info. Since many ISPs now use content caching on port 80 (the same port that directory data comes from), a different IP address can sometimes appear in the directory. There isn't any solution for this at the moment, save having your ISP disable forced proxying of your address.
3. I'm behind a firewall/proxy. Can I still use the DNAS to broadcast?
Answer: Tricky question. Users behind proxies cannot. Users behind NAT devices can, *provided* the same port the SHOUTcast Radio server runs on is set up to forward from the NAT device to the SHOUTcast Radio server. Users behind firewalls can also get a hole punched so listeners can penetrate. If broadcasters also need to get in from the outside world, you should open the hole for PortBase + 1 (i.e. id SHOUTcast Radio runs on 8000, 8001 should be open for broadcasters to get through as well.)


1. How do I use advanced mode?
Answer: Read the README that comes with the plug-in. It explains how to make things like crossfading, cd-audio, and voiceovers work. Also, there's a ScreenCam guide which will show exactly what to do.