Difference between revisions of "SHOUTcast 2 (Ultravox 2.1) Protocol Details"

From Winamp Developer Wiki
Jump to: navigation, search
(New page: == SHOUTcast / Ultravox 2.1 Protocol == ==== Overview ==== The SHOUTcast / Ultravox Protocol is an application level streaming protocol that encapsulates stream data in order to abstract t...)
 
m
Line 1: Line 1:
== SHOUTcast / Ultravox 2.1 Protocol ==
+
==SHOUTcast 2 (Ultravox 2.1) Protocol Details==
==== Overview ====
+
====Overview====
 
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.   
 
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.
 
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 ====
+
====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 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.
  
Line 93: Line 93:
 
: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.
 
: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 ====
+
====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.
 
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.

Revision as of 17:16, 6 January 2011

SHOUTcast 2 (Ultravox 2.1) Protocol Details

Overview

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