View source for Icecast Server/YP-protocol-v2

This page is to document and help collaborate on drafting and later finalizing a complete revision of the Icecast YP protocol and YP server behaviour. 

== Overview ==

There continues to be a demand for listings of online radio stations. Especially player software likes to present the user with easy accessible station listings.

The Icecast stream directory at dir.xiph.org has been fulfilling those needs for years, along with some other directories. For players there is a machine readable XML export.

Over the years some deficiencies have become apparent. This revised protocol will try to address those, as well as aim to provide a structured specification to enable alternative implementations.

== Known deficiencies of the old protocol ==
* No defined way to send warnings to the submitting server, only failures
* No contact details in case directory operators need to reach a server administrator
* Multiple hacks in the POST request
* No good way to revise/extend the protocol without affecting backwards compatibility

== New to be introduced features ==
* Verification of stream availability through handshake

== Design goals for the new revision ==

== Old protocol - factual characteristics ==
This is based on current Icecast server code and the current php implementation of dir.xiph.org

=== Transport ===
The streaming server to directory communication happens over HTTP POST. Originally GET was used, but was deprecated 10 years ago and the directory stopped supporting it later on.

<code>POST /cgi-bin/yp-cgi HTTP/1.1<br>
User-Agent: Icecast 2.4.1<br>
Host: dir.xiph.org<br>
Accept: */*<br>
Content-Length: 133<br>
Content-Type: application/x-www-form-urlencoded</code>

The directory request is contained in the message body as form-urlencoded data, see [https://tools.ietf.org/html/rfc1866#section-8.2.1 RFC 1866, Section 8.2.1].

=== Request types ===

There are 3 defined request types:

* [[#Add|Add]]
* [[#Touch|Touch]]
* [[#Remove|Remove]]

==== Add ====
This type of request will add a new server entry to the directory.

The request MUST have the following parameters :

{| class="wikitable"
|-
!parameter !! value !! explanation
|-
|action || '''add''' || The YP protocol request type
|-
|sn || string || The name of the stream
|-
|type || string || content type
|-
|genre || string || genre, space delimited(?)
|-
|b || string(!?) || The expected average bitrate for the stream
|-
|listenurl || URL || the URL of the actual stream, as used by player clients
|}

The URL call will have the following *optional* parameters :
{| class="wikitable"
|-
!parameter !! value !! explanation
|-
|cpswd	||string||Cluster Password (broadcasts with the same Server Name and cluster password will be displayed together in the directory server).
|-
|user	||string||''never implemented'' YP userid
|-
|pass	||string||''never implemented'' YP password
|-
|desc	||string||Server Description
|-
|url	||url||Stream URL (not the listen url, usually a link to the broadcasters website)
|-
|stype	||string||Server Sub type. Used normally for multi-codec streams (ogg/theora, vp6/aac). Codecs should be separated by a '/' delimiter.''verify''
|}

The listing scripts will respond with the following HTTP headers
{| class="wikitable"
|-
!header !! value !! explanation
|-
|YPResponse:	||0;1||0-failure or 1-success
|-
|YPMessage:	||string||Any error message
|-
|SID:	||string||System Identifier which represents the unique identifier for the new listing entry. All futher communications must be made using this SID - the SID can be any alpha numeric string
|-
||TouchFreq:	||The frequency (in seconds) in which the listing client needs to touch the server in order to prevent a stale record
|}

'''Attention''': Even though HTTP headers are specified to be case-insensitive, Icecast versions prior to 2.4.0 and Icecast-kh do not handle them properly and will fail to parse the server response properly if the header names do not match the exact case as written above!

==== Touch ====

This type of request will update a server entry with new information. This request will also cause the listing server to acknowledge this server as one that is still valid. Periodic cleanups of inactive servers will be performed on the listing server.

The URL call will have the following mandatory parameters :

{| class="wikitable"
|-
!parameter !! value !! explanation
|-
|action || '''touch''' || The YP protocol request type
|-
|sid || string || session ID
|}

The URL call will have the following *optional* parameters :
{| class="wikitable"
|-
!parameter !! value !! explanation
|-
|st ||string||Song title
|-
|listeners||string||Current number of listeners
|-
|max_listeners||string||max listener limit for this stream
|-
|alt||string||average listening time [not implemented]
|-
|ht||string||hits / tune ins
|-
|cm||string||5min average tune ins
|-
|stype||string||Server Sub type. Used normally for multi-codec streams (ogg/theora, vp6/aac). Codecs should be separated by a '/' delimiter. - Note that since it is possible to change codecs mid stream in some container formats, so this field is updatable on a touch.
|}
The listing scripts will respond with the following HTTP headers
{| class="wikitable"
|-
!header !! value !! explanation
|-
|YPResponse:	||0;1||0-failure or 1-success
|-
|YPMessage:	||string||Any error message
|}
==== Remove ====

This type of request will remove a server entry.
This request should be done when either the broadcast has stopped, or the icecast2 server is shutting down. 

The URL call will have the following mandatory parameters :

{| class="wikitable"
|-
!parameter !! value !! explanation
|-
|action || '''remove''' || The YP protocol request type
|-
|sid || string || session ID
|}

The URL call does NOT have *optional* parameters!

The listing scripts will respond with the following HTTP headers
{| class="wikitable"
|-
!header !! value !! explanation
|-
|YPResponse:	||0;1||0-failure or 1-success
|-
|YPMessage:	||string||Any error message
|}